Let's Encrypt с проверкой DNS-01

Введение

Что такое проверка DNS-01?

DNS-01 — это альтернативный метод проверки ACME (Automated Certificate Management Environment), который подтверждает владение доменом через DNS-записи типа TXT вместо HTTP-запросов. Когда вы запрашиваете сертификат с помощью DNS-01:

1. Сервер ACME (Let's Encrypt) предоставляет уникальный токен.
2. Ваш сервер animails автоматически создает DNS-запись TXT _acme-challenge.yourdomain.com с этим токеном.
3. Let's Encrypt опрашивает DNS для подтверждения существования записи.
4. После подтверждения ваш сертификат выпускается.

animails использует acme.sh для обработки валидации DNS-01, поддерживая более 150 DNS-провайдеров через их API.

Когда использовать DNS-проверку

Рассмотрите возможность использования проверки DNS-01, если вам требуется:

• Wildcard-сертификаты (*.example.com) — HTTP-01 не может выпускать сертификаты на поддомены общего вида.
• Серверы за файерволом — порт 80 (HTTP) заблокирован или недоступен извне.
• Сложные настройки обратного прокси — HTTP-валидация может попасть на неверный сервер.
• Несколько серверов с одним доменом — запрос HTTP может достичь другого сервера.
• Снижение внешнего воздействия — нет необходимости открывать порт 80 для интернета.

Когда НЕ использовать DNS-проверку

Придерживайтесь стандартной проверки HTTP-01, если:

• У вас простая конфигурация с одним сервером и открытым доступом по HTTP (проще в настройке).
• Ваш DNS-провайдер не предоставляет доступ по API или не поддерживается acme.sh.
• Вы не можете автоматизировать доступ к DNS API из-за организационных ограничений.
• Вам не нужны wildcard-сертификаты.

Метод по умолчанию

animails по умолчанию использует проверку HTTP-01, которая отлично подходит для большинства установок. Переключайтесь на DNS-01 только при наличии специфической необходимости.

---

Предварительные условия

Перед включением проверки DNS-01 убедитесь, что у вас есть:

1. animails версии 2026-03 или новее
2. Учетные данные API от вашего DNS-провайдера с правами на редактирование DNS-записей
3. Понимание структуры вашей DNS-зоны (каким доменам/поддоменам нужны сертификаты)

---

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

Шаг 1: Включите DNS-проверку в animails.conf

Отредактируйте /opt/animails/animails.conf и добавьте или измените следующие параметры:

# Включить проверку DNS-01 (вместо HTTP-01)
ACME_DNS_CHALLENGE=y

# Укажите плагин вашего DNS-провайдера (см. список ниже)
# Пример: dns_servercow для Servercow, dns_cf для CloudFlare, dns_aws для AWS Route53
ACME_DNS_PROVIDER=dns_servercow

# Email-адрес для регистрации аккаунта ACME
ACME_ACCOUNT_EMAIL=admin@example.com

Важные настройки

• Когда ACME_DNS_CHALLENGE=y, animails будет игнорировать параметр SKIP_HTTP_VERIFICATION (это подразумевается автоматически).
• Порт 80 не требуется для DNS-проверки.
• Все домены в вашей установке animails будут использовать DNS-01 (нельзя смешивать HTTP-01 и DNS-01).

Шаг 2: Настройте учетные данные DNS-провайдера

Создайте или отредактируйте файл /opt/animails/data/conf/acme/dns-01.conf:

# Пример для Servercow
SERVERCOW_API_Username="servercow-api-username"
SERVERCOW_API_Password="servercow-api-password"

Шаг 3: Примените конфигурацию

Перезапустите контейнер acme-animails, чтобы применить изменения:

docker compose (Plugin)docker-compose (Standalone)

cd /opt/animails
docker compose up -d

cd /opt/animails
docker-compose up -d

Шаг 4: Мониторинг запроса сертификата

Следите за логами, чтобы убедиться, что DNS-проверка работает:

docker compose (Plugin)docker-compose (Standalone)

docker compose logs -f acme-animails

docker-compose logs -f acme-animails

---

Поддерживаемые DNS-провайдеры

animails использует плагины DNS API от acme.sh. Поддерживается более 150 провайдеров.

Уровень 1: Полностью протестированные и рекомендуемые

Провайдер	Имя плагина	Необходимые учетные данные	Документация
Servercow	dns_servercow	SERVERCOW_API_Username, SERVERCOW_API_Password	Servercow API
CloudFlare	dns_cf	CF_Token, CF_Account_ID	CloudFlare DNS API
AWS Route53	dns_aws	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY	Route53 API
Azure DNS	dns_azure	AZUREDNS_SUBSCRIPTIONID, AZUREDNS_TENANTID, AZUREDNS_APPID, AZUREDNS_CLIENTSECRET	Azure API
Google Cloud DNS	dns_gcloud	CLOUDSDK_ACTIVE_CONFIG_NAME	GCloud API
DigitalOcean	dns_dgon	DO_API_KEY	DigitalOcean API

Уровень 2: Протестированные сообществом

Провайдер	Имя плагина	Примечания
Hetzner	dns_hetzner	Популярен в Германии/Европе
OVH	dns_ovh	Европейский провайдер
Namecheap	dns_namecheap	Требуется пароль DDNS, не стандартный API
GoDaddy	dns_gd	Требуются API key + API secret
Linode	dns_linode	API токен
DNSimple	dns_dnsimple	API токен

Полный список провайдеров: Документация acme.sh DNS API (150+ провайдеров)

Провайдера нет в списке?

Если ваш провайдер поддерживает DNS API и указан в документации acme.sh, он должен работать с animails. Проверьте вики acme.sh для уточнения деталей конфигурации.

---

Wildcard-сертификаты

Проверка DNS-01 — это единственный способ получить wildcard-сертификаты от Let's Encrypt.

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

Отредактируйте animails.conf:

MAILCOW_HOSTNAME=mail.example.com
ADDITIONAL_SAN=*.example.com,example.com
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_servercow

Ограничения Wildcard

• *.example.com охватывает mail.example.com, webmail.example.com, smtp.example.com и т. д.
• *.example.com НЕ охватывает основной домен example.com.
• Вы должны явно добавить оба варианта: ADDITIONAL_SAN=*.example.com,example.com

---

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

Пример 1: Servercow с Wildcard

Сценарий: animails размещен на Servercow, один домен с wildcard-сертификатом.

animails.conf:

MAILCOW_HOSTNAME=mail.example.com
ADDITIONAL_SAN=*.example.com,example.com

# Конфигурация проверки DNS-01
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_servercow
ACME_ACCOUNT_EMAIL=admin@example.com

data/conf/acme/dns-01.conf:

# Учетные данные Servercow API
# Получить на: https://cp.servercow.de
# API > API Users > Создать нового пользователя или использовать существующего
SERVERCOW_API_Username="vash-servercow-api-username"
SERVERCOW_API_Password="vash-servercow-api-password"

Создание пользователя Servercow API:

1. Войдите в Панель управления Servercow.
2. Перейдите в API > API Users.
3. Нажмите Create API User или используйте существующего.
4. Запишите имя пользователя и пароль.
5. Убедитесь, что у пользователя API есть разрешения на управление DNS.

---

Пример 2: CloudFlare с Wildcard

Сценарий: Малый бизнес, один домен, нужен wildcard-сертификат для всех поддоменов.

animails.conf:

MAILCOW_HOSTNAME=mail.example.com
ADDITIONAL_SAN=*.example.com,example.com

# Конфигурация проверки DNS-01
ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_cf
ACME_ACCOUNT_EMAIL=admin@example.com

data/conf/acme/dns-01.conf:

# Токен CloudFlare API (НЕ Global API Key!)
# Создать на: https://dash.cloudflare.com/profile/api-tokens
# Разрешения: Zone > DNS > Edit для зоны 'example.com'
CF_Token="vash_cloudflare_api_token"
CF_Account_ID="vash_cloudflare_account_id"

Создание токена CloudFlare API:

1. Перейдите в Панель управления CloudFlare.
2. Нажмите "Create Token".
3. Используйте шаблон "Edit zone DNS" или создайте кастомный токен с:
   • Разрешениями: Zone > DNS > Edit
   • Ресурсами зоны: Include > Specific zone > example.com
4. Скопируйте токен (показывается только один раз!).

---

Пример 3: Hetzner (Германия)

Сценарий: Немецкий хостинг-провайдер, популярен в Европе.

Для доменов в новой консоли "Hetzner Console":

animails.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_hetznercloud
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# Токен Hetzner API
# Create a read-write token like described here: https://docs.hetzner.com/cloud/api/getting-started/generating-api-token/
HETZNER_TOKEN="vash-hetzner-api-token"

Для доменов в старой консоли "DNS Console":

animails.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_hetzner
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# Токен Hetzner DNS API
# Create at: https://dns.hetzner.com/settings/api-token
HETZNER_Token="vash-hetzner-api-token"

---

Пример 4: IONOS (Германия)

Сценарий: IONOS (ранее 1&1), немецкий провайдер.

animails.conf:

MAILCOW_HOSTNAME=mail.example.de
ADDITIONAL_SAN=*.example.de

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_ionos
ACME_ACCOUNT_EMAIL=admin@example.de

data/conf/acme/dns-01.conf:

# Ключ IONOS API
# Get from: IONOS customer area under Developer Tools
IONOS_API_KEY="vash-ionos-api-key"

---

Пример 5: AWS Route53 (Несколько доменов)

Сценарий: Несколько доменов на AWS, корпоративная среда.

animails.conf:

MAILCOW_HOSTNAME=mail.company.com
ADDITIONAL_SAN=smtp.company.com,mail.division.org

ACME_DNS_CHALLENGE=y
ACME_DNS_PROVIDER=dns_aws
ACME_ACCOUNT_EMAIL=admin@company.com

data/conf/acme/dns-01.conf:

# AWS IAM User Credentials
# IAM User: animails-acme-dns
# Policy: Attached custom policy (see below)
AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Рекомендуемая политика IAM (минимальные привилегии):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "route53:GetChange",
        "route53:ListHostedZones"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "route53:ChangeResourceRecordSets"
      ],
      "Resource": "arn:aws:route53:::hostedzone/Z1234567890ABC"
    }
  ]
}

Замените Z1234567890ABC на ваш реальный ID зоны.

---

Дополнительные ресурсы

• Документация acme.sh DNS API — полный список из 150+ провайдеров с примерами.
• Типы проверок Let's Encrypt — официальное объяснение HTTP-01 против DNS-01.
• Лимиты Let's Encrypt — ограничения на выпуск сертификатов.
• Документация animails по SSL (HTTP-01) — Стандартная выдача сертификатов на основе HTTP
• Настройка обратного прокси-сервера animails — Использование animails за обратными прокси-серверами
• Предварительные требования animails к DNS — DNS-записи, необходимые для работы почты