ACME#

Обеспечивает автоматическое получение сертификатов с использованием протокола ACME.

При сборке из исходного кода модуль не собирается по умолчанию; его необходимо включить с помощью параметра сборки --with-http_acme_module. В пакетах и образах из наших репозиториев модуль включен в сборку.

Пример конфигурации#

Примеры конфигурации и инструкции по настройке см. в разделе Настройка ACME.

Директивы#

acme#

Синтаксис

acme имя;

По умолчанию

—

Контекст

server

Для всех доменов, указанных в директивах server_name во всех блоках server, которые ссылаются на клиент ACME с именем имя, будет получен единый сертификат; если изменится конфигурация server_name, сертификат будет обновлен для учета изменений.

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

Примечание

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

Домены со звездочкой поддерживаются только в режиме challenge=dns в acme_client.

Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA:

server {

    listen 443 ssl;
    server_name example.com www.example.com;

    ssl_certificate $acme_cert_rsa;
    ssl_certificate_key $acme_cert_key_rsa;

    ssl_certificate $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;

    acme rsa;
    acme ecdsa;
}

acme_client#

Синтаксис

acme_client имя uri [enabled=on | off] [key_type=тип] [key_bits=число] [email=email] [max_cert_size=число] [renew_before_expiry=время] [renew_on_load] [retry_after_error=off|время] [challenge=dns | http | alpn] [account_key=файл];

По умолчанию

—

Контекст

http

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

Совет

Задаваемое здесь имя клиента идентифицирует его в конфигурации Angie, позволяя сопоставить между собой директивы acme_client, acme и переменные модуля, использующие это имя; не следует путать его с именем вашего домена или сервера.

Вторым обязательным параметром является uri каталога ACME. Например, URI каталога Let's Encrypt ACME указан как https://acme-v02.api.letsencrypt.org/directory.

Примечание

Модуль ACME добавляет в контекст client именованный location @acme, который можно использовать для настройки запросов к каталогу ACME; По умолчанию в этом location задана директива proxy_pass с uri каталога, к которой можно добавить другие настройки из модуля Proxy.

Чтобы директива работала, в том же контексте должен быть настроен resolver.

Примечание

Для тестирования удостоверяющие центры обычно предоставляют отдельные тестовые среды. Например, среда тестирования Let's Encrypt — https://acme-staging-v02.api.letsencrypt.org/directory.

enabled

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

По умолчанию: on.

key_type

Тип алгоритма закрытого ключа для сертификата. Допустимые значения: rsa, ecdsa.

По умолчанию: ecdsa.

key_bits

Количество битов в ключе сертификата. По умолчанию: 256 для ecdsa, 2048 для rsa.

email

Необязательный адрес электронной почты для обратной связи; используется при создании учетной записи на сервере CA.

max_cert_size

Задает максимальный допустимый размер файла нового сертификата в байтах, чтобы зарезервировать место для нового сертификата в разделяемой памяти; чем больше число доменов, для которых запрашивается сертификат, тем больше требуется места. Этот параметр не ограничивает размер ответа ACME‑сервера; для этого используется acme_max_response_size.

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

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

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

По умолчанию: вычисляется автоматически.

renew_before_expiry

Время до истечения срока действия сертификата, когда должно начаться его обновление.

По умолчанию: 30d.

renew_on_load

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

retry_after_error

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

По умолчанию: 2h.

challenge

Задает тип верификации для ACME-клиента. Допустимые значения: dns, http, alpn.

Значение alpn включает проверку TLS-ALPN-01 и требует, чтобы Angie был собран с OpenSSL с поддержкой ALPN (не поддерживается сборками с BoringSSL и AWS-LC).

По умолчанию: http.

account_key

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

Поддерживаемые типы ключей:

  • RSA-ключи с длиной, кратной 8, в диапазоне от 2048 до 8192 бит.

  • ECDSA-ключи с длиной 256, 384 или 521 бит.

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

Следует учитывать, что ключи для ACME-клиентов создаются в том порядке, в каком соответствующие клиенты упомянуты в конфигурации в директивах acme_client, acme или acme_hook. Поэтому, если один клиент должен использовать ключ, созданный для другого, этот другой клиент должен стоять в конфигурации раньше.

Кроме того, ключи создаются только для клиентов, у которых задан параметр enabled=on.

