nickjj.acme_sh

Was ist ansible-acme-sh?

Es handelt sich um ein Ansible Role, um:

• acme.sh zu installieren, um SSL-Zertifikate von Let's Encrypt auszustellen, zu erneuern oder zu löschen.
• Zertifikate für einzelne, mehrere oder Wildcard-Domains auszustellen.
• Mehrere Domains über 1 Zertifikat oder separate Zertifikate zu konfigurieren.
• DNS-basierte Herausforderungen mit der automatisierten DNS-API-Funktion von acme.sh durchzuführen.
• Benutzerdefinierte acme.sh-Befehle auszuführen, falls die Voreinstellungen nicht ausreichen.

Warum möchtest du dieses Role verwenden?

Dieses Role verwendet acme.sh, ein eigenständiges Bash-Skript, das sich um alle Komplexitäten der Ausstellung und automatischen Erneuerung deiner SSL-Zertifikate kümmert.

Die Ziele dieses Roles sind hohe Konfigurierbarkeit, aber auch vernünftige Standardwerte, sodass du nur eine Liste von Domainnamen angeben, deinen DNS-Anbieter einstellen und den API-Schlüssel deines DNS-Anbieters angeben musst, um loszulegen.

Es ist auch idempotent für jede Aufgabe, da das mein Ansatz ist!

Warum sind DNS-basierte Herausforderungen die einzige unterstützte Methode?

Eine Herausforderung über DNS zu erledigen, bedeutet, dass du deine Zertifikate einrichten kannst, bevor dein Webserver oder Proxy bereitgestellt ist. Es bedeutet auch, dass dein Webserver nichts über die Funktionsweise der ACME-Herausforderung wissen muss. Du musst nur die endgültigen Zertifikate, die dieses Role erstellt, referenzieren.

Ein weiterer Vorteil ist, dass, wenn du einen Webserver innerhalb von Docker betreibst, dieser möglicherweise nicht läuft, bevor dein Server von Ansible bereitgestellt wird. Zum Beispiel ist es üblich, git-basierte Deployments zu verwenden, um ein App-Deployment zu starten.

Außerdem ist es praktisch, DNS-Herausforderungen zu verwenden, da diese die einzige Möglichkeit sind, Wildcard-Zertifikate mit Let's Encrypt auszustellen. Es schien sinnvoll, die Bemühungen auf eine Lösung zu konzentrieren, die mit allen Zertifikatstypen funktioniert.

Das heißt, ich werde wahrscheinlich keine anderen Methoden wie Standalone, Webroot, Nginx oder Apache unterstützen, aber nichts ist in Stein gemeißelt.

Unterstützte Plattformen

• Ubuntu 16.04 LTS (Xenial)
• Ubuntu 18.04 LTS (Bionic)
• Debian 8 (Jessie)
• Debian 9 (Stretch)

Rollenspezifische Variablen

# Der Benutzer, unter dem acme.sh auf dem System ausgeführt wird. Beachte, dass dieser Benutzer 
# bereits existieren muss. Dieses Role erstellt ihn nicht.
acme_sh_become_user: "root"

# Abhängigkeiten des acme.sh-Pakets. Die Standardwerte gelten für Debian / Ubuntu.
# Für CentOS und Fedora kann "cron" durch "crond" ersetzt werden.
acme_sh_dependencies: ["cron", "git", "wget"]

# Das Git-Repository von acme.sh, das geklont wird.
acme_sh_git_url: "https://github.com/acmesh-official/acme.sh"

# Der Branch, das Tag oder der Commit, der geklont wird.
acme_sh_git_version: "master"

# Wenn du dieses Repository jetzt klonst und in 6 Monaten erneut klonst,
# bleibt es bei der alten Master-Version von vor 6 Monaten.
# Wenn du bei jedem Lauf die neueste Master-Version abrufen möchtest, setze dies auf True.
acme_sh_git_update: False

# Wohin wird dieses Repository geklont?
acme_sh_git_clone_dest: "/usr/local/src/acme.sh"

# Wenn aktiviert, wird acme.sh sich auf die neueste Version aktualisieren, was 
# unabhängig von der Aktualisierung des Git-Repos ist. Das liegt daran, dass acme.sh 
# sich mit einem Installer nach dem Klonen des Quellcodes installiert.
#
# Dies könnte gut sein, um die neueste Version mit Fehlerbehebungen zu erhalten,
# aber bedenke, dass du dadurch bei jedem Lauf unterschiedliche Ergebnisse erhalten 
# kannst. Ich empfehle, dies gelegentlich auf True zu setzen, es aber normalerweise 
# deaktiviert zu lassen.
acme_sh_upgrade: False

