Как получить wildcard SSL‑сертификат Let's Encrypt с помощью acme.sh

Зачем нужен wildcard‑сертификат

Wildcard‑сертификат (например, *.example.com) покрывает все поддомены родительского домена: www.example.com, api.example.com, mail.example.com и т. д. Это упрощает выдачу и обновление сертификатов для множества сервисов — вместо управления отдельными сертификатами для каждого поддомена вы управляете одним.

Важно: wildcard‑сертификат защищает только один уровень поддоменов (.example.com) и не подходит для разноуровневых цепочек вроде .sub.example.com.

Что потребуется

• Сервер на Ubuntu/Debian или совместимой системе с доступом к shell.
• Доступ к DNS‑управлению доменом (панель провайдера или API).
• Учетная запись у вашего DNS‑провайдера, если вы будете использовать API.
• Установленные git и базовые инструменты (curl, sed по необходимости).

Краткая справка: ACME — протокол автоматического получения/обновления сертификатов; acme.sh — популярный POSIX shell‑клиент для ACME.

Быстрая схема действий

1. Установить acme.sh.
2. Настроить переменные окружения для API DNS (если поддерживается).
3. Выпустить wildcard‑сертификат командой acme.sh с DNS‑провайдером или вручную создать TXT‑запись.
4. Установить сертификат в сервер (Nginx/Apache) и настроить автоматическое обновление.

Установка acme.sh

Обновите индекс пакетов и установите git, если он ещё не установлен:

sudo apt update
sudo apt install -y git

Склонируйте репозиторий и установите acme.sh:

git clone https://github.com/Neilpang/acme.sh.git
cd acme.sh/
./acme.sh --install

После установки перезапустите текущую сессию оболочки, чтобы acme.sh стал доступен (обычно установка добавляет путь в ~/.profile):

exec $SHELL

Проверка установки:

acme.sh --version

Если всё установлено корректно, вы увидите версию acme.sh.

Общий принцип получения wildcard‑сертификата

Let’s Encrypt требует проверки владения доменом через вызов ACME challenge. Для wildcard‑сертификатов возможна только DNS‑валидация: сервис запрашивает, чтобы вы добавили TXT‑запись с определённым содержимым для поддомена acme-challenge.<вашдомен>.

acme.sh умеет работать с API многих DNS‑провайдеров и автоматически ставить/удалять нужные TXT‑записи. Если API недоступно или вы не хотите его использовать, можно пройти процесс вручную — тогда при каждом продлении сертификата потребуется снова добавить TXT‑запись.

Пример: Cloudflare

В Cloudflare зайдите в профиль, скопируйте Global API Key и email, затем экспортируйте их в окружение конструкцией (выполните в shell того пользователя, под которым работает acme.sh):

export CF_Key="ваш_cloudflare_api_key"
export CF_Email="ваш_email@пример.com"

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

acme.sh --issue --dns dns_cf -d '*.example.org'

