Интеграция с ACME / Let's Encrypt

Обзор

Протокол ACME (используется Let's Encrypt и другими удостоверяющими центрами) поддерживает проверку DNS-01 для подтверждения владения доменом. DNS-01 – единственный тип проверки, который поддерживает wildcard-сертификаты (*.example.com) и не требует HTTP-сервера на целевой машине.

NexDNS предоставляет встроенные интеграции с тремя популярными ACME-клиентами, а также универсальный CLI-хук для любого клиента, поддерживающего ручные DNS-хуки.

Все ACME-интеграции требуют API-токен с правами records.read и records.write. Создайте его на странице nexdns.ru/settings/api-keys.

Данный экземпляр использует API по адресу https://api.nexdns.ru/v1. Укажите URL API в переменной окружения вашего ACME-клиента.

acme.sh

acme.sh – ACME-клиент на чистом shell. NexDNS поддерживается как встроенный DNS API-провайдер.

Выпуск сертификата

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxx"
export NEXDNS_Api="https://api.nexdns.ru/v1"
acme.sh --issue --dns dns_nexdns -d example.com -d '*.example.com'

Токен сохраняется в ~/.acme.sh/account.conf после первого запуска, поэтому при продлении экспортировать его повторно не нужно.

Продление

Продление происходит автоматически через cron. Для принудительного продления:

acme.sh --renew -d example.com

Клиент lego и Traefik

lego – ACME-клиент на Go, который также используется в Traefik для автоматического управления сертификатами. NexDNS поддерживается как DNS-провайдер.

Автономное использование

NEXDNS_API_TOKEN=nxd_xxx \
NEXDNS_API_URL=https://api.nexdns.ru/v1 \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    run

Конфигурация Traefik

Добавьте DNS challenge resolver NexDNS в конфигурацию Traefik. Ниже приведён типичный пример для docker-compose.yml:

services:
  traefik:
    image: traefik:v3
    command:
      - "--certificatesresolvers.nexdns.acme.dnschallenge=true"
      - "--certificatesresolvers.nexdns.acme.dnschallenge.provider=nexdns"
      - "--certificatesresolvers.nexdns.acme.email=admin@example.com"
      - "--certificatesresolvers.nexdns.acme.storage=/letsencrypt/acme.json"
    environment:
      NEXDNS_API_TOKEN: "nxd_xxxxxxxxxxxxxxxxxxxx"
      NEXDNS_API_URL: "https://api.nexdns.ru/v1"
    volumes:
      - letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "443:443"

volumes:
  letsencrypt:

Затем укажите resolver в labels вашего сервиса:

labels:
  - "traefik.http.routers.myapp.tls.certresolver=nexdns"
  - "traefik.http.routers.myapp.tls.domains[0].main=example.com"
  - "traefik.http.routers.myapp.tls.domains[0].sans=*.example.com"

Клиент certbot

certbot – официальный клиент Let's Encrypt. Используйте плагин DNS-аутентификации NexDNS для автоматической проверки DNS-01.

Установка плагина

pip install certbot-dns-nexdns

Создание файла учётных данных

Создайте файл ~/.nexdns/certbot-credentials.ini с вашим API-токеном:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxx
dns_nexdns_api_url = https://api.nexdns.ru/v1

Ограничьте права доступа к файлу:

chmod 600 ~/.nexdns/certbot-credentials.ini

Выпуск сертификата

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d '*.example.com'

Использование с Docker

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    certbot/dns-nexdns certonly \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d '*.example.com'

CLI-хук

Если ваш ACME-клиент поддерживает ручные DNS-хуки, вы можете использовать CLI NexDNS в качестве скрипта-хука. Это работает с любым клиентом, поддерживающим параметры --manual-auth-hook и --manual-cleanup-hook (например, certbot в ручном режиме).

certbot с CLI-хуком

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d '*.example.com'

Хук считывает переменные окружения CERTBOT_DOMAIN и CERTBOT_VALIDATION, установленные certbot, и автоматически создаёт или удаляет TXT-запись _acme-challenge.

Перед использованием хуков CLI должен быть аутентифицирован. Выполните nexdns auth token nxd_xxx или установите переменную окружения NEXDNS_TOKEN.