# Bei aktivierter Option werden der geklonte Quellcode, der Installationspfad,
# die Protokolldateien und die Erneuerung der Cron-Jobs entfernt.
#
# Installierte Zertifikate werden nicht entfernt. Wenn du die installierten
# Zertifikate entfernen möchtest, gibt es eine andere Option dafür, die wir später 
# besprechen werden.
acme_sh_uninstall: False

# Bei der Erstellung eines initialen Let's Encrypt-Kontos kannst du optional
# eine E-Mail-Adresse angeben. Standardmäßig ist dies nicht festgelegt, aber 
# du kannst gerne deine E-Mail-Adresse eingeben, wenn du möchtest. 
# Wenn du es festlegst, erhältst du eine E-Mail, wenn deine
# Zertifikate innerhalb von 20 Tagen ablaufen.
#
# Ich empfehle dringend, dies festzulegen, da du, sofern alles nach Plan läuft, 
# nie eine E-Mail erhältst, es sei denn, acme.sh ist fehlerhaft und konnte 
# ein Zertifikat nicht erneuern.
acme_sh_account_email: ""

# Zertifikate werden über einen von acme.sh verwalteten Cron-Job erneuert. 
# Standardmäßig verwendet acme.sh 60 Tage für jeden Erneuerungsversuch, 
# ich habe mich jedoch entschieden, standardmäßig 30 Tage zu wählen,
# um 1 zusätzlichen Versuch zu geben, falls unvorhergesehenes passiert.
#
# Zertifikate, die nicht erneuert werden müssen, werden von acme.sh übersprungen. 
# Es ist auch erwähnenswert, dass dieser Wert nicht > 60 Tage sein kann, 
# dies ist eine von acme.sh durchgesetzte Grenze; dieses Role überprüft den Wert nicht.
acme_sh_renew_time_in_days: 30

# Der Basis-Pfad, in den die Zertifikate kopiert werden. 
# Wenn du mit acme.sh vertraut bist, ist dies für die mit --install-cert generierten Zertifikate.
#
# Dies ist das endgültige Ziel für deine Zertifikate, und der Benutzer, den du gewählt hast,
# benötigt Schreibzugriff auf diesen Pfad. Dieser Pfad wird als 
# Eigentümer:Gruppe auf den Wert von acme_sh_become_user gesetzt.
acme_sh_copy_certs_to_path: "/etc/ssl/ansible"

# Am Ende des Laufs wird eine Ansible-Debug-Nachricht eine Liste der
# Domains ausgeben, die gültige SSL-Zertifikate besitzen, zusammen mit ihren 
# Ablaufdaten. Du kannst dies deaktivieren, indem du es auf False setzt.
acme_sh_list_domains: True

# Wenn auf False gesetzt, wird der Live-Server von Let's Encrypt verwendet.
# Stelle also sicher, dass alles mit Staging True funktioniert, 
# oder du könntest auf eine Rate-Limitierung stoßen.
#
# Es ist erwähnenswert, dass du einen neuen Zertifikatsantrag erzwingen musst, 
# wenn du zwischen Staging und Live wechselst oder umgekehrt.
acme_sh_default_staging: True

# Wenn auf True gesetzt, wird dies ein neues Zertifikat regenerieren, 
# auch wenn sich deine Liste von Domains nicht geändert hat. 
# Es wird auch verwendet, um einen neuen DNS-Anbieter und API-Schlüssel einzustellen.
#
# Sei vorsichtig damit, denn du könntest rate-limitiert werden, wenn du dich auf 
# dem Live-Server befindest. Überlege dir, dies nur zu verwenden, um 
# deinen DNS-Anbieter zu aktualisieren. Setze es auf False, wenn du fertig bist.
acme_sh_default_force_issue: False

# Wenn auf True gesetzt, wird dies ein neues Zertifikat für eine bestehende Liste 
# von Zertifikaten regenerieren. Dies wird deinen DNS-Anbieter oder API-Schlüssel 
# nicht aktualisieren.
#
# Dies könnte nützlich sein, wenn deine Zertifikate abgelaufen sind. Setze es 
# auf False zurück, wenn du fertig bist.
acme_sh_default_force_renew: False

