acme: Модуль автоматического управления сертификатами (ACMEv2) для NGINX

Установка

Вы можете установить этот модуль в любой дистрибутив на базе RHEL, включая, но не ограничиваясь:

RedHat Enterprise Linux 7, 8, 9 и 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-acme

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-acme

Активируйте модуль, добавив следующее в начало файла /etc/nginx/nginx.conf:

load_module modules/ngx_http_acme_module.so;

Этот документ описывает nginx-module-acme v0.3.1, выпущенный 8 декабря 2025 года.

nginx-acme

nginx-acme — это модуль NGINX с реализацией протокола автоматического управления сертификатами (ACMEv2).

Модуль реализует следующие спецификации:

RFC8555 (Автоматическая среда управления сертификатами) с ограничениями:
- Поддерживается только тип вызова HTTP-01
RFC8737 (Расширение ACME TLS Application-Layer Protocol Negotiation (ALPN) Challenge)
RFC8738 (Расширение ACME IP Identifier Validation)
draft-ietf-acme-profiles (Расширение профилей ACME, версия 00)

Начало работы

checkout, configure and build NGINX at ../nginx

cd nginx-acme export NGINX_BUILD_DIR=$(realpath ../nginx/objs) cargo build --release

Результат будет находиться в `target/release/libnginx_acme.so`.

Другой способ — использовать предоставленный скрипт конфигурации:

