Ansible Роль: Certbot (для Let's Encrypt)

Устанавливает и настраивает Certbot (для Let's Encrypt).

Требования

Если установка идет из исходников, необходим Git. Вы можете установить Git с помощью роли geerlingguy.git.

Как правило, установка из исходников (см. раздел Установка из Git) предоставляет лучший опыт работы с Certbot и Let's Encrypt, особенно если вы используете старую версию ОС.

Переменные роли

certbot_install_method: package

Управляет способом установки Certbot. Доступные варианты: 'package', 'snap', 'source'.

certbot_auto_renew: true
certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}"
certbot_auto_renew_hour: "3"
certbot_auto_renew_minute: "30"
certbot_auto_renew_options: "--quiet"

По умолчанию эта роль настраивает задание cron, которое выполняется от указанного аккаунта пользователя в заданный час и минуту каждый день. По умолчанию выполняется certbot renew (или certbot-auto renew) через cron каждый день в 03:30:00 от пользователя, указанного в вашем Ansible плейбуке. Рекомендуется установить индивидуального пользователя/час/минуту, чтобы обновление происходило в период низкой нагрузки и выполнялось не от root-пользователя.

Автоматическая генерация сертификатов

В настоящее время поддерживаются методы standalone и webroot для генерации новых сертификатов с использованием этой роли.

Для полного примера: смотрите полностью функциональный тестовый плейбук в molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Установите certbot_create_if_missing в yes или True, чтобы позволить этой роли генерировать сертификаты.

certbot_create_method: standalone

Установите метод, используемый для генерации сертификатов с помощью переменной certbot_create_method — текущие допустимые значения: standalone или webroot.

certbot_testmode: false

Включите тестовый режим, чтобы выполнить только тестовый запрос без фактической генерации сертификатов.

certbot_hsts: false

Включите (HTTP Strict Transport Security) для генерации сертификата.

certbot_admin_email: [email protected]

Электронная почта, используемая для согласия с условиями использования Let's Encrypt и подписки на уведомления, связанные с сертификатами. Ее следует настроить и указать на адрес, который вы или ваша организация регулярно проверяют.

certbot_certs: []
  # - email: [email protected]
  #   webroot: "/var/www/html"
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

Список доменов (и других данных), для которых должны быть сгенерированы сертификаты. Вы можете добавить ключ email к любому элементу списка, чтобы переопределить certbot_admin_email. При использовании метода webroot необходимо предоставить элемент webroot, указывающий, какую директорию использовать для аутентификации. Убедитесь, что ваш веб-сервер правильно отдает содержимое из этой директории.

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

Переменная certbot_create_command определяет команду, используемую для генерации сертификата. См. полную команду по умолчанию внутри defaults/main.yml для полного примера — и вы можете легко добавить дополнительные аргументы, которые не входят в команду по умолчанию, с помощью переменной certbot_create_extra_args.

Генерация сертификатов в автономном режиме

certbot_create_standalone_stop_services:
  - nginx

Сервисы, которые должны быть остановлены во время работы certbot, когда он запускает свой собственный автономный сервер на портах 80 и 443. Если вы используете Apache, установите это значение apache2 (Ubuntu) или httpd (RHEL), или если у вас есть Nginx на порту 443 и что-то еще на порту 80 (например, Varnish, Java-приложение и т.д.), добавьте их в список, чтобы они были остановлены при генерации сертификата.

Эти сервисы будут остановлены только в первый раз при генерации нового сертификата.

Установка через Snap

Начиная с декабря 2020 года, разработчики Certbot решили рекомендовать установку Certbot через Snap, а не поддерживать такие скрипты, как certbot-auto.

Установка certbot_install_method: snap настраивает эту роль для установки Certbot через Snap.

Этот метод установки в настоящее время экспериментальный и может работать не на всех дистрибутивах Linux.

Генерация сертификатов с использованием метода webroot

При использовании метода webroot необходимо предоставить элемент webroot для каждого элемента certbot_certs, указывая, какую директорию использовать для аутентификации. Также убедитесь, что ваш веб-сервер правильно отдает содержимое из этой директории.

Установка из исходников Git

Вы можете установить Certbot из его репозитория Git, если это необходимо, указав certbot_install_method: source. Это может быть полезно в некоторых случаях, особенно когда старые дистрибутивы не имеют доступных пакетов Certbot (например, CentOS < 7, Ubuntu < 16.10 и Debian < 8).

certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

Параметры репозитория Certbot Git. Если установка идет из исходников, указанный certbot_repo клонируется с учетом установленного значения certbot_version. Если certbot_keep_updated установлено в yes, репозиторий обновляется каждый раз, когда выполняется эта роль.

certbot_dir: /opt/certbot

Директория, в которой будет клонирован Certbot.

Сертификаты Wildcard

Let's Encrypt поддерживает генерацию wildcard сертификатов, но процесс их генерации и использования немного сложнее. Смотрите комментарии в этом запросе на изменение для примера, как использовать эту роль для поддержки wildcard сертификатов.

Также у Майкла Портера есть руководство по Созданию Wildcard сертификата Let's Encrypt с помощью Ansible, специально с использованием Cloudflare.

Зависимости

Отсутствуют.

Пример плейбука

- hosts: servers

  vars:
    certbot_auto_renew_user: ваш_имя_пользователя
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Смотрите другие примеры в директории tests/.

Ручная генерация сертификатов с помощью certbot

Примечание: Вы можете использовать эту роль для автоматической генерации сертификатов; смотрите раздел "Автоматическая генерация сертификатов" выше.

Вы можете вручную создавать сертификаты, используя скрипт certbot (или certbot-auto) (используйте letsencrypt на Ubuntu 16.04 или используйте /opt/certbot/certbot-auto, если установлено из исходников/Git). Вот несколько примеров команд по настройке сертификатов с помощью Certbot:

# Автомatically добавляет сертификаты для всех виртуальных хостов Apache (используйте с осторожностью!).
certbot --apache

# Генерирует сертификаты, но не изменяет конфигурацию Apache (более безопасно).
certbot --apache certonly

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

1. Убедитесь, что любые службы, слушающие на портах 80 и 443 (Apache, Nginx, Varnish и т.п.), остановлены.
2. Зарегистрируйтесь с помощью команды certbot register --agree-tos --email [ваше[email protected]] - Примечание: Вам не нужно будет выполнять этот шаг в будущем, когда вы будете генерировать дополнительные сертификаты на том же сервере.
3. Сгенерируйте сертификат для домена, чей DNS указывает на этот сервер: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Перезапустите все, что слушало на портах 80 и 443 до этого.
5. Обновите конфигурацию TLS вашего виртуального хоста веб-сервера, чтобы указать на новый сертификат (fullchain.pem) и закрытый ключ (privkey.pem), который только что сгенерировал Certbot для домена, который вы указали в команде certbot.
6. Перезагрузите или перезапустите веб-сервер, чтобы он использовал новую конфигурацию виртуального хоста HTTPS.

Автоматическое обновление сертификатов Certbot

По умолчанию эта роль добавляет задание cron, которое будет обновлять все установленные сертификаты раз в день в час и минуту по вашему выбору.

Вы можете протестировать автоматическое обновление (без фактического обновления сертификата) с помощью команды:

/opt/certbot/certbot-auto renew --dry-run

Смотрите полную документацию и опции на веб-сайте Certbot.

Лицензия

MIT / BSD

Информация об авторе

Эта роль была создана в 2016 году Джеффом Гирлингом, автором Ansible для DevOps.