Установка и использование acme.sh для выпуска сертификатов Let's Encrypt

Быстрые ссылки

• Установка acme.sh
• Первые шаги
• Конфигурация веб-сервера
• Конфигурация DNS (Cloudflare)
• Выпуск сертификата через webroot
• Выпуск сертификата через DNS
• Обновление сертификата
• Удаление сертификатов
• Дополнительные рекомендации и контрольные списки

Введение

Let’s Encrypt изменил мир SSL, предложив бесплатные сертификаты с коротким сроком действия — это стимулировало автоматизацию и появление утилит для удобного управления сертификатами. Помимо широко известного Certbot, существует acme.sh — полностью shell-базированный ACME-клиент с гибкими возможностями и широким набором DNS-провайдеров.

Определение: ACME — протокол автоматизированного выпуска и управления сертификатами, используемый Let’s Encrypt.

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

Проще всего установить acme.sh запуском инсталляционного скрипта из официального репозитория:

curl https://get.acme.sh | sh

Исходники скрипта доступны в репозитории:

acme.sh

По умолчанию установщик поместит файлы в ~/.acme.sh и добавит alias в ~/.bashrc при возможности. Также установится cron-задача для автоматического продления при наличии cron.

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

Первые шаги

Как вы будете пользоваться acme.sh, зависит от метода валидации домена (webroot, standalone, DNS и т. д.) и от вашего веб-сервера. Основные режимы работы acme.sh:

• webroot — размещает проверочный файл в /.well-known/acme-challenge/
• standalone — запускает временный HTTP-сервер на 80/443
• tls-alpn-01 — проверка по TLS ALPN (порт 443)
• apache / nginx — плагины для конфигураций Apache/NGINX
• dns — создание TXT-записей через API провайдера
• dns alias / stateless — расширенные режимы для делегированных доменов

В этой статье показаны два практических сценария: webroot (с примерами для NGINX и Apache) и dns (на примере Cloudflare).

Конфигурация веб-сервера

Конфигурация NGINX для проверки Let’s Encrypt

Рекомендуется выделить общий конфиг, который можно подключать в vhost’ах:

Файл: letsencrypt.conf

Включение в vhost: include /etc/nginx/letsencrypt.conf

# Rule for legitimate ACME Challenge requests (like /.well-known/acme-challenge/xxxxxxxxx)
# We use ^~ here, so that we don't check other regexes (for speed-up). We actually MUST cancel
# other regex checks, because in our other config files have regex rule that denies access to files with dotted names.
location ^~ /.well-known/acme-challenge/ {
    # Set correct content type. According to this:
    # 
    # Current specification requires "text/plain" or no content header at all.
    # It seems that "text/plain" is a safe option.
   default_type "text/plain";
}

# Direct access returns a 404
location = /.well-known/acme-challenge/ {
   return 404;
}

Пояснения:

• location ^~ используем, чтобы приоритет был выше других regex-правил.
• default_type “text/plain” гарантирует корректный Content-Type для проверки.

Совет: проверьте, что директория webroot доступна от имени процесса веб-сервера и что SELinux/AppArmor не блокируют чтение файлов.

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

Для Apache удобно создать отдельный конфиг, который указывает alias на дисковую директорию проверки.

Файл: /etc/apache2/conf-available/letsencrypt.conf

Alias /.well-known/acme-challenge/ "/var/www/html/.well-known/acme-challenge/"

    AllowOverride None
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
    Require method GET POST OPTIONS

Пояснения:

• Alias перенаправляет запросы в физическую директорию сайта.
• Убедитесь, что виртуальный хост использует ту же DocumentRoot или что путь совпадает с webroot, который вы указываете в acme.sh.

Конфигурация DNS (Cloudflare)

В примере ниже используется Cloudflare как провайдер API для режима dns_cf. acme.sh использует две переменные окружения: CF_Key и CF_Email.

Добавьте в ~/.bashrc (или в systemd unit) следующие строки, чтобы переменные подгружались автоматически:

 export CF_Key="#########..."
 export CF_Email="cfaccount@email.com"

Примечание: пробел перед экспортом в примере защищает от записи команды в историю shell в некоторых настройках.

Важно: для интеграции через API используйте API Token с минимальными правами (Zone:DNS — edit) вместо глобального ключа, если ваша инфраструктура и провайдер поддерживают токены.

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

Пример выпуска сертификата с двумя доменами (основной и www) в одном сертификате:

acme.sh --issue -d example.com -d www.example.com -w /var/www/html

Пояснение: ключ -w указывает путь webroot, где будет создан файл проверки.

Генерируемые сертификаты находятся в ~/.acme.sh/{domain_name}

Файлы обычно: {domain}.key, {domain}.cer, fullchain.cer, ca.cer

Краткий контрольный чек: после выпуска проверьте, что nginx/apache ссылается на fullchain.cer и приватный ключ, перезапустите сервис.

Выпуск сертификата через DNS (Cloudflare)

DNS-метод полезен, когда нет возможности разместить файл в webroot (например, для wildcard-сертификатов) или при делегировании поддомена.

Пример команды с использованием dns_cf:

# Multiple Domains
acme.sh --issue --dns dns_cf -d example.com -d www.example.com

Пояснение: acme.sh создаст временную TXT-запись _acme-challenge через API Cloudflare; после валидации запись будет удалена.

