Что делает этот модуль #
Сертификат TLS — это то, что превращает http:// в https://: он шифрует соединение между вашими посетителями и сервером и заставляет браузер показывать замок вместо предупреждения «сайт не защищён».
Модуль tls берёт на себя весь жизненный цикл этого сертификата, опираясь на certbot: запрашивает его у Let's Encrypt (бесплатного и признанного центра), доказывает, что домен ваш, через испытание ACME, устанавливает сертификат туда, где его ожидает ваш веб-сервер, и продлевает его автоматически до истечения срока — без необходимости об этом помнить.
Ваш домен (например, app.ejemplo.com) должен указывать по DNS на IP этого сервера, а порт 80 должен быть доступен для испытания HTTP-01. Иначе выпуск завершится ошибкой на шаге проверки.
Типовые задачи #
Выберите, что нужно сделать. В каждом рецепте команда уже написана — просто замените домен и почту на свои и нажмите Копировать.
1
Выпустить мой первый сертификат
Получите замок HTTPS для вашего домена за минуту.
Подключитесь по SSH к серверу под пользователем ubuntu.
Выполните команду, заменив домен и почту на свои (почта используется только для оповещения об истечении срока):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Подождите несколько секунд. Вы увидите ход испытания и в конце — дату истечения срока.
https:// с замком. Автоматическое продление активировано — больше ничего делать не нужно.2
Посмотреть, какие есть и когда истекают
Проверьте одним взглядом состояние ваших сертификатов.
Быстрая сводка общего состояния и таймера продления:
$ sudo imaxe tls statusНужны детали по каждому домену — с оставшимися днями и путём к fullchain? Используйте list:
$ sudo imaxe tls list3
Принудительно продлить
Обычно это происходит автоматически, но при необходимости можно ускорить.
Продлите все сертификаты, срок которых скоро истекает (именно это делает таймер):
$ sudo imaxe tls renewХотите сначала прогнать вхолостую без записи на диск или продлить, даже если ещё есть дни? Добавьте --dry-run или --force:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Отозвать сертификат
Аннулирует сертификат в центре (например, если ключ утёк).
Отзовите сертификат домена в Let's Encrypt, указав причину, если она известна:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue.5
Удалить сертификат с диска
Перестаньте управлять доменом, который больше не используете.
Удалите сертификат и его ключи с диска. Внимание: это не отзывает его в центре — для этого сначала используйте revoke.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list, а его автоматическое продление прекращается.Самая частая ошибка — DNS ещё не распространился или порт 80 закрыт. Подождите несколько минут и повторите. Если проблема сохраняется, сначала попробуйте в тестовом режиме с --staging (см. справочник), чтобы не израсходовать лимит попыток.
Синопсис #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Подкоманды, затрагивающие сертификаты, требуют привилегий root (используйте sudo), потому что пишут в /etc/imaxe/ и перезагружают системные сервисы. Добавьте --json к list или status, чтобы получить машиночитаемый вывод, пригодный для скриптинга.
Подкоманды #
| Подкоманда | Что делает | Значимые флаги |
|---|---|---|
| issue | Выпускает сертификат для одного или нескольких доменов, проходя испытание ACME. | --email, --webroot, --standalone, --staging |
| renew | Продлевает сертификаты, срок которых скоро истекает, и перезагружает веб-сервер. Подходит для таймера. | --dry-run, --force |
| list | Выводит управляемые сертификаты с оставшимися днями и путём к fullchain. | --json |
| status | Сводка: число сертификатов, скоро истекающие и состояние таймера продления. | --json |
| revoke | Отзывает сертификат по домену в центре (ACME). | --reason |
| delete | Удаляет сертификат и его ключи с диска. Не отзывает в ACME. | — |
Аргументы и флаги #
| Флаг | Тип | По умолчанию | Описание |
|---|---|---|---|
| <dominio> обяз. | string… | — | Один или несколько доменов для сертификата. В issue первый — основной (CN), остальные — SAN. В revoke/delete — домен, над которым выполняется операция. |
| string | tls.yml | Контактная почта учётной записи ACME. Обязательна при первом issue; далее повторно используется из tls.yml. | |
| --webroot | path | /var/www/html | Корневой каталог для испытания HTTP-01. Метод по умолчанию. |
| --standalone | bool | false | Использует встроенный сервер certbot вместо webroot. Требует свободного порта 80. |
| --staging | bool | false | Использует тестовую среду Let's Encrypt (не учитывается в лимите частоты запросов). Сертификат не будет доверенным. |
| --dry-run | bool | false | В renew имитирует продление без записи на диск. |
| --force | bool | false | В renew продлевает, даже если срок ещё не близок к истечению. |
| --reason | enum | unspecified | В revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | В list/status выдаёт результат в виде JSON в stdout. |
Файлы и пути #
| Путь | Содержимое |
|---|---|
| /etc/imaxe/tls.yml | Конфигурация модуля: почта по умолчанию, метод (webroot/standalone), webroot, staging, автопродление и хук перезагрузки. |
| /etc/letsencrypt/live/<dominio>/ | Сертификат (fullchain.pem) и приватный ключ (privkey.pem), управляемые certbot. |
| /var/log/imaxe/tls.log | Структурированный журнал каждого выпуска, продления и отзыва. |
| imaxe-tls.timer | Таймер systemd, периодически запускающий renew. |
Пример tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxКоды возврата и логи #
Каждый запуск возвращает код, который можно проверить командой echo $? — удобно для цепочек в скриптах:
Следите за логом в реальном времени во время отладки:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logПродвинутые примеры #
Несколько доменов в одном сертификате
Первый домен — основной; следующие добавляются как SAN, все в одном сертификате:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Безопасная проверка перед продакшеном
Проверьте всю цепочку в тестовой среде, чтобы не израсходовать реальный лимит. С --standalone настроенный веб-сервер не требуется:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Устранение неполадок #
| Симптом | Вероятная причина | Решение |
|---|---|---|
| Возникает CHALLENGE (код 3) | Домен не разрешается в этот хост или порт 80 закрыт. | Проверьте запись A/AAAA и откройте порт 80 в security group; повторите. |
| Возникает RATELIMIT (код 4) | Слишком много выпусков одного домена за неделю. | Используйте --staging для проверки; дождитесь освобождения окна. |
| HTTPS загружается, но с предупреждением | Выпущено с --staging: сертификат не доверенный. | Перевыпустите без --staging, чтобы получить действительный. |
| Возникает RELOAD (код 5) | reload_hook указывает на несуществующий сервис. | Настройте reload_hook в tls.yml и снова запустите renew. |
Застряли с модулем TLS?
Напишите нам, приложив вывод «imaxe <module> status --json», и мы быстро ответим.