# Wenn auf True gesetzt, gibt dies detailliertere Informationen an STDOUT aus.
# Dies könnte nützlich sein, wenn du das Role im Staging-Modus testest.
acme_sh_default_debug: False

# Welchen DNS-Anbieter solltest du verwenden?
# Eine Liste der unterstützten Anbieter findest du unter:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
# Den Namen, den du verwenden kannst, findest du ebenfalls unter der oben angegebenen URL.
#
# Standardmäßig wird DigitalOcean verwendet. Stelle sicher, dass du den 
# dns_ Teil des Namens angibst, aber die .sh-Dateierweiterung weglässt.
acme_sh_default_dns_provider: "dns_dgon"

# Was sind die API-Schlüssel deines DNS-Anbieters?
# Die zu verwendenden Schlüsselnamen findest du unter:
#   https://github.com/acmesh-official/acme.sh/tree/master/dnsapi
#
# Der API-Schlüssel kann auf der Website deines DNS-Anbieters erstellt werden. 
# Einige Anbieter benötigen 1 Schlüssel, während andere 2+ benötigen. 
# Füge sie hier einfach als Schlüssel/Wert-Paare ohne "export " hinzu.
#
# Wenn du zum Beispiel DigitalOcean verwendest, würdest du eingeben:
#    acme_sh_default_dns_provider_api_keys:
#      "DO_API_KEY": "THE_API_SECRET_TOKEN_FROM_THE_DO_DASHBOARD"
acme_sh_default_dns_provider_api_keys: {}

# Wie lange sollte acme.sh warten, nachdem versucht wurde, den TXT-Eintrag 
# zu deinen DNS-Einträgen zu setzen? Einige DNS-Anbieter aktualisieren 
# nicht so schnell wie andere.
#
# 120 ist der Standardwert von acme.sh selbst, aber bedenke, wenn du 
# NameSilo verwendest, propagieren deren DNS-Updates nur einmal alle 15 Minuten, 
# also musst du diesen Wert auf 900 setzen, oder du riskierst einen DNS 
# NXDOMAIN-Fehler.
#
# Ich empfehle, es auf 120 oder mehr zu setzen, falls dein DNS-Anbieter dies erfordert.
#
# Nebenbei bemerkt, ich habe 10 verwendet, als ich dieses Role gegen DigitalOcean getestet habe,
# und es hat etwa 30 Mal hintereinander funktioniert. Trotzdem würde ich in der Produktion 
# 120 verwenden, nur um auf der sicheren Seite zu sein, da diese 2-minütige Verzögerung 
# dich nur beim ersten Ansible-Lauf betreffen wird. Danach wird es im Hintergrund durch 
# einen Cron-Job aktualisiert.
acme_sh_default_dns_sleep: 120

# Bei der Ausstellung neuer Zertifikate kannst du zusätzliche Flags hinzufügen, 
# die hier standardmäßig nicht vorhanden sind. Gib sie an, wie du es in 
# der Befehlszeile tun würdest, z.B. "--help".
acme_sh_default_extra_flags_issue: ""

# Bei der Erneuerung von Zertifikaten kannst du zusätzliche Flags angeben, 
# die hier standardmäßig nicht vorhanden sind. Gib sie an, wie du es in 
# der Befehlszeile tun würdest, z.B. "--help".
acme_sh_default_extra_flags_renew: ""

# Bei der Installation von Zertifikaten kannst du zusätzliche Flags angeben, 
# die hier standardmäßig nicht vorhanden sind. Gib sie an, wie du es in 
# der Befehlszeile tun würdest, z.B. "--help".
#
# Die Installation unterscheidet sich von der Ausstellung, dies werden wir später 
# noch erklären.
acme_sh_default_extra_flags_install_cert: ""

# Wenn ein Zertifikat ausgestellt oder erneuert wird, versucht acme.sh, einen 
# von dir gewählten Befehl auszuführen. Dies könnte zum Neustarten oder 
# Neuladen deines Webservers oder Proxys dienen.
#
# Beachte, dass der Benutzer, den du in acme_sh_become_user gesetzt hast, 
# Zugriffsrechte für sudo benötigen muss, wenn du hier sudo verwendest, 
# oder, wenn nicht, Zugriffsrechte für das Neuladen deines Webservers / Proxys.
#
# Für ein Docker-Beispiel schaue dir den Beispiels Abschnitt in diesem README an.
acme_sh_default_install_cert_reloadcmd: "sudo systemctl reload nginx"

