Хуки Certbot: команда до и после продления сертификата
Хук — это команда, которую Certbot запускает сам: перед продлением сертификата, сразу после него или в самом конце. Главное, для чего он нужен: чтобы nginx перечитал новый сертификат, иначе сайт продолжит показывать старый, пока срок не кончится. Здесь — как понять, нужен ли хук вам, как его сделать и проверить.
Содержание 10
Что сделать прямо сейчас
- Подключитесь к серверу по SSH (как подключиться).
- Посмотрите, каким способом получен сертификат. Имя файла — имя сертификата из
sudo certbot certificates:sudo grep -E "^(authenticator|installer)" /etc/letsencrypt/renewal/example.ru.conf-
installer = nginx— Certbot сам перезагружает nginx после продления. Хук для этого не нужен, переходите к шагу 5; -installer = Noneили такой строки нет — nginx не узнает о новом сертификате. Сделайте хук — шаги 3–4. - Создайте файл хука, который перезагружает nginx:
printf '#!/bin/sh\nsystemctl reload nginx\n' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh - Разрешите его запуск — без этого Certbot файл пропустит:
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh - Проверьте продление вместе с хуками:
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-hooksCertbot проверит продление с новыми настройками, запустит хук и сохранит его. Строка Successfully updated configuration. — хук записан.
Правила для файлов в папках
- Файл должен быть исполняемым:
sudo chmod +x имя-файла. Без этого Certbot его пропускает и ничего не пишет. - Первая строка —
#!/bin/sh: она говорит, какой программой выполнять файл. - Файлы, имя которых кончается на
~, Certbot пропускает: это копии, которые оставляют редакторы. - Если файлов несколько, они запускаются по алфавиту имён.
- Хук запускается от root, как и сам Certbot, поэтому
sudoвнутри файла не нужен.
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 nginxreload, а не 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_LINEAGE | deploy | папка нового сертификата: /etc/letsencrypt/live/example.ru |
RENEWED_DOMAINS | deploy, post | домены через пробел: example.ru www.example.ru |
FAILED_DOMAINS | post | домены, которые продлить не удалось |
С ними хук может отвечать за один сертификат, а не за все. Например, перезапускать почтовый сервер, только когда продлился 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-hooksDeploy-хуки тогда запустятся после успешной проверки. Работают они с текущим сертификатом, а не с тестовым.
Что вывел хук, видно в ответе 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) указаны отдельно.
Источники
- Исходный код Certbot 5.9.0: hooks.py — когда запускаются хуки, переменные, пропуск deploy-хуков при
--dry-run. - Исходный код Certbot 5.9.0: main.py — перезагрузка nginx плагином после продления.
- Исходный код Certbot 5.9.0: ops.py — сообщения
reported error codeиran with output. - Список изменений Certbot — с какой версии файлы из папок работают при первом получении сертификата.
- Справка Certbot: продление сертификатов — на английском.
Сверено 6 ноября 2026 года.
Что почитать дальше
- Автопродление Certbotкто и когда запускает продление.
- Standaloneгде нужны pre- и post-хуки.
- Файл renewalгде Certbot хранит хуки сертификата.