```sh
## в директории с исходным кодом NGINX
auto/configure \
    --with-compat \
    --with-http_ssl_module \
    --add-[dynamic-]module=/path/to/nginx-acme

Результат будет находиться в objs/ngx_http_acme_module.so.

В настоящее время этот метод производит немного большую библиотеку, так как мы не указываем компоновщику выполнять LTO и удалять неиспользуемый код.

Тестирование

Репозиторий содержит набор интеграционных тестов на основе nginx-tests. Следующая команда соберет модуль и выполнит тесты:

## Путь к исходному коду nginx, по умолчанию ../nginx, если не указан.
export NGINX_SOURCE_DIR=$(realpath ../nginx)
## Путь к репозиторию nginx-tests; по умолчанию ../nginx/tests, если не указан.
export NGINX_TESTS_DIR=$(realpath ../nginx-tests)

make test

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

Как использовать

Добавьте модуль в конфигурацию NGINX и настройте его, как описано ниже. Обратите внимание, что этот модуль требует конфигурации resolver в блоке http.

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

resolver 127.0.0.1:53;

acme_issuer example {
    uri         https://acme.example.com/directory;
    # contact     admin@example.test;
    state_path  /var/cache/nginx/acme-example;
    accept_terms_of_service;
}

acme_shared_zone zone=ngx_acme_shared:1M;

server {
    listen 443 ssl;
    server_name  .example.test
                 192.0.2.1      # не поддерживается некоторыми ACME серверами
                 2001:db8::1    # не поддерживается некоторыми ACME серверами
                 ;

    acme_certificate example;

    ssl_certificate       $acme_certificate;
    ssl_certificate_key   $acme_certificate_key;

    # не парсить сертификат при каждом запросе
    ssl_certificate_cache max=2;
}

server {
    # слушатель на порту 80 необходим для обработки ACME HTTP-01 вызовов
    listen 80;

    location / {
        return 404;
    }
}

Директивы

[!ВАЖНО] Ссылка ниже отражает текущую версию разработки. См. документацию ngx_http_acme_module на nginx.org для последней выпущенной версии.

acme_issuer

Синтаксис: acme_issuer name { ... }

По умолчанию: -

Контекст: http

Определяет объект эмитента сертификатов ACME.

uri

Синтаксис: uri uri

По умолчанию: -

Контекст: acme_issuer

URL директории сервера ACME. Эта директива обязательна.

account_key

Синтаксис: account_key alg[:size] | file

По умолчанию: -

Контекст: acme_issuer

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

Допустимые значения:

ecdsa:256/384/521 для алгоритмов JSON Web Signature ES256, ES384 или ES512
rsa:2048/3072/4096 для RS256.
Путь к файлу для существующего ключа, используя один из вышеуказанных алгоритмов.

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

challenge

Синтаксис: challenge type

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

Контекст: acme_issuer

Эта директива появилась в версии 0.2.0.

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

Допустимые значения:

http-01 (http)
tls-alpn-01 (tls-alpn)

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

contact

Синтаксис: contact URL

По умолчанию: -

Контекст: acme_issuer

Устанавливает массив URL-адресов, которые сервер ACME может использовать для связи с клиентом по вопросам аккаунта. Будет использоваться схема mailto:, если не указано явно.

external_account_key

Синтаксис: external_account_key kid file

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.2.0.

Указывает идентификатор ключа kid и file с MAC-ключом для внешней авторизации аккаунта.

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

В обоих случаях ожидается, что ключ будет закодирован в base64url.

preferred_chain

Синтаксис: preferred_chain name

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.3.0.

Указывает предпочтительную цепочку сертификатов.

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

profile

Синтаксис: profile name [require]

По умолчанию: -

Контекст: acme_issuer

Эта директива появилась в версии 0.3.0.

Запрашивает профиль сертификата name у сервера ACME.

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

ssl_trusted_certificate

Синтаксис: ssl_trusted_certificate file

По умолчанию: системный CA bundle

Контекст: acme_issuer

Указывает file с доверенными сертификатами CA в формате PEM, используемыми для проверки сертификата сервера ACME.

ssl_verify

Синтаксис: ssl_verify on | off

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

Контекст: acme_issuer

Включает или отключает проверку сертификата сервера ACME.

state_path

Синтаксис: state_path path | off

По умолчанию: acme_<name>

Контекст: acme_issuer

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

Директория содержит конфиденциальное содержимое, такое как ключ аккаунта, выданные сертификаты и закрытые ключи.

Параметр off (0.2.0) отключает сохранение информации об аккаунте и выданных сертификатах на диске.

До версии 0.2.0 директория состояния не создавалась по умолчанию.

accept_terms_of_service

Синтаксис: accept_terms_of_service

По умолчанию: -

Контекст: acme_issuer

Соглашается с условиями обслуживания, на которых будет использоваться сервер ACME. Некоторые серверы требуют принятия условий обслуживания перед регистрацией аккаунта. Условия обычно доступны на веб-сайте сервера ACME, и URL будет напечатан в журнале ошибок, если это необходимо.

acme_shared_zone

Синтаксис: acme_shared_zone zone=name:size

По умолчанию: zone=ngx_acme_shared:256k

Контекст: http

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

Размер зоны по умолчанию достаточен для хранения примерно 50 ключей ECDSA prime256v1 или 35 ключей RSA 2048.

acme_certificate

Синтаксис: acme_certificate issuer [identifier ...] [key=alg[:size]]

По умолчанию: -

Контекст: server

Определяет сертификат со списком identifiers, запрашиваемых у эмитента issuer.

Явный список идентификаторов можно опустить. В этом случае идентификаторы будут взяты из директивы server_name в том же server блоке. Не все значения, принимаемые в server_name, являются допустимыми идентификаторами сертификатов: регулярные выражения и подстановочные знаки не поддерживаются.

Параметр key устанавливает тип сгенерированного закрытого ключа. Поддерживаемые алгоритмы и размеры ключей: ecdsa:256 (по умолчанию), ecdsa:384, ecdsa:521, rsa:2048, rsa:3072, rsa:4096.

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

Модуль ngx_http_acme_module поддерживает встроенные переменные, действительные в блоке server с директивой acme_certificate:

`$acme_certificate`

SSL сертификат, который можно передать в ssl_certificate.

`$acme_certificate_key`

Закрытый ключ SSL сертификата, который можно передать в ssl_certificate_key.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-acme.