Модуль Apache mod_md

Директива MDActivationDelay

MDActivationDelay duration

Директива MDBaseServer

MDBaseServer on|off

MDBaseServer off

Определяет, должен ли mod_md управлять базовым сервером, расположенным вне всех VirtualHost. По умолчанию этого не происходит. Причина в том, что это может привести к неожиданным побочным эффектам. Рекомендуется настроить виртуальные хосты для всех управляемых доменов и не полагаться на глобальную конфигурацию резервного сервера.

Директива MDCAChallenges

MDCAChallenges name [ name ... ]

MDCAChallenges tls-alpn-01 http-01 dns-01

Задаёт типы проверки (в порядке предпочтения) для подтверждения права владения доменом. Модуль поддерживает методы проверки 'tls-alpn-01', 'dns-01' и 'http-01'. Модуль анализирует общую конфигурацию сервера, чтобы определить доступные методы.

Например, если сервер прослушивает порт 80, доступен метод 'http-01'. Для метода 'dns-01' требуется настроенная команда MDChallengeDns01. Метод 'tls-alpn-01' описан выше, в разделе «Проверки https:».

Автоматический выбор подходит для большинства конфигураций. Однако Apache — очень мощный сервер с множеством параметров конфигурации, поэтому не все возможные ситуации однозначны. Например, сервер может прослушивать несколько IP-адресов, некоторые из которых доступны по `https:`, а некоторые — нет.

Если настроить MDCAChallenges напрямую, автоматический выбор будет отключён. Вместо этого модуль будет использовать настроенный список проверок при обращении к серверу ACME (сервер также должен предлагать соответствующий тип проверки). Проверки выполняются в указанном порядке.

Директива MDCertificateAgreement

MDCertificateAgreement accepted

