Поиск
Справочник

Хуки Certbot: команда до и после продления сертификата

Хук — это команда, которую Certbot запускает сам: перед продлением сертификата, сразу после него или в самом конце. Главное, для чего он нужен: чтобы nginx перечитал новый сертификат, иначе сайт продолжит показывать старый, пока срок не кончится. Здесь — как понять, нужен ли хук вам, как его сделать и проверить.

≈ 8 мин чтения
Содержание 10

Что сделать прямо сейчас

  1. Подключитесь к серверу по SSH (как подключиться).
  2. Посмотрите, каким способом получен сертификат. Имя файла — имя сертификата из sudo certbot certificates:
    sudo grep -E "^(authenticator|installer)" /etc/letsencrypt/renewal/example.ru.conf

    - installer = nginx — Certbot сам перезагружает nginx после продления. Хук для этого не нужен, переходите к шагу 5; - installer = None или такой строки нет — nginx не узнает о новом сертификате. Сделайте хук — шаги 3–4.

  3. Создайте файл хука, который перезагружает nginx:
    printf '#!/bin/sh\nsystemctl reload nginx\n' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
  4. Разрешите его запуск — без этого Certbot файл пропустит:
    sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
  5. Проверьте продление вместе с хуками:
    sudo certbot renew --dry-run --run-deploy-hooks

    Строка Congratulations, all simulated renewals succeeded: и ни одной строки reported error code — всё работает.

Три вида хуков

ХукКогда запускаетсяДля чегоПапка
preперед получением или продлением, только если продлевать есть чтоостановить nginx для standalone/etc/letsencrypt/renewal-hooks/pre/
deployпосле каждого успешно полученного или продлённого сертификата, по разу на сертификатперезагрузить nginx, передать сертификат другой программе/etc/letsencrypt/renewal-hooks/deploy/
postпосле попытки получить или продлить, даже неудачной; у certbot renew — один раз в конце, после всех сертификатовзапустить nginx, который остановил pre-хук/etc/letsencrypt/renewal-hooks/post/

Порядок такой: pre → получение сертификата → deploy → post. Если продлевать нечего, не запускается ни один хук, и Certbot пишет No hooks were run.

Одинаковый pre-хук у нескольких сертификатов Certbot запускает один раз, post-хук — тоже.

Если команда хука закончилась ошибкой, Certbot пишет Hook 'deploy-hook' reported error code 1 (вместо deploy-hook — pre-hook или post-hook) и работает дальше. Сертификат при этом уже продлён — ошибка хука его не отменяет.

Хук файлом в папке или ключом в команде

Хук можно задать двумя способами.

СпособДля каких сертификатовГде хранится
файл в /etc/letsencrypt/renewal-hooks/deploy/ (или pre/, post/)для всех сертификатов на сервересам файл
ключ --deploy-hook, --pre-hook или --post-hook при получении сертификататолько для этого сертификатастрока в файле renewal

Файл в папке проще: его видно командой ls, он работает для всех сертификатов и не зависит от того, с какими ключами их получали.

Ключ Certbot запоминает в файле /etc/letsencrypt/renewal/имя.conf и запускает при каждом продлении. Deploy-хук там записан строкой renew_hook = — это старое имя того же хука. Добавить хук к сертификату, который уже есть:

sudo certbot reconfigure --cert-name example.ru --deploy-hook "systemctl reload nginx" --run-deploy-hooks

Certbot проверит продление с новыми настройками, запустит хук и сохранит его. Строка Successfully updated configuration. — хук записан.

Правила для файлов в папках

  • Файл должен быть исполняемым: sudo chmod +x имя-файла. Без этого Certbot его пропускает и ничего не пишет.
  • Первая строка — #!/bin/sh: она говорит, какой программой выполнять файл.
  • Файлы, имя которых кончается на ~, Certbot пропускает: это копии, которые оставляют редакторы.
  • Если файлов несколько, они запускаются по алфавиту имён.
  • Хук запускается от root, как и сам Certbot, поэтому sudo внутри файла не нужен.
В Certbot 2.9.0 из пакета Ubuntu файлы из папок запускаются только при продлении — командой certbot renew или таймером. В Certbot 5.9.0 из snap — и при первом получении сертификата.

Как перезагрузить nginx после продления

Nginx читает файл сертификата один раз — при запуске или перезагрузке. Certbot кладёт новый сертификат, а nginx продолжает отдавать старый из памяти. Через месяц срок старого кончается, и браузеры показывают NET::ERR_CERT_DATE_INVALID, хотя certbot certificates пишет VALID.

Как получен сертификатПерезагружает ли Certbot nginx сам
sudo certbot --nginx (в файле renewal installer = nginx)да: в журнале строка Reloading nginx server after certificate renewal
certonly --webroot, certonly --standalone, certonly --manual, DNS-плагинынет, нужен deploy-хук

