certbro

certbro ist ein quelloffenes Kommandozeilenwerkzeug für die regfish TLS-API und DNS-API. Es bündelt Bestellung, Domainvalidierung, Download, Schlüsselrotation, Auslieferung und Verlängerung in einem Befehl, statt jeden Schritt einzeln zu skripten.

Quellcode und Releases: github.com/regfish/certbro (Go, Apache 2.0, ohne externe Abhängigkeiten).

Voraussetzungen

Linux (macOS wird vom Installer unterstützt, die systemd-Automatik nicht)
ein regfish-API-Key mit Zugriff auf TLS und DNS — siehe API-Key erstellen
eine über regfish verwaltete DNS-Zone (certbro legt die Validierungs-Records selbst an)
systemd für die unbeaufsichtigte Verlängerung

Installation

curl -fsSL https://regfish.com/certbro/install.sh | sh

Der Installer erkennt Betriebssystem und Architektur, lädt das passende Archiv von den GitHub-Releases, prüft die SHA256-Summe gegen checksums.txt und bricht bei Abweichung ab. Installiert wird nach /usr/local/bin/certbro.

Für einen reproduzierbaren Rollout die Version festnageln — die aktuelle steht bei den Releases:

curl -fsSL https://regfish.com/certbro/install.sh | CERTBRO_VERSION=v0.1.10 sh

Einrichten

sudo certbro configure --api-key YOUR_REGFISH_API_KEY

certbro prüft den Schlüssel vor dem Speichern gegen die API und merkt sich den Zeitpunkt der Prüfung. Ohne verifizierten Schlüssel verweigern alle weiteren Befehle den Dienst.

Ein Zertifikat bestellen

sudo certbro issue \
  --name example-com \
  --common-name example.com \
  --dns-name www.example.com \
  --webserver nginx

Pflicht ist nur --common-name. Die wichtigsten weiteren Schalter:

Flag	Standard	Bedeutung
`--name`	Kleinschreibung von `--common-name`	logischer Name, mit dem `renew` das Zertifikat wiederfindet
`--dns-name`	—	zusätzlicher Name (SAN), wiederholbar
`--product`	`RapidSSL`	wird gegen den Live-Katalog geprüft; verfügbare Produkte liefert `GET /tls/products`
`--key-type`	`rsa`	`rsa` oder `ecdsa`
`--webserver`	—	`nginx`, `apache` oder `caddy`
`--install-hook`	—	Shell-Befehl nach der Auslieferung
`--validity-days`	siehe unten	Laufzeit der Bestellung
`--org-id`	—	Organisations-Handle (`hdl_…`) für OV-Produkte

Für RSA und ECDSA parallel gibt es certbro issue-pair — es legt zwei Zertifikate mit den Suffixen -rsa und -ecdsa an und lädt den Webserver erst neu, wenn beide fertig sind.

Wo die Dateien liegen

Das ist die Stelle, die man kennen muss: certbro legt unter /etc/certbro/<common-name>/ drei Verzeichnisse an.

Verzeichnis	Inhalt
`live/`	die stabilen Pfade — `privkey.pem`, `cert.pem`, `chain.pem`, `fullchain.pem`, `metadata.json`, dazu `request.csr.pem` und `bundle.zip`, sofern vorhanden. Wird bei jeder Auslieferung überschrieben.
`archive/<Zeitstempel>/`	ein unveränderter Schnappschuss je Auslieferung
`pending/`	nur bei laufender Bestellung: privater Schlüssel, CSR und Bestellzustand. Verschwindet, sobald das Zertifikat ausgeliefert ist.

Die Webserver-Konfiguration zeigt auf live/, nie auf archive/. Die Pfade dort ändern sich nicht, deshalb muss der vhost nach einer Verlängerung nicht angefasst werden.

Webserver-Anbindung

Was jeweils ausgeführt wird:

Wert	Prüfen	Neuladen
`nginx`	`nginx -t`	`systemctl reload nginx`, sonst `nginx -s reload`
`apache`	`apachectl -t`	`apachectl -k graceful`, sonst `systemctl reload apache2`
`caddy`	`caddy validate`	`caddy reload`, sonst `systemctl reload caddy`

Mit --webserver-config lässt sich ein abweichender Konfigurationspfad angeben. Der Befehl aus --install-hook läuft nach dem Neuladen und bekommt die Pfade als Umgebungsvariablen (CERTBRO_LIVE_DIR, CERTBRO_FULLCHAIN_PATH, CERTBRO_PRIVKEY_PATH und weitere).

Laufzeit

Ohne --validity-days nimmt certbro die größte Laufzeit, die das CA/Browser-Forum gerade zulässt, minus einen Tag:

ab	Standard
heute	199 Tage
14.03.2027	99 Tage
14.03.2029	46 Tage

Der Wert muss größer sein als der Vorlauf für die Verlängerung, sonst lehnt certbro ihn ab — sonst liefe die Verlängerung in eine Endlosschleife.

Verlängern

sudo certbro renew

Ohne --name prüft certbro alle verwalteten Zertifikate. Fällig ist eines, wenn es in weniger als --renew-before-days (Standard: 7 Tage) abläuft. Ein einzelnes verlängerst du mit --name example-com, erzwingen lässt es sich mit --force.

Parallele Läufe verhindert certbro über eine Sperrdatei — der zweite Lauf endet mit einem Hinweis und Rückgabewert 0, stört also keinen Cron-Job.

Automatisch verlängern

sudo certbro install

Das legt eine systemd-Service- und eine Timer-Einheit an, aktiviert den Timer und lädt systemd neu. Der Timer läuft stündlich mit einer zufälligen Verzögerung von bis zu 30 Minuten, damit nicht alle Server gleichzeitig anfragen. Verpasste Läufe werden nachgeholt.

Ohne systemd tut es auch ein Cron-Eintrag:

17 3 * * * /usr/local/bin/certbro renew

Überblick behalten

sudo certbro list

zeigt je Zertifikat unter anderem Status, Namen, Schlüsseltyp, Ablaufdatum und ob eine Aktion aussteht. Mit --json ist die Ausgabe maschinenlesbar.

Was certbro nicht tut

Kein Widerrufen. Dafür gibt es POST /tls/certificate/{id}/revoke.
Kein Entfernen. Ein verwaltetes Zertifikat lässt sich per Befehl nicht wieder austragen — dazu das zugehörige Verzeichnis löschen.
Keine Webserver-Konfiguration. Siehe oben.
Keine fremden DNS-Records anfassen. Steht am Validierungsnamen bereits ein CNAME, der nicht von certbro stammt, bricht der Lauf ab und nennt den Namen. Der Record muss dann von Hand weg.
Nur DNS-Validierung. certbro nutzt ausschließlich dns-cname-token; E-Mail-Validierung unterstützt es nicht.

Weiterlesen

TLS-Automatisierung mit certbro — der vollständige Ablauf als Rezept
OV-Zertifikat mit certbro bestellen — mit Abschluss im dash
TLS-Endpunkte — die API, die certbro darunter nutzt