Файлы сертификатов также будут в ~/.acme.sh/{domain_name}

Совет: при автоматизации с CI/CD используйте API Token с ограниченными правами и храните переменные в безопасном хранилище (Vault/Secrets Manager).

Обновление сертификата

По умолчанию acme.sh создаёт cronjob для регулярной проверки и продления сертификатов, например:

48 0 * * * "/home/user/.acme.sh/acme.sh" --cron --home "/home/user/.acme.sh" > /dev/null

Ручное принудительное продление для доменов:

acme.sh --renew -d example.com -d www.example.com

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

Удаление сертификатов

Чтобы убрать сертификат из списка автоматического продления, используйте:

acme.sh --remove -d example.com -d www.example.com

Это не удаляет файлы с диска из ~/.acme.sh — если нужно удалить и файлы, удалите соответствующую директорию вручную.

Список установленных сертификатов можно получить командой:

acme.sh --list

Когда подход с acme.sh не сработает — типичные причины и решения

• Неправильный webroot: укажите точный путь, совпадающий с DocumentRoot виртуального хоста.
• Брандмауэр или NAT: порты 80/443 должны быть доступны для HTTP-01/TLS-ALPN-01.
• Ошибки DNS: при использовании DNS-метода API-ключ/токен должен иметь права на изменение DNS-записей.
• Rate limits Let’s Encrypt: аккуратно тестируйте автоматизацию на staging окружении.
• SELinux/AppArmor: могут блокировать запись/чтение в webroot — проверьте контексты.

Альтернативы и сравнение (кратко)

• Certbot — основной клиент с поддержкой systemd и широкими плагинами. Проще для базовых сценариев, но тяжелее встраивается в кастомные скрипты.
• acme.sh — минималистичный shell-скрипт, удобен в контейнерных/минималистичных системах и при необходимости тонкой настройки.

Выбор: если нужна простая интеграция с Apache/NGINX и вы не планируете кастомные DNS-скрипты — Certbot подойдёт. Если важна лёгкость, поддержка множества DNS-провайдеров и отсутствие Python-зависимостей — acme.sh лучше.

Мини-методология: шаги для безопасного выпуска и обслуживания сертификатов

1. Подготовка: определить метод валидации (webroot или dns) и проверить доступы.
2. Установка acme.sh и конфигурация переменных окружения (для DNS).
3. Тестовый выпуск на staging (acme.sh поддерживает –staging) для проверки работы без рисков rate limit.
4. Выпуск на production, проверка файлов сертификатов и настройка веб-сервера.
5. Настройка автоматического продления (cron или systemd timer) и оповещений на случай неудач.
6. Регулярные проверки: логов, прав доступа и состояния DNS-API.

Контрольные списки по ролям

Администратор (sysadmin):

• Проверить доступность 80/443 и корректность webroot.
• Настроить cron/systemd timer для acme.sh.
• Хранить API-токены в защищённом хранилище.

DevOps/CI:

• Интегрировать выпуск в pipeline (staging → prod).
• Автоматизировать перезапуск сервисов после обновления сертификата.
• Покрыть тестами edge-cases (отказ API, недоступность DNS).

Владелец сайта / менеджер:

• Контролировать, что контакты для домена верны (WHOIS, почта).
• Оповещения о сбоях в продлении.

Полезная шпаргалка команд (cheat sheet)

• Установка: curl https://get.acme.sh | sh
• Выпуск webroot: acme.sh –issue -d example.com -d www.example.com -w /var/www/html
• Выпуск DNS (Cloudflare): acme.sh –issue –dns dns_cf -d example.com
• Продление вручную: acme.sh –renew -d example.com
• Удалить из автопродления: acme.sh –remove -d example.com
• Список сертификатов: acme.sh –list

Факты для быстрой ориентации

• Срок действия сертификатов Let’s Encrypt: 90 дней.
• Рекомендуется автоматическое продление и перезапуск веб-сервера после обновления.
• acme.sh по умолчанию хранит файлы в ~/.acme.sh

Простая блок-схема принятия решения (Mermaid)

flowchart TD
  A[Нужен сертификат?] --> B{Есть доступ к webroot?}
  B -- Да --> C[Использовать webroot и nginx/apache конфиг]
  B -- Нет --> D{Можно ли менять DNS через API?}
  D -- Да --> E[Использовать dns_cf или другой dns-плагин]
  D -- Нет --> F[Использовать standalone режим на временном сервере]
  C --> G[Выпустить, проверить, настроить cron]
  E --> G
  F --> G

Безопасность и рекомендации

• Используйте минимально необходимые права для API-токенов.
• Ограничьте доступ к приватным ключам сертификата (chmod 600).
• Храните резервные копии ключей и конфигураций.

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

acme.sh — лёгкий и гибкий инструмент для выпуска сертификатов Let’s Encrypt, подходящий для множества сценариев: от простого webroot на NGINX до автоматизации через DNS API (Cloudflare). Выбирайте метод валидации исходя из архитектуры сервиса, храните ключи и токены безопасно и автоматизируйте продление.

Важно: перед массовым выпуском протестируйте процесс в staging, чтобы избежать ограничения Let’s Encrypt по количеству запросов.

1‑строчный глоссарий

• webroot — метод проверки домена через размещение файла в корне сайта; DNS — метод через TXT-запись; ACME — протокол автоматизированного выпуска сертификатов.