acme_max_response_size#

Синтаксис

acme_max_response_size размер;

По умолчанию

acme_max_response_size 32k;

Контекст

http

Ограничивает максимальный размер тела ответа ACME‑сервера. Если ответ превышает это значение, запрос завершится ошибкой. Увеличьте значение, если появляются ошибки вида too big subrequest response while sending to client.

acme_client_path#

Синтаксис

acme_client_path путь;

По умолчанию

—

Контекст

http

Переопределяет путь к каталогу для хранения сертификатов и ключей, заданному при сборке с помощью параметра сборки --http-acme-client-path.

acme_dns_port#

Синтаксис

acme_dns_port порт | ip[:порт] | [ip6][:порт];

Значение по умолчанию

acme_dns_port 53;

Контекст

http

Указывает порт, который модуль использует для обработки DNS-запросов от ACME-сервера по UDP. Номер порта должен быть в диапазоне от 1 до 65535.

Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде ip:порт, так и IPv6-адреса в виде [ip6]:порт:

acme_dns_port 8053;
acme_dns_port 127.0.0.1;
acme_dns_port [::1];

Чтобы использовать номер порта 1024 или ниже, Angie должен работать с привилегиями суперпользователя.

acme_http_port#

Синтаксис

acme_http_port порт | ip[:порт] | [ip6][:порт];

Значение по умолчанию

acme_http_port 80;

Контекст

http

Указывает порт, который модуль использует для обработки HTTP‑проверок ACME. Номер порта должен быть в диапазоне от 1 до 65535.

Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде ip:порт, так и IPv6-адреса в виде [ip6]:порт:

acme_http_port 8080;
acme_http_port 127.0.0.1;
acme_http_port [::1];

Если ни один сервер не слушает указанный адрес и порт, модуль создаст отдельный слушающий сокет для HTTP‑проверок.

Чтобы использовать номер порта 1024 или ниже, Angie должен работать с привилегиями суперпользователя.

acme_hook#

Синтаксис

acme_hook имя [uri];

По умолчанию

—

Контекст

location

Директива связывает сервер с указанным ACME-клиентом. Через контекст location, где она находится, производятся вызовы обработчиков (хуков), реализуемых каким-либо внешним сервисом.

имя

Указывает соответствующий ACME-клиент.

uri

Строка с переменными; задает строку запроса для вызова обработчиков.

По умолчанию — /.

Например, следующая конфигурация передает значения переменных хука в приложение FastCGI через строку запроса:

acme_hook example uri=/acme_hook/$acme_hook_name?domain=$acme_hook_domain&key=$acme_hook_keyauth;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_pass ...;

Встроенные переменные#

$acme_cert_<имя>#

Содержимое последнего файла сертификата (если он есть), полученного клиентом с этим именем.

$acme_cert_key_<имя>#

Содержимое файла ключа сертификата, используемого клиентом с этим именем.

Примечание

Файл сертификата доступен, только если клиент ACME получил хотя бы один сертификат, а вот файл ключа доступен сразу после запуска.

$acme_hook_challenge#

Тип проверки. Возможные значения: dns, http, alpn.

$acme_hook_client#

Имя ACME-клиента, инициирующего запрос.

$acme_hook_domain#

Проверяемый домен. Если это wildcard-домен, он будет передан без префикса *..

$acme_hook_keyauth#

Строка авторизации:

  • При DNS-проверке используется как значение TXT-записи, имя которой формируется как _acme-challenge. + $acme_hook_domain + ..

  • При HTTP-проверке эта строка должна использоваться в качестве содержимого ответа, запрашиваемого ACME-сервером.

$acme_hook_name#

Имя хука. Для разных типов проверки оно может иметь разные значения и смысл:

Значение

Смысл при DNS-проверке

Смысл при HTTP-проверке

add (добавление хука)

Необходимо добавить соответствующую TXT-запись в конфигурацию DNS.

Необходимо подготовить ответ на соответствующий HTTP-запрос.

remove (удаление хука)

Можно удалить TXT-запись из конфигурации DNS.

Данный HTTP-запрос более не актуален; можно удалить ранее созданный файл со строкой авторизации.

$acme_hook_token#

Токен для проверки. При HTTP-проверке используется как имя запрашиваемого файла: /.well-known/acme-challenge/ + $acme_hook_token.