# ACME Обеспечивает автоматическое получение сертификатов с использованием [протокола ACME](https://datatracker.ietf.org/doc/html/rfc8555). При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure) `--with-http_acme_module`. В пакетах и образах из [наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages) модуль включен в сборку. ## Пример конфигурации Примеры конфигурации и инструкции по настройке см. в разделе [Настройка ACME](https://angie.software//angie/docs/configuration/acme.md#acme-config). ## Директивы ### acme | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme` имя; | |------------------------------------------------------------------------------------------|---------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | server | Для всех доменов, указанных в директивах [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name) во всех блоках [server](https://angie.software//angie/docs/configuration/modules/http/index.md#server), которые ссылаются на [клиент ACME](#acme-client) с именем имя, будет получен единый сертификат; если изменится конфигурация `server_name`, сертификат будет обновлен для учета изменений. При каждом запуске Angie для всех доменов, у которых отсутствует действующий сертификат, запрашиваются новые сертификаты. Возможные причины включают истечение срока действия сертификатов, отсутствие файлов или невозможность прочитать их, а также изменения в настройках сертификатов. #### NOTE Эта директива определяет только то, какие доменные имена включаются в запросы сертификатов; она не влияет на то, где можно использовать сертификат. Любой блок `server` может ссылаться на сертификат через переменную [$acme_cert_<имя>](#v-acme-cert-name), независимо от того, содержит ли блок директиву `acme`. Удаление `acme` из блока `server` просто исключает значения [server_name](https://angie.software//angie/docs/configuration/modules/http/index.md#server-name) этого блока из последующих запросов сертификатов, но не запрещает блоку использовать сертификат. #### NOTE Сейчас домены, заданные через регулярные выражения, не поддерживаются и будут пропускаться. Домены со звездочкой поддерживаются только в режиме `challenge=dns` в `acme_client`. Эта директива может быть указана несколько раз для загрузки сертификатов разных типов, например RSA и ECDSA: ```nginx 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 | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `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=`файл]; | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http | Определяет клиент ACME с глобально уникальным именем. Оно должно быть допустимым для каталога, представляет собой строку с переменными и будет использоваться без учета регистра. Вторым обязательным параметром является uri каталога ACME. Например, URI каталога Let's Encrypt ACME [указан](https://letsencrypt.org/getting-started/) как [https://acme-v02.api.letsencrypt.org/directory](https://acme-v02.api.letsencrypt.org/directory). #### NOTE Модуль ACME добавляет в контекст [client](https://angie.software//angie/docs/configuration/modules/http/index.md#client) именованный `location @acme`, который можно использовать для настройки запросов к каталогу ACME; По умолчанию в этом `location` задана директива [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) с uri каталога, к которой можно добавить другие настройки из модуля [Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy). Чтобы директива работала, в том же контексте должен быть настроен [resolver](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver). #### NOTE Для тестирования удостоверяющие центры обычно предоставляют отдельные тестовые среды. Например, [среда тестирования Let's Encrypt](https://letsencrypt.org/docs/staging-environment/) — [https://acme-staging-v02.api.letsencrypt.org/directory](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](#acme-max-response-size).

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

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

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

По умолчанию: вычисляется автоматически. | | `renew_before_expiry` | [Время](https://angie.software//angie/docs/configuration/configfile.md#syntax) до истечения срока действия сертификата,
когда должно начаться его обновление.

По умолчанию: `30d`. | | `renew_on_load` | Указывает, что сертификат следует принудительно обновлять
при каждой загрузке конфигурации. | | `retry_after_error` | [Время](https://angie.software//angie/docs/configuration/configfile.md#syntax) до повторной попытки,
если получить сертификат не удалось.
Если задано значение `off`,
клиент не будет снова пытаться получить сертификат после ошибки.

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

Значение `alpn` включает проверку [TLS-ALPN-01](https://datatracker.ietf.org/doc/rfc8737/) и требует,
чтобы 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-client), [acme](#id4) или [acme_hook](#acme-hook).
Поэтому, если один клиент должен использовать ключ,
созданный для другого,
этот другой клиент должен стоять в конфигурации раньше.

Кроме того, ключи создаются только для клиентов,
у которых задан параметр `enabled=on`. | ### acme_max_response_size | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_max_response_size` размер; | |------------------------------------------------------------------------------------------|------------------------------------| | По умолчанию | `acme_max_response_size 32k;` | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http | Ограничивает максимальный размер тела ответа ACME‑сервера. Если ответ превышает это значение, запрос завершится ошибкой. Увеличьте значение, если появляются ошибки вида `too big subrequest response while sending to client`. ### acme_client_path | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_client_path` путь; | |------------------------------------------------------------------------------------------|----------------------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http | Переопределяет путь к каталогу для хранения сертификатов и ключей, заданному при сборке с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure) `--http-acme-client-path`. ### acme_dns_port | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_dns_port` порт | ip[:порт] | [ip6][:порт]; | |------------------------------------------------------------------------------------------|----------------------------------------------------| | Значение по умолчанию | `acme_dns_port 53;` | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http | Указывает порт, который модуль использует для обработки DNS-запросов от ACME-сервера по UDP. Номер порта должен быть в диапазоне от 1 до 65535. Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде `ip:порт`, так и IPv6-адреса в виде `[ip6]:порт`: ```nginx acme_dns_port 8053; acme_dns_port 127.0.0.1; acme_dns_port [::1]; ``` Чтобы использовать номер порта 1024 или ниже, Angie должен работать с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). ### acme_http_port | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_http_port` порт | ip[:порт] | [ip6][:порт]; | |------------------------------------------------------------------------------------------|-----------------------------------------------------| | Значение по умолчанию | `acme_http_port 80;` | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | http | Указывает порт, который модуль использует для обработки HTTP‑проверок ACME. Номер порта должен быть в диапазоне от 1 до 65535. Также поддерживается указание IP-адреса вместе с опциональным портом. Могут быть использованы как IPv4-адреса в виде `ip:порт`, так и IPv6-адреса в виде `[ip6]:порт`: ```nginx acme_http_port 8080; acme_http_port 127.0.0.1; acme_http_port [::1]; ``` Если ни один сервер не слушает указанный адрес и порт, модуль создаст отдельный слушающий сокет для HTTP‑проверок. Чтобы использовать номер порта 1024 или ниже, Angie должен работать с привилегиями [суперпользователя](https://angie.software//angie/docs/configuration/modules/core.md#user). ### acme_hook | [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile) | `acme_hook` имя [uri]; | |------------------------------------------------------------------------------------------|--------------------------| | По умолчанию | — | | [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile) | location | Включает проверку домена с помощью хуков для [ACME-клиента](#acme-client), заданного параметром имя. Когда для выпуска или обновления сертификата требуется проверка домена, Angie формирует внутренний запрос к именованному `location`, в котором размещена эта директива. Способ обработки запроса полностью зависит от других директив, заданных в том же `location`, таких как [fastcgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass) или любого другого обработчика запросов. | имя | Имя [ACME-клиента](#acme-client),
для которого этот хук обрабатывает проверку домена. | |-------|---------------------------------------------------------------------------------------------| | uri | Строка с переменными;
задает URI запроса для вызовов хука.

По умолчанию: `/`. | Например, следующая конфигурация передает значения [переменных хука](#http-acme-variables) в приложение FastCGI через URI запроса: ```nginx 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_<имя>` Содержимое файла ключа сертификата, используемого клиентом с этим именем. #### NOTE Файл сертификата доступен, только если клиент 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`.