Если всё прошло успешно, сертификат появится в директории ~/.acme.sh/*.example.org/.

Пример: NameCheap

Получите API‑ключ в панели NameCheap и при необходимости добавьте доверенный IP. Экспортируйте переменные:

export NAMECHEAP_SOURCEIP="ваш_сервер_ip"
export NAMECHEAP_USERNAME="ваш_логин_namecheap"
export NAMECHEAP_API_KEY="ваш_namecheap_api_key"

Выпуск:

acme.sh --issue --dns dns_namecheap -d '*.example.org'

Пример: DigitalOcean

Создайте персональный токен с правами read/write на DNS и экспортируйте:

export DO_API_KEY="ваш_digitalocean_api_token"

Выпуск:

acme.sh --issue --dns dns_dgon -d '*.example.org'

Пример: GoDaddy

Скопируйте ключ и секрет из панели GoDaddy:

export GD_Key="ваш_godaddy_api_key"
export GD_Secret="ваш_godaddy_api_secret"

Выпуск:

acme.sh --issue --dns dns_gd -d '*.example.org'

Пример: Vultr

Создайте API token с правами управления DNS и экспортируйте переменную:

export VULTR_API_KEY="ваш_vultr_api_key"

Выпуск:

acme.sh --issue --dns dns_vultr -d '*.example.org'

Пример: Rackspace

Экспортируйте учетные данные Rackspace:

export RACKSPACE_Username="ваш_rackspace_username"
export RACKSPACE_Apikey="ваш_rackspace_api_key"

Выпуск:

acme.sh --issue --dns dns_rackspace -d '*.example.org'

Ручной режим (без API)

Если провайдер не поддерживается или вы не хотите хранить API‑ключи, используйте ручную DNS‑валидацию. Команда выдаст токен, который нужно добавить в TXT‑запись:

acme.sh --issue --dns --yes-I-know-dns-manual-mode-enough-go-ahead-please -d '*.example.org'

Команда покажет значение TXT для _acme-challenge.example.org. Добавьте эту запись в DNS‑панели, дождитесь распространения (propagation) и затем выполните повторный запуск команды для завершения выпуска.

ALT: Ручная инструкция по добавлению TXT‑записи в панель DNS для проверки владения доменом

Где находятся файлы сертификата

После успешного выпуска сертификаты сохраняются в домашней папке: ~/.acme.sh/<имя_домена>/

• Сертификат: ~/.acme.sh/.example.org/.example.org.cer
• Приватный ключ: ~/.acme.sh/.example.org/.example.org.key (держите в секрете, chmod 600)
• Fullchain (cert + intermediate): ~/.acme.sh/*.example.org/fullchain.cer — обычно используется в конфигурациях веб‑серверов

Пример установки в системные каталоги (требуются права root):

sudo mkdir -p /etc/ssl/private /etc/ssl/certs
sudo cp ~/.acme.sh/*.example.org/fullchain.cer /etc/ssl/certs/example.crt
sudo cp ~/.acme.sh/*.example.org/*.example.org.key /etc/ssl/private/example.key
sudo chmod 640 /etc/ssl/private/example.key
sudo chown root:root /etc/ssl/private/example.key /etc/ssl/certs/example.crt

Пример: настройка Nginx и автоматического обновления

Конфигурация Nginx (фрагмент):

server {
    listen 443 ssl;
    server_name example.org *.example.org;

    ssl_certificate /etc/ssl/certs/example.crt;
    ssl_certificate_key /etc/ssl/private/example.key;

    # дополнительные SSL‑опции: протоколы, ciphers, HSTS
}

Чтобы автоматизировать установку сертификата в системные пути и перезагрузку Nginx после обновления, используйте опцию –install-cert:

acme.sh --install-cert -d '*.example.org' \
  --key-file /etc/ssl/private/example.key \
  --fullchain-file /etc/ssl/certs/example.crt \
  --reloadcmd "systemctl reload nginx"

acme.sh сам добавит задачу в cron и будет пробовать обновлять сертификат автоматически за несколько дней до истечения.

Безопасность и хранение секретов

• Храните приватный ключ с правами доступа 600 или 640 и владельцем root.
• Храните API‑ключи в защищённом файле (~/.acme.sh/account.conf или отдельном .env) с правами 600.
• По возможности используйте минимально необходимые привилегии для API‑ключей (только управление DNS).
• Не отправляйте приватный ключ и API‑ключи по незащищённым каналам.

Устранение проблем (для быстрого поиска причин)

• Проверка DNS: убедитесь, что TXT‑запись _acme-challenge.* действительно доступна публично; используйте dig/host/nslookup.
• Неверные учетные данные API: проверьте переменные окружения и права ключа.
• Пропagation DNS: некоторые провайдеры обновляют записи дольше, подождите 5–30 минут.
• Лимиты Let’s Encrypt: если вы часто пробовали выдачу и получали ошибки, возможно вы достигли ограничений — подождите и уменьшите частоту попыток.

Альтернативные подходы и сценарии использования

• Если DNS‑провайдер не поддерживает API и у вас большое количество серверов, можно настроить централизованный DNS‑менеджер (внутренний API) и дать acme.sh права только к нему.
• Для единичных доменов без поддоменов удобнее использовать сертификат на конкретные имена (без wildcard).
• Для Kubernetes и динамичных окружений стоит рассмотреть cert‑manager, который интегрируется с Let’s Encrypt и управляет жизненным циклом сертификатов.

Роли и чеклист (кто что делает)

• DevOps / админ: устанавливает acme.sh, настраивает API‑переменные, автоматическую установку сертификата в /etc/ssl и перезагрузку сервисов.
• Владельцы домена: обеспечивают доступ к DNS‑панели или выдают ключи API.
• Разработчик: проверяет, что сервисы слушают на HTTPS и что сертификат корректно отдан (curl -I https://example.org).

Мини‑чеклист перед выпуском:

• Домена настроен и доступен DNS.
• Есть доступ к DNS‑API или возможность править TXT‑записи вручную.
• Установлен acme.sh и проверена версия.
• Настроено автоматическое копирование сертификатов в системные пути и перезагрузка сервисов.

Факты и числа

• Срок действия сертификата Let’s Encrypt: 90 дней.
• Рекомендуется автоматически обновлять и тестировать перезапуск сервисов, чтобы избежать простоя.

Критерии приёмки

• Веб‑сайт отвечает по HTTPS с вашим новым wildcard‑сертификатом для основных поддоменов.
• Сертификат виден в браузере и содержит *.example.org в CN/SAN.
• Приватный ключ хранится с ограниченными правами доступа и не публикуется.

Глоссарий (одна строка)

• ACME: протокол автоматизации получения SSL/TLS сертификатов;
• wildcard: сертификат, покрывающий все поддомены уровня *.domain;
• TXT: тип DNS‑записи, используемый для проверки владения доменом.

Короткое резюме

Wildcard‑сертификат от Let’s Encrypt через acme.sh — удобный и бесплатный способ защитить множество поддоменов одновременно. Используйте DNS‑валидацию через API провайдера для полной автоматизации; если API недоступен — применяйте ручную проверку, но учтите дополнительные трудозатраты при регулярном обновлении. Обязательно настройте безопасное хранение ключей и автоматическое обновление сертификатов.

Важно: всегда проверяйте и тестируйте процесс обновления в тестовом окружении перед внедрением в продакшен.