Ansible Rolle: Certbot (für Let's Encrypt)

Installiert und konfiguriert Certbot (für Let's Encrypt).

Anforderungen

Wenn du aus dem Quellcode installierst, benötigst du Git. Du kannst Git mit der Rolle geerlingguy.git installieren.

Im Allgemeinen führt die Installation aus dem Quellcode (siehe Abschnitt „Quellinstallation von Git“) zu einer besseren Erfahrung mit Certbot und Let's Encrypt, besonders wenn du eine ältere Betriebssystemversion verwendest.

Rollenvariablen

certbot_install_method: package

Steuert, wie Certbot installiert wird. Verfügbare Optionen sind „package“, „snap“ und „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"

Standardmäßig konfiguriert diese Rolle einen Cron-Job, der unter dem angegebenen Benutzerkonto zu der angegebenen Stunde und Minute jeden Tag ausgeführt wird. Die Standardwerte führen certbot renew (oder certbot-auto renew) täglich um 03:30:00 durch, mit dem Benutzer, den du in deinem Ansible-Playbook verwendest. Es wird empfohlen, einen benutzerdefinierten Benutzer/Stunde/Minute festzulegen, damit die Erneuerung in einer verkehrsarmen Zeit erfolgt und von einem Nicht-Root-Benutzerkonto durchgeführt wird.

Automatische Zertifikatserstellung

Aktuell werden die Methoden standalone und webroot unterstützt, um neue Zertifikate mit dieser Rolle zu erstellen.

Für ein vollständiges Beispiel: siehe das voll funktionsfähige Test-Playbook in molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false

Setze certbot_create_if_missing auf yes oder True, damit diese Rolle Zertifikate erstellt.

certbot_create_method: standalone

Setze die Methode, die zur Erstellung von Zertifikaten mit der Variablen certbot_create_method verwendet wird – die aktuell zulässigen Werte sind: standalone oder webroot.

certbot_testmode: false

Aktiviere den Testmodus, um nur eine Testanforderung auszuführen, ohne tatsächlich Zertifikate zu erstellen.

certbot_hsts: false

Aktiviere (HTTP Strict Transport Security) für die Zertifikatserstellung.

certbot_admin_email: email@example.com

Die E-Mail-Adresse, die verwendet wird, um den TOS von Let's Encrypt zuzustimmen und sich für cert-bezogene Benachrichtigungen anzumelden. Diese sollte angepasst und auf eine E-Mail-Adresse eingestellt werden, die du oder deine Organisation regelmäßig überwachen.

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

Eine Liste von Domains (und weiteren Daten), für die Zertifikate erstellt werden sollen. Du kannst jedem Listenelement einen email-Schlüssel hinzufügen, um die certbot_admin_email zu überschreiben. Wenn du die Methode webroot verwendest, muss ein webroot-Element angegeben werden, das angibt, welches Verzeichnis für die Authentifizierung verwendet werden soll. Stelle sicher, dass dein Webserver Inhalte aus diesem Verzeichnis korrekt ausliefert.

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

Der certbot_create_command definiert den Befehl, der zur Erstellung des Zertifikats verwendet wird. Siehe den vollständigen Standardbefehl in defaults/main.yml für ein vollständiges Beispiel – und du kannst einfach zusätzliche Argumente hinzufügen, die nicht im Standardbefehl enthalten sind, mit der Variablen certbot_create_extra_args.

Standalone Zertifikatserstellung

certbot_create_standalone_stop_services:
  - nginx

Dienste, die gestoppt werden sollen, während certbot seinen eigenen Standalone-Server auf den Ports 80 und 443 ausführt. Wenn du Apache verwendest, setze dies auf apache2 (Ubuntu) oder httpd (RHEL), oder wenn du Nginx auf Port 443 und etwas anderes auf Port 80 (z.B. Varnish, eine Java-Anwendung oder etwas anderes) hast, füge es der Liste hinzu, damit es gestoppt wird, wenn das Zertifikat erstellt wird.

Diese Dienste werden nur beim ersten Mal gestoppt, wenn ein neues Zertifikat erstellt wird.

Snap-Installation

Seit Dezember 2020 haben die Certbot-Maintainer beschlossen, die Installation von Certbot über Snap zu empfehlen, anstatt Skripte wie certbot-auto zu pflegen.

Das Setzen von certbot_install_method: snap konfiguriert diese Rolle, um Certbot über Snap zu installieren.

Dieser Installationsmodus ist derzeit experimentell und funktioniert möglicherweise nicht über alle Linux-Distributionen hinweg.

Webroot Zertifikatserstellung

Wenn du die Methode webroot verwendest, muss für jedes certbot_certs-Element ein webroot-Element angegeben werden, das angibt, welches Verzeichnis für die Authentifizierung verwendet werden soll. Stelle auch sicher, dass dein Webserver Inhalte aus diesem Verzeichnis korrekt ausliefert.

Quellinstallation von Git

Du kannst Certbot aus seinem Git-Quellrepository installieren, wenn gewünscht, mit certbot_install_method: source. Dies kann in mehreren Fällen nützlich sein, insbesondere wenn ältere Distributionen keine Certbot-Pakete verfügbar haben (z.B. CentOS < 7, Ubuntu < 16.10 und Debian < 8).

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

Certbot-Git-Repository-Optionen. Wenn du aus dem Quellcode installierst, wird das konfigurierte certbot_repo geklont, wobei die Einstellung certbot_version respektiert wird. Wenn certbot_keep_updated auf yes gesetzt ist, wird das Repository jedes Mal aktualisiert, wenn diese Rolle ausgeführt wird.

certbot_dir: /opt/certbot

Das Verzeichnis, in dem Certbot geklont wird.

Wildcard-Zertifikate

Let's Encrypt unterstützt die Erstellung von Wildcard-Zertifikaten, aber der Prozess zur Erstellung und Verwendung ist etwas komplexer. Siehe Kommentare in diesem Pull Request für ein Beispiel, wie diese Rolle zur Verwaltung von Wildcard-Zertifikaten verwendet werden kann.

Michael Porter hat auch eine Schritt-für-Schritt-Anleitung Zertifikatserstellung mit Ansible für Let's Encrypt Wildcard speziell für Cloudflare.

Abhängigkeiten

Keine.

Beispiel-Playbook

- hosts: servers

  vars:
    certbot_auto_renew_user: dein_benutzername_hier
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - geerlingguy.certbot

Siehe andere Beispiele im Verzeichnis tests/.

Manuelles Erstellen von Zertifikaten mit certbot

Hinweis: Du kannst diese Rolle Zertifikate automatisch erstellen lassen; siehe die Dokumentation zur "Automatischen Zertifikatserstellung" weiter oben.

Du kannst Zertifikate manuell mit dem Skript certbot (oder certbot-auto) erstellen (verwende letsencrypt auf Ubuntu 16.04 oder verwende /opt/certbot/certbot-auto, wenn du aus dem Quellcode/Git installierst). Hier sind einige Beispielbefehle, um Zertifikate mit Certbot zu konfigurieren:

# Zertifikate für alle Apache-virtuellen Hosts automatisch hinzufügen (mit Vorsicht verwenden!).
certbot --apache

# Zertifikate erstellen, aber Apache-Konfiguration nicht ändern (sicherer).
certbot --apache certonly

Wenn du den Prozess zum Hinzufügen eines neuen Zertifikats vollständig automatisieren möchtest, aber nicht die integrierte Funktionalität dieser Rolle verwenden möchtest, kannst du dies mit den Befehlszeilenoptionen tun, um zu registrieren, den Nutzungsbedingungen zuzustimmen und dann ein Zertifikat mit dem Standalone-Server zu erstellen:

1. Stelle sicher, dass alle Dienste, die auf den Ports 80 und 443 hören (Apache, Nginx, Varnish usw.), gestoppt sind.
2. Registriere dich mit einem Befehl wie certbot register --agree-tos --email [[email protected]] - Hinweis: Dieser Schritt ist in Zukunft beim Erstellen weiterer Zertifikate auf demselben Server nicht erforderlich.
3. Erstelle ein Zertifikat für eine Domain, deren DNS auf diesen Server zeigt: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Starte alle Dienste, die zuvor auf den Ports 80 und 443 gehört haben, neu.
5. Aktualisiere die TLS-Konfiguration des virtuellen Hosts deines Webservers, damit sie auf das neue Zertifikat (fullchain.pem) und den privaten Schlüssel (privkey.pem) zeigt, die Certbot gerade für die Domain erstellt hat, die du im certbot-Befehl übergeben hast.
6. Lade deinen Webserver neu oder starte ihn neu, damit er die neue HTTPS-virtuellen Hostkonfiguration verwendet.

Automatische Zertifikatserneuerung mit Certbot

Standardmäßig fügt diese Rolle einen Cron-Job hinzu, der alle installierten Zertifikate einmal täglich zu der von dir gewählten Stunde und Minute erneuert.

Du kannst die automatische Erneuerung (ohne das Zertifikat tatsächlich zu erneuern) mit dem Befehl testen:

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

Siehe die vollständige Dokumentation und Optionen auf der Certbot-Website.

Lizenz

MIT / BSD

Autor Informationen

Diese Rolle wurde 2016 von Jeff Geerling erstellt, dem Autor von Ansible for DevOps.