Хук — файл из двух строк, как в начале страницы:

#!/bin/sh
systemctl reload nginx

reload, а не restart: nginx перечитывает настройки и сертификаты, не обрывая открытые соединения. Если в настройках nginx ошибка, перезагрузка не пройдёт, nginx продолжит работать по-старому, а Certbot напишет Hook 'deploy-hook' reported error code 1. Найти ошибку поможет sudo nginx -t.

Сертификат получен через standalone и порт 80 нужен Certbot свободным — тогда нужны два хука: pre systemctl stop nginx и post systemctl start nginx. Перезагружать nginx deploy-хуком тогда не нужно: post-хук запустит его уже с новым сертификатом.

Сертификат нужен не только nginx, а ещё почтовому серверу или FTP — добавьте в тот же файл перезапуск этой программы, как в настройке vsftpd.

Какие данные получает хук

Certbot передаёт хуку переменные окружения:

ПеременнаяКакой хук получаетЧто в ней
RENEWED_LINEAGEdeployпапка нового сертификата: /etc/letsencrypt/live/example.ru
RENEWED_DOMAINSdeploy, postдомены через пробел: example.ru www.example.ru
FAILED_DOMAINSpostдомены, которые продлить не удалось

С ними хук может отвечать за один сертификат, а не за все. Например, перезапускать почтовый сервер, только когда продлился mail.example.ru:

#!/bin/sh
case "$RENEWED_DOMAINS" in
  *mail.example.ru*) systemctl restart postfix ;;
esac
systemctl reload nginx

Как проверить хук

С --dry-run Certbot запускает pre- и post-хуки, а deploy-хуки пропускает. Чтобы проверить и их, добавьте --run-deploy-hooks:

sudo certbot renew --dry-run --run-deploy-hooks

Deploy-хуки тогда запустятся после успешной проверки. Работают они с текущим сертификатом, а не с тестовым.

Что вывел хук, видно в ответе Certbot строкой Hook 'deploy-hook' ran with output:. Хук, который перезагружает nginx, ничего не пишет — это нормально. Убедиться, что nginx перезагрузился:

sudo journalctl -u nginx --since "10 minutes ago" --no-pager

Строка с Reloaded nginx.service — перезагрузка была. Подробнее о журнале — команда journalctl.

Запустить сам файл хука можно и без Certbot:

sudo /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh

Если хук не срабатывает

Как узнатьПричинаЧто сделать
ls -l /etc/letsencrypt/renewal-hooks/deploy/ — в начале строки нет x, например -rw-r--r--файл не исполняемый, Certbot его пропускаетsudo chmod +x на этот файл (права на файлы)
имя файла кончается на ~Certbot считает его копиейпереименуйте файл
sudo certbot renew пишет No hooks were run.продлевать было нечеготак и должно быть; проверка — --dry-run --run-deploy-hooks
хук не запустился после первого certbot certonlyв Certbot 2.9.0 файлы из папок работают только при продленииперезагрузите nginx один раз вручную, дальше хук сработает сам
sudo grep hook /etc/letsencrypt/renewal/example.ru.conf показывает старую командухук запомнен в файле renewal и запускается вместе с файлами из папкипоменяйте его через certbot reconfigure, как выше

Ошибки и как их исправить

Что видитеПричинаЧто делать
Unable to find deploy-hook command systemclt in the PATH.в первом слове команды опечатка или программы нет на сервереисправьте команду; можно писать полный путь: /usr/bin/systemctl reload nginx
… exists, but is not executable.в --deploy-hook указан файл без права на запускsudo chmod +x на этот файл
Hook 'deploy-hook' reported error code 1команда хука закончилась ошибкойзапустите её вручную и прочитайте ответ; для nginx — sudo nginx -t
Hook 'deploy-hook' ran with error output:хук написал что-то в поток ошибоктекст под этой строкой — ответ команды хука
сертификат продлился, а браузер показывает старый срокнет deploy-хука или он не исполняемыйперезагрузка nginx после продления и ERR_CERT_DATE_INVALID

Certbot проверяет только первое слово команды хука. Если команда начинается не с программы — например, с cd или с переменной, — эта проверка может её не понять. Проще вынести такую команду в файл в папке deploy.

Всё сверено с Certbot 5.9.0 из snap, отличия пакета Ubuntu 24.04 (Certbot 2.9.0) указаны отдельно.

Источники

Сверено 6 ноября 2026 года.

Где попробовать. Команды из статьи безопаснее сначала повторить на отдельном тестовом сервере, а не на рабочем. Подойдёт VPS с Ubuntu, например Timeweb Cloud Реклама. АО «ТАЙМВЭБ», ИНН 7810353960. erid: CQH36pWzJpoBWKF332yG5h2XQ4cVubfBmkvqAitFqcpzWs. Как зайти на него после заказа — в статье Как подключиться к VPS по SSH.

Что почитать дальше