Автоматические TLS-сертификаты в Angie с модулем ACME / Хабр

В этой статье посмотрим на модуль ACME веб‑сервера Angie. Модуль позволяет с минимальными усилиями получить TLS‑сертификаты и автоматически их обновлять. Наверняка вы уже работали с бесплатными сертификатами от Let's Encrypt и можете задать закономерный вопрос: зачем это делать веб‑сервером, когда есть утилиты вроде certbot, acme.sh и acmebot? Для ответа нужно хотя бы один раз попробовать модуль ACME и удобство конфигурации станет очевидным.

Начнём с краткого введения в тему ACME.

Навигация по циклу

Видеоверсия

Для вашего удобства подготовлена видеоверсия этой статьи, доступна на Rutube, VKVideo и YouTube.

Протокол ACME

Сегодня мы живём в мире HTTPS‑сайтов. Практически все веб‑гиганты объединились в порыве перевода всего веба на защищённые подключения. Сайты на обычном HTTP помечаются как опасные, а браузеры отключают важные фичи. В результате этого перехода потребовался способ выдачи огромного количества TLS‑сертификатов (которые необходимы для работы HTTPS), причем бесплатно. Решением задачи стал бесплатный CA (certificate authority — удостоверяющий центр) под названием Let's Encrypt (LE). Технологическая основа работы этого CA — максимальная автоматизация и исключение участия людей. Именно для автоматизации был разработан протокол ACME (Automatic Certificate Management Environment). ACME позволил минимизировать операционные расходы в CA Let's Encrypt и позже получил поддержку в других CA.

Модуль ACME в Angie

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

Использование модуля возможно как для HTTP‑модуля, так для потокового (Stream). Модуль поддерживает работу с RSA, ECDSA‑сертификатами с HTTP‑проверками, ALPN‑проверками и с DNS‑верификацией. Сам процесс получения и продления сертификатов полностью автоматизирован и не требует ручных действий, достаточно подготовить конфигурацию. Важно, что при обновлении сертификата он автоматически загружается в память сервера, не требуя ручного обновления конфигурации.

Перейдём к практике настройки модуля и начнём с простого примера.

Использование HTTP-проверок (обычные сертификаты)

Допустим, вам необходимо получить сертификат на сайт, работающий в Интернете. Скорее всего у вас уже есть один или несколько доменов (например, site.ru, company.ru) второго уровня и конечное количество имён третьего уровня (www.site.ru, site.ru, test.site.ru и так далее)