# Wenn du mehr Kontrolle als reloadcmd benötigst, kannst du in den Lebenszyklus 
# der Ausstellung oder Erneuerung eines Zertifikats eingreifen. 
# Standardmäßig tun die folgenden 3 Optionen nichts, es sei denn, du füllst sie aus. 
# Sie sind nicht erforderlich, damit alles funktioniert, solange dein reloadcmd funktioniert.
#
# Wenn ein Zertifikat ausgestellt oder erneuert wird, versucht acme.sh, einen Befehl auszuführen 
# bevor versucht wird, ein Zertifikat auszustellen. 
# Dies kann nur bei der Ausstellung eines Zertifikats angewendet werden, 
# wird aber auch für die Erneuerung gespeichert und verwendet.
#
# Dies wird auch ausgeführt, wenn das Zertifikat nicht erfolgreich ausgestellt / erneuert wurde.
acme_sh_default_issue_pre_hook: ""

# Wenn ein Zertifikat ausgestellt oder erneuert wird, wird acme.sh versuchen, 
# einen Befehl auszuführen, nachdem es versucht hat, ein Zertifikat auszustellen. 
# Dies kann nur bei der Ausstellung eines Zertifikats angewendet werden, 
# wird aber auch für die Erneuerung gespeichert und verwendet.
#
# Dies wird auch ausgeführt, wenn das Zertifikat nicht erfolgreich ausgestellt / erneuert wurde.
acme_sh_default_issue_post_hook: ""

# Wenn ein Zertifikat ausgestellt oder erneuert wird, wird acme.sh versuchen, 
# einen Befehl auszuführen, nachdem das Zertifikat erfolgreich erneuert wurde.
# Dies kann nur bei der Ausstellung eines Zertifikats angewendet werden, 
# wird aber auch für die Erneuerung gespeichert und verwendet.
#
# Dies wird nur ausgeführt, wenn das Zertifikat erfolgreich ausgestellt / erneuert wurde.
acme_sh_default_issue_renew_hook: ""

# Wenn auf True gesetzt, werden Zertifikate entfernt 
# und die Erneuerung wird anstelle der Erstellung deaktiviert. 
# Dies deinstalliert acme.sh nicht.
acme_sh_default_remove: False

# Diese Liste enthält eine Liste von Domains, 
# zusammen mit Schlüssel/Wert-Paaren zur individuellen Konfiguration 
# jeder Gruppe von Domains.
#
# Hier ist ein Beispiel mit jeder verfügbaren Option dokumentiert, und ein paar 
# reale Beispiele werden ebenfalls im Beispiels Abschnitt dieses README enthalten sein:
acme_sh_domains:
#  Eine Liste von 1 oder mehreren Domains, 
#  du kannst ["example.com", "*.example.com"] oder
#  ["*.example.com", "example.com"] für die Verwendung eines Wildcard-Zertifikats zusammen
#  mit dem Root-Domain-Zertifikat in derselben Datei verwenden. 
#  Die erste Domain in der Liste wird als Basisdateiname für den Zertifikatsnamen verwendet.
#
#  Wenn du separate Dateien möchtest, erstelle einen neuen "domains:"-Eintrag in der Liste.
#  - domains: ["example.com", "www.example.com", "admin.example.com"]
#    # optional die Standardstaging-Variable überschreiben. 
#    # Dieses Gesamtmuster lässt dich die oben aufgeführten Defaults 
#    # für jede Domainliste situativ überschreiben.
#    staging: False
#    # optional neue Zertifikate fordern.
#    force_issue: False
#    # optional Zertifikate erneuern.
#    force_renew: False
#    # optional den Debugmodus aktivieren.
#    debug: True
#    # optional den Standard-DNS-Anbieter überschreiben.
#    dns_provider: "dns_namesilo"
#    # optional den Standard-API-Schlüssel des DNS-Anbieters überschreiben.
#    dns_provider_api_keys:
#     "Namesilo_Key": "THE_API_SECRET_TOKEN_FROM_THE_NAMESILO_DASHBOARD"
#    # optional die Standard-DNS-Schlafzeit überschreiben.
#    dns_sleep: 900
#    # optional zusätzliche Flags für eine dieser 3 Aktionen hinzufügen:
#    extra_flags_issue: ""
#    extra_flags_renew: ""
#    extra_flags_install_cert: ""
#    # optional einen anderen Neuladebefehl festlegen.
#    install_cert_reloadcmd: "whoami"
#    # optional Befehle zu verschiedenen Zeitpunkten des Zertifikatserteilungsprozesses ausführen:
#    extra_issue_pre_hook: ""
#    extra_issue_post_hook: ""
#    extra_issue_renew_hook: ""
#    # optional das Zertifikat entfernen und deaktivieren.
#    remove: True

