Rola Ansible: Certbot (dla Let's Encrypt)

Instaluje i konfiguruje Certbot (dla Let's Encrypt).

Wymagania

Jeśli instalujesz z źródła, potrzebny jest Git. Możesz zainstalować Git za pomocą roli geerlingguy.git.

Ogólnie rzecz biorąc, instalacja z źródła (zobacz sekcję Instalacja z Żródła z Git) prowadzi do lepszych doświadczeń z używaniem Certbot i Let's Encrypt, zwłaszcza jeśli korzystasz z starszej wersji systemu operacyjnego.

Zmienne roli

certbot_install_method: package

Kontroluje, jak Certbot jest instalowany. Dostępne opcje to 'package', 'snap' i '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"

Domyślnie ta rola konfiguruje zadanie cron, aby wykonywało się pod podanym kontem użytkownika o danej godzinie i minucie, codziennie. Domyślne wartości uruchamiają certbot renew (lub certbot-auto renew) codziennie o 03:30:00 przez użytkownika, którego używasz w swoim playbooku Ansible. Preferowane jest ustawienie niestandardowego użytkownika/godziny/minuty, aby odnawianie odbywało się w czasie niskiego ruchu i było wykonywane przez konto użytkownika, a nie roota.

Automatyczne generowanie certyfikatów

Obsługiwane są aktualnie metody standalone i webroot do generowania nowych certyfikatów z użyciem tej roli.

Aby zobaczyć pełny przykład: zobacz w pełni funkcjonalny testowy playbook w molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Ustaw certbot_create_if_missing na yes lub True, aby pozwolić tej roli na generowanie certyfikatów.

certbot_create_method: standalone

Ustaw metodę używaną do generowania certyfikatów za pomocą zmiennej certbot_create_method — aktualne dozwolone wartości to: standalone lub webroot.

certbot_testmode: false

Włącz tryb testowy, aby uruchomić tylko testowe żądanie bez faktycznego tworzenia certyfikatów.

certbot_hsts: false

Włącz (HTTP Strict Transport Security) dla generacji certyfikatu.

certbot_admin_email: email@example.com

Adres e-mail używany do akceptacji TOS Let's Encrypt i subskrypcji powiadomień związanych z certyfikatami. Powinien być dostosowany i ustawiony na adres e-mail, który Ty lub Twoja organizacja regularnie monitorujecie.

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

Lista domen (i inne dane), dla których mają być generowane certyfikaty. Możesz dodać klucz email do dowolnego elementu listy, aby nadpisać certbot_admin_email. Przy używaniu metody webroot musi być podany element webroot, określający, która katalog ma być użyty do uwierzytelniania. Upewnij się, że Twój serwer WWW poprawnie dostarcza zawartość z tego katalogu.

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 definiuje polecenie używane do generowania certyfikatu. Zobacz pełne domyślne polecenie w defaults/main.yml dla pełnego przykładu — możesz również łatwo dodać dodatkowe argumenty, które nie są w domyślnym poleceniu za pomocą zmiennej certbot_create_extra_args.

Generowanie certyfikatów w trybie standalone

certbot_create_standalone_stop_services:
  - nginx

Usługi, które powinny być zatrzymane, gdy certbot uruchomi własny serwer standalone na portach 80 i 443. Jeśli używasz Apache, ustaw to na apache2 (Ubuntu) lub httpd (RHEL), albo jeśli masz Nginx na porcie 443 i coś innego na porcie 80 (np. Varnish, aplikacja Java), dodaj to do listy, aby zostało zatrzymane podczas generacji certyfikatu.

Te usługi będą zatrzymywane tylko przy pierwszym generowaniu nowego certyfikatu.

Instalacja przez Snap

Począwszy od grudnia 2020 roku, utrzymujący Certbot zdecydowali o rekomendacji instalacji Certbot przez Snap zamiast utrzymywania skryptów takich jak certbot-auto.

Ustawienie certbot_install_method: snap konfiguruje tę rolę do instalacji Certbot za pomocą Snap.

Ta metoda instalacji jest obecnie na etapie eksperymentalnym i może, ale nie musi, działać na wszystkich dystrybucjach Linuxa.

Generowanie certyfikatów przez Webroot

Podczas używania metody webroot, musi być podany element webroot dla każdego elementu certbot_certs, określający, która katalog ma być użyty do uwierzytelniania. Upewnij się również, że Twój serwer WWW poprawnie dostarcza zawartość z tego katalogu.

Instalacja z źródła z Git

Możesz zainstalować Certbot z repozytorium źródłowego Git, jeśli chcesz, ustawiając certbot_install_method: source. Może to być użyteczne w kilku przypadkach, szczególnie gdy starsze dystrybucje nie mają dostępnych pakietów Certbot (np. CentOS < 7, Ubuntu < 16.10 i Debian < 8).

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

Opcje repozytorium Certbot Git. Jeśli instalujesz z źródła, skonfigurowane certbot_repo jest klonowane, szanując ustawienie certbot_version. Jeśli certbot_keep_updated jest ustawione na yes, repozytorium jest aktualizowane za każdym razem, gdy ta rola jest uruchamiana.

certbot_dir: /opt/certbot

Katalog, w którym Certbot będzie klonowany.

Certyfikaty Wildcard

Let's Encrypt obsługuje generowanie certyfikatów wildcard, ale proces ich generowania i używania jest nieco bardziej złożony. Zobacz komentarze w tym zgłoszeniu dla przykładu, jak użyć tej roli do utrzymywania certyfikatów wildcard.

Michael Porter również ma przewodnik na Tworzenie certyfikatu wildcard Let's Encrypt z Ansible, szczególnie z Cloudflare.

Zależności

Brak.

Przykładowy Playbook

- hosts: servers

  vars:
    certbot_auto_renew_user: twoja_nazwa_użytkownika
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Zobacz inne przykłady w katalogu tests/.

Ręczne tworzenie certyfikatów z certbot

Uwaga: Możesz sprawić, że ta rola automatycznie wygeneruje certyfikaty; zobacz powyższą dokumentację "Automatyczne generowanie certyfikatów".

Możesz ręcznie tworzyć certyfikaty przy użyciu skryptu certbot (lub certbot-auto) (użyj letsencrypt na Ubuntu 16.04, lub użyj /opt/certbot/certbot-auto jeśli instalujesz z źródła/Git). Oto przykłady poleceń służących do konfigurowania certyfikatów z Certbot:

# Automatycznie dodaj certyfikaty dla wszystkich wirtualnych hostów Apache (użyj ostrożnie!).
certbot --apache

# Generuj certyfikaty, ale nie zmieniaj konfiguracji Apache (bezpieczniej).
certbot --apache certonly

Jeśli chcesz w pełni zautomatyzować proces dodawania nowego certyfikatu, ale nie chcesz używać wbudowanej funkcjonalności tej roli, możesz to zrobić, używając opcji wiersza poleceń, aby zarejestrować, zaakceptować warunki świadczenia usług i następnie wygenerować certyfikat, używając serwera standalone:

1. Upewnij się, że wszelkie usługi nasłuchujące na portach 80 i 443 (Apache, Nginx, Varnish itp.) są zatrzymane.
2. Zarejestruj się za pomocą certbot register --agree-tos --email [[email protected]] - Uwaga: Nie będziesz musiał wykonywać tego kroku w przyszłości, podczas generowania dodatkowych certyfikatów na tym samym serwerze.
3. Wygeneruj certyfikat dla domeny, której DNS wskazuje na ten serwer: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Uruchom ponownie wszystko, co nasłuchiwało na portach 80 i 443 wcześniej.
5. Zaktualizuj konfigurację TLS swojego wirtualnego hosta w serwerze WWW, aby wskazywała na nowy certyfikat (fullchain.pem) i klucz prywatny (privkey.pem), które Certbot właśnie wygenerował dla domeny, którą podałeś w poleceniu certbot.
6. Przeładuj lub uruchom ponownie swój serwer WWW, aby korzystał z nowej konfiguracji wirtualnego hosta HTTPS.

Automatyczne odnawianie certyfikatów Certbot

Domyślnie ta rola dodaje zadanie cron, które odnowi wszystkie zainstalowane certyfikaty raz dziennie o godzinie i minucie, które wybierzesz.

Możesz przetestować automatyczne odnawianie (bez faktycznego odnawiania certyfikatu) za pomocą polecenia:

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

Zobacz pełną dokumentację i opcje na stronie Certbot.

Licencja

MIT / BSD

Informacje o autorze

Ta rola została stworzona w 2016 roku przez Jeffa Geerlinga, autora Ansible for DevOps.