Для обеспечения такого сайта сертификатами хорошо подходят обычные HTTP‑проверки (HTTP-01 challenge). Также можно создать несколько отдельных сертификатов (один на каждый домен второго уровня) или общий сертификат на весь сайт. У общего сертификата будет небольшое преимущество: при перенаправлениях браузеры могут переиспользовать подключение, если домен в редиректе есть в сертификате текущего подключения (HTTP/2 connection reuse). При этом максимальное количество имён хостов в таком сертификате — 100 (ограничение Let's Encrypt). Приступим к настройке Angie, исходя из описанного сценария.

Для получения сертификата необходимо описать его свойства в директиве acme_client (допустима только в контексте http). Пример:

http {
  resolver 127.0.0.53 ipv6=off;
  acme_client rsa      https://acme-v02.api.letsencrypt.org/directory key_type=rsa;
  acme_client ecdsa    https://acme-v02.api.letsencrypt.org/directory;
}

В примере показано создание двух сертификатов с ключами RSA и ECDSA. Далее мы будем использовать более современный стандарт ECDSA, который используется по умолчанию. Также вы можете заметить директиву resolver, которая необходима для работы модуля ACME. Как обычно, адрес DNS‑сервера в этой директиве должен быть доверенным. Также в нашем примере отключена работа IPv6 (ipv6=off), что полезно для избежания сюрпризов при использовании только IPv4.

В качестве адреса у нас указана рабочая директория для Let's Encrypt. Если в�� настраиваете модуль первый раз, стоит проверить конфигурацию на тестовой среде LE, чтобы не получить бан из‑за превышения лимитов LE. Большинство параметров директивы acme_client имеют значения по умолчанию, например способ проверки будет http, значение других параметров можно посмотреть в документации.

Таким образом, мы описали основные свойства для сертификатов и можно приступить к настройке сайта. Здесь всё просто:

server {
  listen 443 ssl;
  server_name site.ru www.site.ru test.site.ru company.ru;

  acme rsa;
  acme ecdsa;

  ssl_certificate         $acme_cert_rsa;
  ssl_certificate_key $acme_cert_key_rsa;
  ssl_certificate         $acme_cert_ecdsa;
  ssl_certificate_key $acme_cert_key_ecdsa;
}

Этой конфигурации будет достаточно для получения сертификата. Конечно, все доменные имена вышеприведённого сайта должны указывать на публичный IP сервера. Обратите внимание, что в конфигурации нет указания на сокет с портом 80, который используется для HTTP‑проверки. Дело в том, что Angie сам откроет нужный сокет (по умолчанию 80 порт на всех адресах сервера) и обработает запросы для HTTP‑проверок. Если вы хотите самостоятельно управлять сокетом для HTTP‑проверок, используйте директиву acme_http_port.

Следить за процессом выпуска сертификата можно в error_log или через API. Там будут как сообщения об успешной работе, так и проблемах при выпуске сертификата. Успешные сообщения имеют уровень notice. Например, сообщение о продлении:

2026/01/01 16:29:41 [notice] 1704832#1704832: certificate renewed, next renewal date: Wed Apr 22 15:31:09 2026, ACME client: ecdsa

Теперь Angie будет отслеживать сертификаты и обновлять их заранее в соответствии с настройками acme_client. Файлы сертификатов по умолчанию находятся в директории, указанной при сборке. Для Ubuntu это /var/lib/angie/acme, но этот путь можно переопределить директивой acme_client_path. При этом сервер подключает эти файлы через переменные и содержимое файлов находится в зоне разделяемой памяти. В этом месте стоит вспомнить про кэш сертификатов и ключей, который можно использовать в Angie. Он как раз предназначен для ключей и сертификатов, подключаемых через переменные.

ssl_certificate_cache max=1000 inactive=20s valid=1m;

Кроме обычной HTTP‑проверки (HTTP-01), Angie поддерживает метод TLS‑ALPN-01. Такой метод будет полезен, если вы не можете или не хотите открывать 80 TCP‑порт на сервере. Подключить его можно параметром challenge=alpn директивы acme_client и проверка будет происходить с использованием TLS и порта TCP/443.

acme_client ecdsa    https://acme-v02.api.letsencrypt.org/directory challenge=alpn;

На этом конфигурация примера завершена. Дополнение для использования в потоковом модуле: даже если вы используете только потоковый модуль, директива acme_client должна быть в контексте http. В остальном всё так же, как и с модулем HTTP.

Использование HTTP‑проверок — это не единственный вариант получить сертификат, более того, для wildcard‑сертификатов необходимо использовать DNS‑верификацию.

DNS-верификация с делегированием зоны (wildcard-сертификаты)

Использование системы DNS для проверки владения доменом даёт более широкие возможности, чем HTTP-проверки. Во-первых, с помощью DNS-проверок можно получить мультидоменные wildcard-сертификаты, которые покрывают доменное имя второго уровня (site.ru) и все доменные имена третьего уровня (*.site.ru). Обратите внимание, что wildcard распространяется только на один уровень имён, то есть доменные имена уровнем выше или ниже покрываться таким сертификатом не будут.

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

Самый удобный и простой способ задействования DNS-проверок в ACME-модуле это делегирование части зоны домена непосредственно на сервер Angie. В этом случае он выполняет функцию DNS-сервера для части зоны (а именно, хоста _acme-challenge.site.ru).

Первый этап: подготовка DNS-записей в основной зоне домена, все изменения производим в панели системы DNS-хостинга. Важно: проверьте, поддерживает ли ваш провайдер создание NS-записей для имён третьего уровня. Создаём следующие записи:

_acme-challenge.site.ru. 60    IN      NS       ns.site.ru.
             ns.site.ru. 60    IN       A       {IP_сервера}

Первая запись отдаёт управление именем (_acme‑challenge.site.ru) на DNS‑сервер ns.site.ru. Вторая запись указывает IP‑адрес для имени ns.site.ru — это и будет публичный адрес сервера с Angie.

Теперь осталось настроить директиву acme_client в контексте http на использование DNS‑проверок и сам сайт (не забываем про обязательный resolver).

http {
  resolver 127.0.0.53 ipv6=off;
  
  acme_client ecdsa    https://acme-v02.api.letsencrypt.org/directory challenge=dns;
  
  server {
    listen 443 ssl;
    
    server_name site.ru *.site.ru;
    # Короткая версия
    # server_name .site.ru;
    acme	                        ecdsa;
    
    ssl_certificate         $acme_cert_ecdsa;
    ssl_certificate_key $acme_cert_key_ecdsa;
  }
}

Как обычно, проверяем сообщения о ходе получения сертификата в error_log. Так как Angie в такой конфигурации выступает в качестве DNS‑сервера, он будет открывать 53 UDP‑порт для обработки DNS‑запросов. Для избежания конфликтов с локальным DNS‑службами можно использовать директиву acme_dns_port, в которой указать сокет с внешним IP сервера (адрес должен совпадать с записью A в зоне домена), например:

acme_dns_port 123.123.123.123:53;

На этом настройка модуля ACME для получения сертификатов через DNS‑проверки завершена. Пожалуй, это самый удобный и простой способ получения wildcard‑сертификатов.

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

Верификация с помощью хуков

Использовать хуки для получения сертификатов стоит, если стандартные методы проверок невозможно реализовать из‑за особенностей инфраструктуры. Хуки позволяют вынести действия по созданию файлов HTTP‑проверок или DNS‑записей для DNS‑проверок на внешнее приложение. При выпуске или продлении сертификата Angie отправляет запрос с параметрами проверки на указанный адрес приложения. Рассмотрим пример из документации. Конфигурация сервера Angie:

http {
  acme_client example https://acme-v02.api.letsencrypt.org/directory challenge=dns;

server {
    listen 80;
    server_name *.example.com;

    acme example;

    ssl_certificate $acme_cert_example;
    ssl_certificate_key $acme_cert_key_example;

    location @acme_hook_location {

        acme_hook example;

        fastcgi_pass localhost:9000;

        fastcgi_param ACME_CLIENT $acme_hook_client;
        fastcgi_param ACME_HOOK $acme_hook_name;
        fastcgi_param ACME_CHALLENGE $acme_hook_challenge;
        fastcgi_param ACME_DOMAIN $acme_hook_domain;
        fastcgi_param ACME_TOKEN $acme_hook_token;
        fastcgi_param ACME_KEYAUTH $acme_hook_keyauth;

        include fastcgi.conf;
    }
  }
}

Обратите внимание на локацию @acme_hook_location, именно там находится директива acme_hook, которая отвечает за обработку хуков. Остальная конфигурация локации формирует необходимые параметры для DNS‑проверки, на основе которых проксируемое приложение (по адресу localhost:9000) должно внести изменения в зону домена. Пример Perl‑приложения для обработки хука приведён ниже:

#!/usr/bin/perl

use strict; use warnings;

use FCGI;

my $socket = FCGI::OpenSocket(":9000", 5);
my $request = FCGI::Request(\*STDIN, \*STDOUT, \*STDERR, \%ENV, $socket);

while ($request->Accept() >= 0) {
    print "\r\n";

    my $client =    $ENV{ACME_CLIENT};
    my $hook =      $ENV{ACME_HOOK};
    my $challenge = $ENV{ACME_CHALLENGE};
    my $domain =    $ENV{ACME_DOMAIN};
    my $token =     $ENV{ACME_TOKEN};
    my $keyauth =   $ENV{ACME_KEYAUTH};

    if ($hook eq 'add') {

        DNS_set_TXT_record("_acme-challenge.$domain.", $keyauth);

    } elsif ($hook eq 'remove') {

        DNS_clear_TXT_record("_acme-challenge.$domain.");
    }
};

FCGI::CloseSocket($socket);

Основная работа этого скрипта должна быть реализована в виде функций DNS_set_TXT_record (создать TXT‑запись для DNS‑проверки) и DNS_clear_TXT_record (удалить запись). Конкретная реализация будет зависеть от API DNS‑хостинга либо скрипт может работать непосредственно на DNS‑сервере домена и вносить изменения в конфигурацию напрямую. Больше подробностей по работе с хуками для DNS‑проверок можно почерпнуть в статье разработчиков.

Итоги

Итак, мы разобрали основные возможности модуля ACME веб‑сервера Angie для автоматического получения и продления TLS‑сертификатов. Использование встроенных HTTP или DNS‑проверок позволяет быстро получить сертификаты для доменов без использования внешних утилит. Для нестандартных ситуаций можно использовать режим кастомных хуков. Ну и конечно, не забывайте про мониторинг дат действия сертификатов, любая автоматика может дать сбой.