Beispielnutzung

Für dieses Beispiel nehmen wir an, du hast eine Gruppe namens app und du hast eine typische site.yml-Datei.

Um dieses Role zu verwenden, bearbeite deine site.yml-Datei, sodass sie so aussieht:

---

- name: App-Server(s) konfigurieren
  hosts: "app"
  become: True

  roles:
    - { role: "nickjj.acme_sh", tags: ["acme_sh"] }

Hier einige Beispiele. Du kannst dieses Beispiel auf deiner Seite nachstellen, indem du group_vars/app.yml öffnest oder erstellst, das sich relativ zu deinem inventory-Verzeichnis befindet, und es so aussehen lässt:

---

acme_sh_account_email: "[email protected]"

# Ein Beispiel, wo ein DNS-Anbieter 2 Schlüssel für den API-Zugriff hat:
acme_sh_default_dns_provider: "dns_cf"
acme_sh_default_dns_provider_api_keys:
  "CF_Key": "THE_API_SECRET_TOKEN_FROM_THE_CLOUDFLARE_DASHBOARD"
  "CF_Email": "[email protected]"

# Nginx im Docker-Container neu laden, der "nginx" heißt.
# Wenn du Nginx in einem Docker-Container ausführst, musst du auch deine Zertifikate 
# im Volume einbinden, aber das wusstest du sicherlich schon!
acme_sh_default_install_cert_reloadcmd: "docker exec nginx nginx -s reload"

# --- Hier sind einige verschiedene acme_sh_domains-Beispiele --------------------------
# Du müsstest nur eines von diesen angeben, je nachdem, was du tun möchtest!
# ------------------------------------------------------------------------------

# 1 Zertifikat für alle Domains.
acme_sh_domains:
  - domains: ["example.com", "www.example.com", "admin.example.com"]

# Erzeugt dies auf deinem Server:
#   /etc/ssl/ansible/example.com.key (der private Schlüssel)
#   /etc/ssl/ansible/example.com.pem (das vollständige Kettenzertifikat)

# ------------------------------------------------------------------------------

# 2 Zertifikatdateien unter Verwendung der gleichen Domains wie oben.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]

# Erzeugt dies auf deinem Server:
#   /etc/ssl/ansible/example.com.key (der private Schlüssel)
#   /etc/ssl/ansible/example.com.pem (das vollständige Kettenzertifikat)
#   /etc/ssl/ansible/admin.example.com.key (der private Schlüssel)
#   /etc/ssl/ansible/admin.example.com.pem (das vollständige Kettenzertifikat)

# ------------------------------------------------------------------------------

# 2 Zertifikatdateien unter Verwendung des gleichen Beispiels, aber das Admin-Zertifikat 
# wird entfernt und deaktiviert.
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    remove: True

# Erzeugt dies auf deinem Server:
#   /etc/ssl/ansible/example.com.key (der private Schlüssel)
#   /etc/ssl/ansible/example.com.pem (das vollständige Kettenzertifikat)

# ------------------------------------------------------------------------------

# 2 Zertifikatdateien unter Verwendung des gleichen Beispiels, aber beim Admin-Zertifikat 
# wird von Staging auf Live gewechselt (aber denke daran, force_issue nach dem ersten Lauf 
# zu entfernen).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    staging: False
    force_issue: True

# ------------------------------------------------------------------------------

# 2 Zertifikatdateien unter Verwendung des gleichen Beispiels, aber beim Admin-Zertifikat wird 
# eine Erneuerung erzwungen (sagen wir, ein katastrophaler Fehler ist passiert und das Zertifikat ist abgelaufen).
acme_sh_domains:
  - domains: ["example.com", "www.example.com"]
  - domains: ["admin.example.com"]
    force_renew: True

Wenn du nach einem Ansible-Role zum Erstellen von Benutzern suchst, schau dir mein Benutzer-Role an.

Jetzt würdest du ansible-playbook -i inventory/hosts site.yml -t acme_sh ausführen.

Installation

$ ansible-galaxy install nickjj.acme_sh

Ansible Galaxy

Du findest es auf dem offiziellen Ansible Galaxy, wenn du es bewerten möchtest.

Lizenz

MIT