Используя mod_md для получения сертификата, вы становитесь клиентом центра сертификации (например, Let's Encrypt). Это значит, что вам необходимо прочитать и принять его условия обслуживания, чтобы понимать, что он предлагает, а также какие ограничения или требования могут применяться. mod_md не может принять такие условия за вас.

Директива MDCertificateAuthority

MDCertificateAuthority url

MDCertificateAuthority letsencrypt

URL-адреса, по которым центр сертификации предоставляет свои услуги. Вместо фактического URL-адреса можно указать 'letsencrypt' или 'buypass'.

Если настроено несколько URL-адресов, после нескольких неудачных попыток они будут проверяться по очереди. Задать частоту или задержку переключения можно с помощью директив MDRetryDelay и MDRetryFailover. По умолчанию переключение происходит примерно после половины дня попыток.

Все остальные настройки применяются к каждому из этих URL-адресов. Поэтому, например, нельзя задать для них разные значения MDExternalAccountBindings.

Для тестирования центры сертификации обычно предлагают дополнительный URL-адрес службы. Служба «test» выдаёт сертификаты, которые браузеры не считают действительными, но не так строго ограничивает частоту запросов. Это позволяет проверить собственную конфигурацию перед переходом на URL-адрес рабочей службы.

MDCertificateAuthority https://acme-staging-v02.api.letsencrypt.org/directory

Директива MDCertificateCheck

MDCertificateCheck name url

Директива MDCertificateFile

MDCertificateFile path-to-pem-file

Используется внутри MDomainSet и указывает файл, содержащий цепочку сертификатов управляемого домена. Соответствующий ключ указывается с помощью MDCertificateKeyFile.

<MDomain mydomain.com>
  MDCertificateFile /etc/ssl/my.cert
  MDCertificateKeyFile /etc/ssl/my.key
</MDomain>

Это эквивалент директивы mod_ssl SSLCertificateFile. У неё несколько вариантов применения.

Например, если вы хотите перейти от статических файлов для существующего домена к автоматизированным сертификатам Let's Encrypt. Задайте MDomainSet, укажите здесь файлы и удалите SSLCertificateFile из VirtualHosts.

В результате конфигурация будет работать как раньше, но, возможно, в ней будет меньше повторяющихся строк. Затем добавьте к ней MDRenewMode 'always', и модуль получит новый сертификат до истечения срока действия указанного в файле. После этого удалите MDCertificateFile и перезагрузите сервер.

Другой вариант применения — обновлять сертификаты Let's Encrypt с помощью других клиентов ACME, например отличного инструмента certbot. В этом случае укажите в MD файлы certbot, чтобы они работали совместно.

Директива MDCertificateKeyFile

MDCertificateKeyFile path-to-file

Используется внутри MDomainSet и указывает файл, содержащий закрытый ключ управляемого домена. Соответствующий сертификат указывается с помощью MDCertificateFile.

Это эквивалент директивы mod_ssl SSLCertificateKeyFile.

Директива MDCertificateMonitor

MDCertificateMonitor name url

MDCertificateMonitor crt.sh https://crt.sh?q=

Это часть HTML-интерфейса «server-status» и не влияет на работу самого модуля. Директива задаёт ссылку на этой странице для удобной проверки сертификатов с помощью монитора. К настроенному URL-адресу добавляется отпечаток сертификата SHA256.

Мониторы сертификатов следят за журналами Certificate Transparency (CT), отслеживая использование сертификатов для доменов. Как минимум, вы сможете увидеть, что Let's Encrypt (или настроенный вами центр сертификации) добавил ваши сертификаты в журналы CT.

Примечание: обновление журналов сертификатов и получение этих обновлений мониторами происходит с задержкой. Она зависит от конкретного журнала и монитора. Сведения о новом сертификате появятся не сразу.

Директива MDCertificateProtocol

MDCertificateProtocol protocol

MDCertificateProtocol ACME

Задаёт используемый протокол. В настоящее время поддерживается только ACME.

Директива MDCertificateStatus

MDCertificateStatus on|off

MDCertificateStatus on

Если эта функция включена, в управляемых доменах становится доступен ресурс 'https://domain/.httpd/certificate-status', возвращающий документ JSON со списком основных свойств текущего и обновлённого сертификата, если он доступен.

{
  "valid-until": "Thu, 29 Aug 2019 16:06:35 GMT",
  "valid-from": "Fri, 31 May 2019 16:06:35 GMT",
  "serial": "03039C464D454EDE79FCD2CAE859F668F269",
  "sha256-fingerprint": "1ff3bfd2c7c199489ed04df6e29a9b4ea6c015fe8a1b0ce3deb88afc751e352d"
  "renewal" : { ...renewed cert information... }
}

Директива MDChallengeDns01

MDChallengeDns01 path-to-command

Определяет программу, вызываемую при создании или удалении проверки `dns-01`. Программе передаётся аргумент `setup` или `teardown`, за которым следует имя домена. Для `setup` дополнительно передаются данные проверки. Если MDChallengeDns01Version установлено в значение 2, данные проверки также передаются аргументом при вызове `teardown`.

Эту директиву не обязательно задавать, если доступен метод проверки 'http:' или 'https:'. Однако Let's Encrypt оставляет 'dns-01' единственным доступным методом для сертификатов с подстановочными знаками. Если вам нужен такой сертификат, эту директиву необходимо настроить.

Теперь эту директиву можно использовать внутри секции MDomain, чтобы указать отдельную команду для конкретного домена. Это позволяет настроить скрипт для используемого поставщика DNS.

Подробнее см. в разделе о сертификатах с подстановочными знаками выше.

Директива MDChallengeDns01Version

MDChallengeDns01Version 1|2

MDChallengeDns01Version 1

Задаёт способ вызова команды MDChallengeDns01, например число и типы аргументов. О различиях см. MDChallengeDns01. Эта настройка является глобальной и не может различаться для разных доменов.

Директива MDCheckInterval

MDCheckInterval duration

MDCheckInterval 12h

Интервал между проверками сертификатов. По умолчанию действительность сертификатов и необходимость их обновления проверяются дважды в день. Этот интервал не соблюдается точно: модуль случайным образом добавляет к нему отклонение +/-50%. При значении по умолчанию 12 часов фактический интервал между запусками составляет от 6 до 18 часов, причём новое случайное отклонение выбирается при каждом запуске. Это помогает снизить пиковую нагрузку на серверы ACME.

Минимально допустимый интервал — 1 секунда. Не рекомендуется использовать такие короткие интервалы в рабочей среде.

Директива MDContactEmail

MDContactEmail address

Протокол ACME требует указать контактный URL-адрес при регистрации. Сейчас Let's Encrypt запрашивает адрес электронной почты (и использует его, чтобы сообщать вам об обновлениях и изменении условий обслуживания). mod_md использует адрес электронной почты из директивы MDContactEmail в конфигурации Apache, поэтому укажите там правильный адрес. Если MDContactEmail отсутствует, mod_md использует директиву ServerAdmin.

Директива MDDriveMode

MDDriveMode always|auto|manual

MDDriveMode auto

Эта директива сохранена для обратной совместимости как прежнее название MDRenewMode.

Директива MDExternalAccountBinding

MDExternalAccountBinding key-id hmac-64 | none | file

MDExternalAccountBinding none

Настраивает значения для «привязки внешней учётной записи» ACME — функции стандарта ACME, позволяющей клиентам привязывать регистрацию к существующей учётной записи на серверах ACME.

Let's Encrypt их не требует, но они нужны другим центрам сертификации ACME. Узнайте у своего центра сертификации ACME, нужны ли они и как получить эти значения. Это две строки: идентификатор ключа и значение 'hmac' в кодировке base64.

Их можно настроить глобально или для определённого MDomain. Поскольку эти значения позволяют любому пользователю регистрироваться под одной и той же учётной записью, рекомендуется ограничить разрешения на файл конфигурации, например разрешить доступ только пользователю root.

Значения также можно считывать из файла JSON. Это позволит предоставить более широкие разрешения на файл конфигурации сервера и ограничить доступ к этому файлу. Содержимое JSON:

{"kid": "kid-1", "hmac": "zWND..."}

Если изменить значения EAB, новые значения будут использованы при следующем обновлении сертификата.

Директива MDHttpProxy

MDHttpProxy url

Использует HTTP-прокси для подключения к MDCertificateAuthority. Задайте эту директиву, если веб-сервер может выходить в интернет только через прямой прокси-сервер.

Директива MDMatchNames

MDMatchNames all|servernames

MDMatchNames all

Режим `all` работает так же, как во всех предыдущих версиях. Для поиска MDomain, соответствующего VirtualHost, проверяются ServerName и ServerAlias. Благодаря этому автоматически определяется соответствие, даже если в MDomain добавлено только одно из имён.

Однако при сложных конфигурациях такой автоматический выбор имеет недостатки. Если задать для этой директивы значение `servernames`, для сопоставления будет использоваться только ServerName виртуального хоста. ServerAlias учитываться не будет. Псевдонимы по-прежнему будут добавляться в полученный сертификат, если только вы также не используете `MDMembers manual`.

Ещё одно преимущество `servernames` — гибкость при работе с поддоменами и подстановочными знаками. Можно определить один MDomain с подстановочным знаком, а для конкретных имён поддоменов создать другие MDomains.

Директива MDMember

MDMember hostname

Вместо того чтобы перечислять все имена DNS в одной строке, можно использовать MDMember, чтобы добавить их в управляемый домен.

<MDomain example.org>
    MDMember www.example.org
    MDMember mail.example.org
</MDomain>

Если директива используется в глобальном контексте, вне конкретного MD, можно указать только одно значение: 'auto' или 'manual', которое будет значением по умолчанию для всех остальных MD. Описание этих специальных значений см. в MDomain.

Директива MDMembers

MDMembers auto|manual

MDMembers auto

Определяет, добавляются ли значения ServerName и ServerAlias виртуального хоста автоматически в список имён управляемого домена.

Директива MDMessageCmd

MDMessageCmd path-to-cmd optional-args

Эта команда вызывается при наступлении одного из следующих событий для управляемого домена: "renewed", "installed", "expiring", "errored". В будущем команда может вызываться и для других событий; она должна игнорировать события, которые не умеет обрабатывать.

Это более гибкий аналог MDNotifyCmd.

MDMessageCmd /etc/apache/md-message

# will be invoked when a new certificate for mydomain.org is available as: /etc/apache/md-message renewed mydomain.com

Программа не должна блокировать выполнение, поскольку модуль будет ждать ее завершения. Код возврата, отличный от 0, считается ошибкой.

Событие 'errored' не является поводом для немедленного беспокойства, поскольку обновление запускается достаточно рано, чтобы интернет успел восстановиться. Об этом событии сообщается не чаще одного раза в час.

К событию 'expiring' следует отнестись серьезно. Оно генерируется при достижении MDWarnWindow. По умолчанию это 10% срока действия сертификата, поэтому для Let's Encrypt это сейчас означает 9 дней до истечения срока действия. Предупреждение повторяется не чаще одного раза в день.

Событие 'renewed' означает, что получен новый сертификат и сохранен в области 'staging' хранилища MD. Он будет активирован при следующем перезапуске или перезагрузке сервера.

Событие 'installed' генерируется, когда новый сертификат переносится из области staging в каталог доменов хранилища MD. Это происходит при запуске или перезагрузке сервера. В отличие от всех остальных вызовов, MDMessageCmd запускается с правами root (в системах *nix) и имеет доступ к файлам сертификатов (и ключам). При обработке этого события можно выполнять операции с сертификатами, необходимыми другим приложениям или в других форматах.

Событие 'renewing' генерируется перед запуском процесса обновления управляемого домена. Если команда по этой причине возвращает значение, отличное от 0, обновление будет отменено и повторено в следующем цикле. В некоторых кластерных конфигурациях это используется, чтобы разрешить обновление только на одном узле.

Событие 'challenge-setup:type:domain' генерируется после создания данных проверки для домена. Оно вызывается до того, как сервер ACME получает указание проверить эти данные. Тип — один из типов проверки ACME. Событие вызывается для каждого DNS-имени в MDomain. В кластерных конфигурациях это событие может использоваться для распространения файлов проверки на все узлы кластера.

Событие ocsp-errored возникает, когда для домена включен MDStapling, и указывает на ошибку при получении ответа OCSP от центра сертификации. mod_md продолжит попытки.

Директива MDMustStaple

MDMustStaple on|off

MDMustStaple off

Определяет, должен ли у запрашиваемого нового сертификата быть установлен флаг OCSP Must Staple. Если сертификат содержит этот флаг, сервер обязан отправлять ответ OCSP stapling каждому клиенту. Это работает, только если настроен mod_ssl для формирования таких ответов (см. SSLUseStapling и связанные директивы).

Директива MDNotifyCmd

MDNotifyCmd path [ args ]

Настроенный исполняемый файл запускается, когда управляемый домен зарегистрирован или обновил сертификат. В качестве дополнительных аргументов (после указанных здесь параметров) ему передается имя обрабатываемого MD. Для успешного завершения программа должна вернуть код состояния 0.

Директива MDomain

MDomain dns-name [ other-dns-name... ] [auto|manual]

Все имена в списке управляются как один управляемый домен (MD). mod_md запросит один сертификат, действительный для всех этих имен. Эта директива использует глобальные настройки (см. другие директивы MD ниже). Если для одного MD нужны особые настройки, используйте <MDomainSet>.

Для управляемого домена необходимы еще две настройки: контактный адрес электронной почты (через MDContactEmail или ServerAdmin) и MDCertificateAgreement. Адрес электронной почты из ServerAdmin используется для регистрации в центре сертификации (по умолчанию — Let's Encrypt). Центр сертификации может использовать его, чтобы сообщать вам об изменениях в своей службе или статусе ваших сертификатов.

Для второй настройки, MDCertificateAgreement, следует указать значение "accepted". Указывая его, вы подтверждаете, что принимаете условия обслуживания центра сертификации.

MDContactEmail admin@example.org
MDCertificateAgreement accepted
MDomain example.org www.example.org

<VirtualHost *:443>
    ServerName example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

<VirtualHost *:443>
    ServerName www.example.org
    DocumentRoot htdocs/www

    SSLEngine on
</VirtualHost>

В этой директиве можно использовать два специальных имени: 'manual' и 'auto'. Они определяют, должен ли управляемый домен содержать строго указанный в конфигурации список имен ('manual') или предоставлять больше удобств. В режиме 'auto' в MD добавляются все имена виртуального хоста. По умолчанию также используется режим 'auto'.

MDomain example.org

<VirtualHost *:443>
    ServerName example.org
    ServerAlias www.example.org
    DocumentRoot htdocs/root

    SSLEngine on
</VirtualHost>

MDomain example2.org auto

<VirtualHost *:443>
    ServerName example2.org
    ServerAlias www.example2.org
    ...
</VirtualHost>

В этом примере домен 'www.example.org' автоматически добавляется в MD 'example.org'. Аналогично для 'example2.org', где режим 'auto' задан явно. При добавлении новых имен ServerAlias в этот виртуальный хост они также будут добавлены в управляемый домен.

Если вы предпочитаете явно указывать все доменные имена, используйте режим 'manual'. Если имена не совпадут с ожидаемыми, в журнал будет записана ошибка.

Директива <MDomainSet>

<MDomainSet dns-name [ other-dns-name... ]>...</MDomainSet>

Это директива MDomain с дополнительной возможностью задать настройки только для этого MD. Фактически, вместо нее можно использовать сокращенную форму "<MDomain ..>".

Это позволяет настроить MD для использования другого центра сертификации, задать иные требования к обновлению и т. д.

<MDomain sandbox.example.org>
    MDCertificateAuthority   https://someotherca.com/ACME
</MDomain>

Частый вариант использования — отдельная настройка требований https: для ваших доменов.

<MDomain example.org>
    MDRequireHttps temporary
</MDomain>

Директива MDPortMap

MDPortMap map1 [ map2 ]

MDPortMap http:80 https:443

Протокол ACME предоставляет два способа проверки владения доменом через HTTP: один использует URL 'http:' (порт 80), другой — URL 'https:' (порт 443). Если сервер недоступен хотя бы по одному из этих способов, ACME может работать только при настройке DNS-сервера; см. MDChallengeDns01.

На большинстве общедоступных серверов запросы 'http:' поступают на порт 80, а 'https:' — на порт 443. Модуль проверяет порты, на которых прослушивает запросы сервер Apache, и считает, что они доступны. Это означает, что если сервер не прослушивает порт 80, модуль предполагает, что запросы 'http:' из интернета не будут работать.

Это разумное предположение, но оно может быть неверным. Например, Apache может прослушивать порт 80, но брандмауэр может его блокировать. 'http:' доступен только во внутренней сети. Поэтому модуль ошибочно предположит, что Let's Encrypt может использовать на вашем сервере проверки 'http:'. Это приведет к сбою, поскольку брандмауэр отбросит такие запросы.

MDPortMap http:- https:8433

В примере выше показано, как указать, что запросы 'http:' из интернета никогда не будут поступать. Кроме того, в нем указано, что запросы 'https:' будут поступать на локальный порт 8433.

Это необходимо при настроенной переадресации портов: сервер может быть доступен из интернета по порту 443, но локальный порт, используемый httpd, может отличаться. Сервер может прослушивать только порты 8443 и 8000, но быть доступным из интернета по портам 443 и 80.

Директива MDPrivateKeys

MDPrivateKeys type [ params... ]

MDPrivateKeys RSA 2048

Определяет типы закрытых ключей, генерируемых для управляемого домена, и их параметры. Можно настроить несколько типов закрытых ключей; модуль получит сертификат для каждого ключа.

Например, можно настроить ключи RSA и эллиптической кривой (EC), чтобы для домена были созданы два сертификата. При подключении клиента будет использоваться первый сертификат, поддерживаемый клиентом.

Поскольку ключи и сертификаты EC имеют меньший размер, их можно предлагать в первую очередь всем совместимым (современным) клиентам. Это может ускорить рукопожатие. Добавьте тип ключа RSA для поддержки более старых клиентов.

MDPrivateKeys secp256r1 rsa3072

Поддерживаемые типы EC зависят от используемого центра сертификации. Let's Encrypt поддерживает, в частности, кривые 'secp256r1' и 'secp384r1'.

Каждый тип ключа и сертификата хранится в отдельном файле в хранилище MD. Тип ключа входит в имя файла; для сертификатов RSA используется некоторое количество обратно совместимых соглашений об именовании. Поэтому эти файлы можно продолжать использовать совместно с другими приложениями.

Обратите внимание, что эта настройка влияет только на новые ключи. Имеющиеся закрытые ключи не изменяются. Кроме того, настройка влияет только на закрытые ключи, генерируемые для сертификатов. На ключи учетных записей ACME она не влияет.

Директива MDProfile

MDProfile name

Эта директива относится к нестандартному расширению ACME от Let's Encrypt.

Let's Encrypt объявила, что в 2025 году добавит поддержку профилей сертификатов в свой центр сертификации, начиная с тестовых серверов. Помимо прочего, профили позволят выбирать срок действия получаемых сертификатов. Профиль "default" сохранит срок в 90 дней, а профиль "tlsserver" будет выдавать сертификаты со сроком действия всего 6 дней.

Если не менять конфигурацию mod_md, вы продолжите получать сертификаты сроком на 90 дней. Если вы считаете, что более короткий срок действия вам подходит (и готовы к гораздо более частому обновлению), можно настроить профиль с помощью 'MDProfile tlsserver'.

Имена профилей определяются центром сертификации. Если настроенный профиль недоступен, профиль использоваться не будет, а сертификат будет выпущен согласно настройкам по умолчанию центра сертификации.

См. MDProfileMandatory, чтобы узнать, как отключить профили по умолчанию.

Директива MDProfileMandatory

MDProfileMandatory on|off

MDProfileMandatory off

Определяет, является ли настроенный вами MDProfile обязательным. Если профиль обязательный, а центр сертификации его не предлагает, обновление сертификата завершится ошибкой.

Если профиль необязательный и центр сертификации его не предлагает, сертификаты будут обновляться без указания профиля, а центр сертификации выпустит сертификаты согласно настройкам по умолчанию.

Директива MDRenewMode

MDRenewMode always|auto|manual

MDRenewMode auto

В режиме 'auto', используемом по умолчанию, модуль действует наиболее подходящим образом для каждого управляемого домена. Для домена без сертификатов он получит их от центра сертификации.

Однако если вы определили MD, который не используется ни одним виртуальным хостом Apache, модуль не будет выполнять для него никаких действий. Для MD со статическими файлами сертификатов (см. MDCertificateFile) предполагается, что сертификаты поступают из другого источника, поэтому модуль также не будет их обновлять.

Поведение по умолчанию можно изменить. Если указать 'always', модуль будет обновлять сертификаты MD независимо от того, используются ли домены и имеются ли статические файлы.

Чтобы добиться обратного эффекта, настройте 'manual'; тогда обновление выполняться не будет.

Директива MDRenewWindow

MDRenewWindow duration

MDRenewWindow 33%

Если срок действия сертификата станет меньше указанного интервала, mod_md получит новый подписанный сертификат.

Обычно сертификаты действуют около 90 дней, и mod_md начинает их обновление не раньше, чем пройдет 33% от всего срока действия (то есть для сертификата со сроком действия 90 дней — за 30 дней до истечения срока). Если вам это не подходит, можно указать точное время, например:

# 21 days before expiry
MDRenewWindow 21d 
# 30 seconds (might be close)
MDRenewWindow 30s
# 10% of the cert lifetime
MDRenewWindow 10%

В режиме автоматической работы модуль будет не реже чем раз в 12 часов проверять состояние управляемых доменов и определять, нужно ли что-либо делать. При ошибках, например если центр сертификации недоступен, сначала повторная попытка будет предпринята через несколько секунд. Если ошибки продолжатся, интервал постепенно увеличится до максимума — проверки раз в час.

Директива MDRequireHttps

MDRequireHttps off|temporary|permanent

MDRequireHttps off

Эта удобная директива упрощает переход управляемых доменов с http: на https:. С помощью:

MDRequireHttps temporary

вы указываете, что на данный момент хотите перенаправлять весь трафик по URL http: на URL https:. Это безопасно, и эту настройку можно в любой момент удалить.

Это имеет последствия: если вы хотите, чтобы клиенты перестали использовать URL http:, настройте:

MDRequireHttps permanent

Это дает два результата:

1. Все запросы к ресурсам http: перенаправляются на тот же URL со схемой https: с использованием кода состояния 301. Это сообщает клиентам, что перенаправление будет постоянным, и им следует соответствующим образом обновить все имеющиеся ссылки.
2. Все ответы на запросы https: будут содержать заголовок Strict-Transport-Security со сроком действия в полгода. Это сообщает браузеру, что в течение полугода ему никогда не следует использовать http: при обращении к этому доменному имени. Увидев этот заголовок, браузеры откажутся обращаться к вашему незашифрованному сайту. Это препятствует понижению уровня защиты соединения вредоносными посредниками, а также прослушиванию и изменению трафика. Это полезно, но отменить такое решение простым способом не получится.

В целом, того же результата можно добиться с помощью mod_alias и некоторых настроек Redirect. Если вы настраиваете это самостоятельно, обязательно исключите пути /.well-known/* из перенаправления, иначе у mod_md могут возникнуть проблемы с получением новых сертификатов.

Если задать эту директиву глобально, она будет применяться ко всем управляемым доменам. Чтобы включить ее только для определенного домена, используйте:

<MDomain xxx.yyy>
  MDRequireHttps temporary
</MDomain>

Директива MDRetryDelay

MDRetryDelay duration

MDRetryDelay 5s

Время ожидания после ошибки перед новой попыткой обновить сертификат. После каждой последующей ошибки этот интервал удваивается, но не может превышать 24 часов.

Для каждого обновления сертификата интервал отслеживается отдельно. Это означает, что ошибка в одном MDomain не задерживает обновление других доменов.

Директива MDRetryFailover

MDRetryFailover number

MDRetryFailover 13

Количество последовательных ошибок при обновлении сертификата, после которого выбирается другой центр сертификации. Применяется только к конфигурациям, в которых указано более одного MDCertificateAuthority.

Директива MDServerStatus

MDServerStatus on|off

MDServerStatus on

Обработчик 'server-status' в Apache позволяет настроить ресурс для мониторинга происходящего на сервере. Теперь в него входит раздел со списком всех управляемых доменов, их DNS-именами, статусом обновления, сроками действия и основными свойствами.

Эту функцию можно отключить с помощью данной директивы.

Директива MDStapleOthers

MDStapleOthers on|off

MDStapleOthers on

Эта настройка действует, только если включен MDStapling. Она определяет, должен ли mod_md также предоставлять данные stapling для сертификатов, которыми он напрямую не управляет, например сертификатов, обновленных через центр сертификации ACME.

Директива MDStapling

MDStapling on|off

MDStapling off

mod_md реализует предоставление данных OCSP stapling. Это альтернатива реализации, предоставляемой mod_ssl. Для обеспечения обратной совместимости эта функция по умолчанию отключена.

Stapling можно включить для всех сертификатов сервера или для отдельного MDomain. При этом для этих узлов заменяется любая конфигурация stapling в mod_ssl. Если функция отключена, stapling mod_ssl будет выполнять эту работу (если он, конечно, включен). Это позволяет постепенно перейти с одной реализации на другую.

Stapling с помощью mod_md работает также для доменов, сертификатами которых этот модуль не управляет (см. MDStapleOthers, чтобы узнать, как управлять этим поведением). Это позволяет использовать новый механизм stapling без управления сертификатами ACME.

Директива MDStaplingKeepResponse

MDStaplingKeepResponse duration

MDStaplingKeepResponse 7d

Этот временной интервал определяет, когда данные ответов OCSP, используемые для stapling, удаляются из хранилища. Информация об ответах старше 7 дней (значение по умолчанию) удаляется при перезапуске или перезагрузке сервера. Это предотвращает увеличение размера хранилища при частом обновлении или перенастройке сертификатов.

Директива MDStaplingRenewWindow

MDStaplingRenewWindow duration

MDStaplingRenewWindow 33%

Если до истечения срока действия ответа OCSP, используемого для stapling, остается меньше duration, mod_md получит новый ответ OCSP.

Центр сертификации, выпустивший сертификат, обычно также управляет службой OCSP responder и определяет срок действия подписанного им ответа о действительности сертификата. Чем дольше действует ответ, тем дольше его можно кэшировать, что повышает общую производительность для всех. Чем короче срок действия, тем быстрее сведения об отзыве сертификата доходят до клиентов. Также следует учитывать надежность службы.

Настраивая интервал обновления stapling, вы можете частично управлять этим самостоятельно. Если задать короткий интервал обновления (например, незадолго до истечения срока действия текущей информации), кэширование будет максимально эффективным. Но сбой службы (например, из-за технического обслуживания) повлияет на вас. Если обновлять информацию задолго до истечения срока действия, обновления будут выполняться чаще, увеличивая нагрузку на инфраструктуру серверов центра сертификации, а также требуя дополнительной координации между дочерними процессами вашего сервера.

Значение по умолчанию — 33%. Это означает, что обновление начинается, когда остается треть срока действия ответа. Если центр сертификации выдает ответы OCSP со сроком действия 3 дня, информация будет кэшироваться 2 дня, а на попытки обновления останется 1 день. Чтобы повлиять на ваши домены, сбой службы должен будет продолжаться все 24 часа.

Также можно задать абсолютный интервал обновления, например `2d` (2 дня).

Директива MDStoreDir

MDStoreDir path

MDStoreDir md

Определяет расположение данных управляемых доменов в локальной файловой системе. Указывается абсолютный путь или путь относительно корневого каталога сервера. По умолчанию в корневом каталоге сервера создается каталог 'md'.

Если вы меняете расположение уже существующих данных, сначала обязательно переместите или скопируйте их в новое место, затем измените конфигурацию и перезапустите сервер. Если сначала изменить конфигурацию и перезапустить сервер, он попытается получить новые сертификаты, поскольку будет считать, что имеющиеся отсутствуют.

Директива MDStoreLocks

MDStoreLocks on|off|duration

MDStoreLocks off

Включите эту настройку, чтобы при запуске сервера использовать файл блокировки во время синхронизации MDStoreDir с конфигурацией сервера и активации обновленных сертификатов.

Блокировка предназначена для кластерных конфигураций с общей файловой системой для MDStoreDir. Она защищает активацию обновленных сертификатов, если узлы кластера одновременно перезапускаются или перезагружаются. Для этого общая файловая система должна поддерживать блокировку файлов.

По умолчанию на получение блокировки отводится 5 секунд. Если получить блокировку не удастся, в журнал будет записана ошибка, но запуск сервера продолжится. В результате узел кластера может продолжить использовать предыдущий сертификат.

Более длительное время ожидания снизит вероятность этого, но может задержать запуск или перезагрузку сервера, если блокировки неправильно обрабатываются базовой файловой системой. Экземпляр httpd должен удерживать блокировку лишь короткое время.

Директива MDWarnWindow

MDWarnWindow duration

MDWarnWindow 10%

Описание формата указания времени см. в MDRenewWindow.

Модуль проверяет оставшийся срок действия сертификатов и вызывает MDMessageCmd, если до истечения срока остается меньше времени, чем задано в окне предупреждения. При настройках по умолчанию это означает 9 дней для сертификатов Let's Encrypt.

Это также относится к управляемым доменам со статическими файлами сертификатов (см. MDCertificateFile).