Was dieses Modul tut #
Ein TLS-Zertifikat ist das, was http:// in https:// verwandelt: es verschlüsselt die Verbindung zwischen deinen Besuchern und dem Server und sorgt dafür, dass der Browser das Schloss anzeigt statt einer „nicht sicher"-Warnung.
Das Modul tls übernimmt den gesamten Lebenszyklus dieses Zertifikats mithilfe von certbot: es fordert es bei Let's Encrypt an (einer kostenlosen, gut anerkannten Zertifizierungsstelle), weist nach, dass die Domain dir gehört, über die ACME-Challenge, installiert das Zertifikat dort, wo dein Webserver es erwartet, und erneuert es automatisch, bevor es abläuft — ohne dass du daran denken musst.
Deine Domain (z. B. app.ejemplo.com) muss per DNS auf die IP dieses Servers zeigen, und Port 80 muss für die HTTP-01-Challenge erreichbar sein. Andernfalls schlägt die Ausstellung im Validierungsschritt fehl.
Häufige Aufgaben #
Wähle, was du tun möchtest. Jedes Rezept bringt den Befehl schon fertig mit — einfach deine eigene Domain und E-Mail einsetzen und Kopieren drücken.
1
Mein erstes Zertifikat ausstellen
Hol dir in einer Minute das HTTPS-Schloss für deine Domain.
Verbinde dich per SSH als Benutzer ubuntu mit deinem Server.
Führe den Befehl aus und setze deine eigene Domain und E-Mail ein (die E-Mail wird nur genutzt, um dich zu warnen, wenn etwas bald abläuft):
$ sudo imaxe tls issue app.ejemplo.com --email [email protected]Warte ein paar Sekunden. Du siehst den Fortschritt der Challenge und am Ende das Ablaufdatum.
https:// mit dem Schloss. Die automatische Erneuerung ist aktiviert — du musst nichts weiter tun.2
Sehen, welche existieren und wann sie ablaufen
Prüfe den Zustand deiner Zertifikate auf einen Blick.
Eine schnelle Übersicht über den Gesamtstatus und den Erneuerungs-Timer:
$ sudo imaxe tls statusWillst du das Detail Domain für Domain, mit verbleibenden Tagen und dem fullchain-Pfad? Nutze list:
$ sudo imaxe tls list3
Eine Erneuerung erzwingen
Sie ist normalerweise automatisch, aber du kannst sie bei Bedarf vorziehen.
Erneuere alle Zertifikate, die kurz vor dem Ablauf stehen (genau das tut der Timer):
$ sudo imaxe tls renewWillst du es zuerst proben, ohne die Festplatte anzurühren, oder erneuern, auch wenn noch Tage übrig sind? Füge --dry-run oder --force hinzu:
$ sudo imaxe tls renew --dry-run
$ sudo imaxe tls renew --force4
Ein Zertifikat widerrufen
Mache ein Zertifikat bei der Zertifizierungsstelle ungültig (z. B. wenn der Schlüssel geleakt ist).
Widerrufe das Zertifikat einer Domain bei Let's Encrypt und gib den Grund an, wenn du ihn kennst:
$ sudo imaxe tls revoke app.ejemplo.com --reason keycompromiseissue ein neues aus.5
Ein Zertifikat von der Festplatte löschen
Höre auf, eine Domain zu verwalten, die du nicht mehr nutzt.
Entferne das Zertifikat und seine Schlüssel von der Festplatte. Hinweis: dies widerruft es nicht bei der Zertifizierungsstelle — nutze dafür zuerst revoke.
$ sudo imaxe tls delete tienda.ejemplo.comimaxe tls list und ihre automatische Erneuerung stoppt.Das häufigste Problem ist, dass sich DNS noch nicht verbreitet hat oder Port 80 geschlossen ist. Warte ein paar Minuten und versuche es erneut. Bleibt es bestehen, probiere zuerst den Testmodus mit --staging (siehe die Referenz), damit du dein Kontingent an Versuchen nicht aufbrauchst.
Synopsis #
imaxe tls <subcomando> [<dominio>...] [--email CORREO] [flags]Unterbefehle, die Zertifikate berühren, erfordern root-Rechte (nutze sudo), da sie nach /etc/imaxe/ schreiben und Systemdienste neu laden. Füge --json zu list oder status hinzu, um maschinenlesbare Ausgabe für das Scripting zu erhalten.
Unterbefehle #
| Unterbefehl | Was er tut | Relevante Flags |
|---|---|---|
| issue | Stellt ein Zertifikat für eine oder mehrere Domains aus und löst die ACME-Challenge. | --email, --webroot, --standalone, --staging |
| renew | Erneuert Zertifikate kurz vor dem Ablauf und lädt den Webserver neu. Für einen Timer geeignet. | --dry-run, --force |
| list | Listet die verwalteten Zertifikate mit Tagen bis zum Ablauf und dem fullchain-Pfad auf. | --json |
| status | Zusammenfassung: Anzahl der Zertifikate, die kurz vor dem Ablauf stehenden und der Status des Erneuerungs-Timers. | --json |
| revoke | Widerruft ein Zertifikat nach Domain bei der Zertifizierungsstelle (ACME). | --reason |
| delete | Löscht das Zertifikat und seine Schlüssel von der Festplatte. Widerruft nicht bei ACME. | — |
Argumente und Flags #
| Flag | Typ | Standard | Beschreibung |
|---|---|---|---|
| <dominio> erf. | string… | — | Eine oder mehrere Domains für das Zertifikat. Bei issue ist die erste die primäre (CN); die restlichen sind SANs. Bei revoke/delete die Domain, auf der operiert wird. |
| string | tls.yml | Kontakt-E-Mail für das ACME-Konto. Beim ersten issue erforderlich; danach wird die aus tls.yml wiederverwendet. | |
| --webroot | path | /var/www/html | Wurzelverzeichnis für die HTTP-01-Challenge. Die Standardmethode. |
| --standalone | bool | false | Nutzt den in certbot integrierten Server statt eines Webroots. Erfordert, dass Port 80 frei ist. |
| --staging | bool | false | Nutzt die Testumgebung von Let's Encrypt (zählt nicht zum Rate-Limit). Dem Zertifikat wird nicht vertraut. |
| --dry-run | bool | false | Bei renew simuliert die Erneuerung, ohne die Festplatte anzurühren. |
| --force | bool | false | Bei renew erneuert, auch wenn der Ablauf nicht nahe ist. |
| --reason | enum | unspecified | Bei revoke: unspecified, keycompromise, superseded, cessationofoperation. |
| --json | bool | false | Bei list/status gibt das Ergebnis als JSON über stdout aus. |
Dateien und Pfade #
| Pfad | Inhalt |
|---|---|
| /etc/imaxe/tls.yml | Konfiguration des Moduls: Standard-E-Mail, Methode (webroot/standalone), Webroot, Staging, automatische Erneuerung und Reload-Hook. |
| /etc/letsencrypt/live/<dominio>/ | Zertifikat (fullchain.pem) und privater Schlüssel (privkey.pem), verwaltet von certbot. |
| /var/log/imaxe/tls.log | Strukturiertes Log jeder Ausstellung, Erneuerung und Widerrufung. |
| imaxe-tls.timer | systemd-Timer, der renew periodisch auslöst. |
Beispiel für tls.yml:
email: [email protected]
default_method: webroot
webroot: /var/www/html
staging: false
auto_renew: true
reload_hook: systemctl reload nginxExit-Codes und Logs #
Jede Ausführung liefert einen Code, den du mit echo $? prüfen kannst — nützlich zum Verketten in Skripten:
Verfolge das Log live, während du Fehler suchst:
$ sudo journalctl -u imaxe-tls -f
$ sudo tail -f /var/log/imaxe/tls.logFortgeschrittene Beispiele #
Mehrere Domains in einem einzigen Zertifikat
Die erste Domain ist die primäre; die folgenden werden als SANs hinzugefügt, alle in einem einzigen Zertifikat:
$ sudo imaxe tls issue ejemplo.com www.ejemplo.com \
--email [email protected]Ein sicherer Test vor der Produktion
Validiere die gesamte Kette gegen die Testumgebung, damit du dein echtes Kontingent nicht aufbrauchst. Mit --standalone brauchst du keinen konfigurierten Webserver:
$ sudo imaxe tls issue app.ejemplo.com \
--email [email protected] --standalone --staging \
|| echo "falló con código $?"Fehlerbehebung #
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Liefert CHALLENGE (Code 3) | Die Domain löst nicht auf diesen Host auf oder Port 80 ist geschlossen. | Prüfe den A/AAAA-Eintrag und öffne Port 80 in der Security Group; versuche es erneut. |
| Liefert RATELIMIT (Code 4) | Zu viele Ausstellungen derselben Domain in einer Woche. | Nutze --staging zum Testen; warte, bis das Zeitfenster wieder frei wird. |
| HTTPS lädt, aber mit einer Warnung | Mit --staging ausgestellt: dem Zertifikat wird nicht vertraut. | Stelle ohne --staging neu aus, um ein gültiges zu erhalten. |
| Liefert RELOAD (Code 5) | Der reload_hook verweist auf einen nicht existierenden Dienst. | Passe reload_hook in tls.yml an und führe renew erneut aus. |
Steckst du beim Modul TLS fest?
Schreib uns mit der Ausgabe von «imaxe <module> status --json» und wir antworten dir schnell.