Cert Tool 🔐

Das Cert Tool ist ein modulares Node.js Tool, mit dem du dir automatisch SSL/TLS Zertifikate von Let's Encrypt holst und sie direkt an beliebig viele Ziele verteilst - zum Beispiel per SSH auf einen Server, als PFX-Datei (z.B. für Jellyfin) oder direkt in eine OPNsense Firewall.

Alles läuft selbstständig im Hintergrund: Das Tool prüft von alleine, ob eine Erneuerung überhaupt nötig ist, holt sich bei Bedarf ein neues Zertifikat per DNS-01 Challenge und informiert dich am Ende per Mail oder Konsole über den Verlauf. 🚀

Der komplette Ablauf ist in einzelne Bausteine aufgeteilt (Trigger, Input, Middleware, Output, Notification). Jeder Baustein lässt sich einzeln austauschen, kombinieren oder erweitern.

Die Module werden automatisch anhand ihres Namens geladen wenn sie sich im richtigen Ordner befinden. Jedes Modul benötigt vor definierte Methoden (Trigger z.B. run()).

Ablauf 🔄

1. Ein Trigger startet den Lauf - entweder sofort oder nach einem Zeitplan.
2. Das Input Modul prüft, ob ein neues Zertifikat nötig ist, und holt es sich bei Bedarf per ACME DNS-01 Challenge von Let's Encrypt.
3. Für die DNS-01 Challenge trägt ein Middleware Modul den passenden TXT Record bei deinem DNS Provider ein. Middleware gehört dabei zum Input Modul und wird unter Input → Options → Middleware konfiguriert.
4. Die Output Module verteilen das fertige Zertifikat an die konfigurierten Ziele und führen danach optional noch Befehle aus, z.B. um einen Dienst neu zu starten.
5. Über die Notification Module bekommst du am Ende eine Rückmeldung über den Verlauf.

Features ✨

• 🔁 Automatische Erneuerung - ein Zertifikat wird nur erneuert, wenn es bald abläuft (einstellbar über renewAfter)
• 🌐 Unterstützt Wildcard Zertifikate (*.domain.tld) per DNS-01 Challenge
• 🧩 Komplett modularer Aufbau - jeder Baustein ist austauschbar
• 🖥️ Verteilung an beliebig viele Server per SSH/SCP inklusive Befehlen nach der Übertragung
• 🧱 OPNsense Integration über die REST API, inklusive automatischem Neustart von WebGUI/NGINX
• 📦 Erstellung einer PFX Datei für Systeme, die PKCS#12 benötigen
• ✉️ Benachrichtigung per E-Mail oder Konsole mit einstellbarem Log-Level
• ⏰ Ausführung sofort oder wiederkehrend per Cron Zeitplan
• 🐳 Lauffähig als Docker Container

Module 🧩

Jedes Modul wird in der Config über module (Dateiname/Ordnername) ausgewählt und bekommt seine eigenen options mitgegeben. Welche Felder options jeweils unterstützt, steht bei jedem Modul unten in der jeweiligen Options-Tabelle.

Trigger

Bestimmt, wann ein Lauf gestartet wird. Liegt als Array direkt unter trigger.

Modul	Beschreibung
now	Führt den Lauf sofort einmal aus.
cron	Führt den Lauf wiederkehrend nach einem Cron Zeitplan aus.

Options now

Keine - das Modul braucht keine Optionen.

Options cron

Parameter	Beschreibung
execution	Cron-Ausdruck, nach dem der Lauf wiederholt wird, z.B. "0 5 * * 7" für jeden Sonntag um 5 Uhr.

Input

Beschafft das Zertifikat. Liegt als einzelnes Objekt unter input.

Modul	Beschreibung
acme_dns	Holt bzw. erneuert ein Zertifikat direkt über eine ACME Bibliothek per DNS-01 Challenge bei Let's Encrypt. Unterstützt Wildcards und kann über skipCreation auch einfach nur ein bereits vorhandenes Zertifikat einlesen.
certbot	Alternative, die auf das certbot Tool des Systems zurückgreift.

ℹ️ Wichtig: Die Middleware Module gehören zum Input Modul und werden nicht auf oberster Ebene konfiguriert, sondern unter input.options.middleware als Array eingetragen - also Input → Options → Middleware.

Options acme_dns

Parameter	Beschreibung
domain	Die Hauptdomain, für die das Zertifikat ausgestellt wird.
wildcard	Wenn true, wird zusätzlich *.domain als Wildcard mit ins Zertifikat aufgenommen.
email	E-Mail Adresse, die beim Let's Encrypt Account hinterlegt wird.
directoryUrl	ACME Directory URL, z.B. das Produktiv- oder Staging-Directory von Let's Encrypt.
outputDir	Ordner, in dem Zertifikat (<domain>.crt) und Key (<domain>.key) abgelegt bzw. von dort eingelesen werden.
skipCreation	Wenn true, wird kein neues Zertifikat angefordert, sondern direkt das vorhandene aus outputDir eingelesen.
do	Muss true sein, damit überhaupt eine neue Anfrage bei Let's Encrypt gestellt werden darf (zusätzlich zur Prüfung, ob laut renewAfter eine Erneuerung fällig ist).
renewAfter	Anzahl Tage vor Ablauf, ab der das Zertifikat erneuert wird.
dnsPropagationDelay	Wartezeit in Millisekunden nach dem Setzen des TXT Records, bevor Let's Encrypt die Challenge prüft (Standard: 60000).
middleware	Array der DNS Middleware Module, die beim Setzen/Entfernen des TXT Records ausgeführt werden - siehe Middleware.

Options certbot

Parameter	Beschreibung
domain	Die Domain, für die per certbot ein Zertifikat angefordert wird.
email	E-Mail Adresse, die certbot bei Rückfrage automatisch einträgt.
test	Wenn true, wird der Let's Encrypt Staging-Server statt der Produktivumgebung verwendet.
skip_to_done	Wenn true, wird certbot nicht ausgeführt, sondern direkt das vorhandene Zertifikat unter /etc/letsencrypt/live/<domain>/ eingelesen.
sleep	Wartezeit in Millisekunden nach dem Setzen des TXT Records, bevor certbot mit Enter fortgesetzt wird (DNS Propagation).
middleware	Array der DNS Middleware Module, die beim Setzen/Entfernen des TXT Records ausgeführt werden - siehe Middleware.

Middleware (für die DNS-01 Challenge)

Trägt den TXT Record beim DNS Provider ein, damit Let's Encrypt die Domain bestätigen kann. Gehört zum Input Modul und wird unter input.options.middleware als Array konfiguriert (Input → Options → Middleware), nicht als eigener Top-Level-Schlüssel.

Modul	Beschreibung
powerdns	Trägt den TXT Record direkt in die MySQL Datenbank einer PowerDNS Instanz ein und erhöht den Serial der Zone.
buddyns	Synchronisiert die Zone bei BuddyNS über deren API.

Options powerdns

Parameter	Beschreibung
domain	Die Domain, deren TXT Record gesetzt wird.
domain_id	ID der Zone in der PowerDNS Datenbank.
authentification.host	Host der MySQL Datenbank von PowerDNS.
authentification.user	Benutzername für die MySQL Datenbank.
authentification.password	Passwort für die MySQL Datenbank.
authentification.database	Name der PowerDNS Datenbank.

Options buddyns

Parameter	Beschreibung
domain	Die Domain/Zone, die bei BuddyNS synchronisiert wird.
authentification.username	Benutzername des BuddyNS Accounts.
authentification.password	Passwort des BuddyNS Accounts.

Output

Verteilt das fertige Zertifikat. Liegt als Array unter output - du kannst beliebig viele Output Module hintereinander ausführen lassen.

Modul	Beschreibung
get_cert_from_plain	Liest die Details aus dem erzeugten Zertifikat aus, z.B. zum Loggen/Debuggen.
pfx_creator	Erstellt aus Zertifikat und Key per OpenSSL eine PFX (PKCS#12) Datei.
ssh_scp	Überträgt Zertifikat, Key oder PFX per SCP auf einen oder mehrere Server und führt danach beliebige Shell-Befehle aus, z.B. um einen Dienst neu zu starten.
opnsense	Legt das Zertifikat über die OPNsense API an bzw. aktualisiert es und startet WebGUI/NGINX neu.

Options get_cert_from_plain

Keine - das Modul braucht keine Optionen.

Options pfx_creator

Parameter	Beschreibung
path	Zielpfad, unter dem die erzeugte PFX Datei abgelegt wird.
password	Passwort, mit dem die PFX Datei verschlüsselt wird.

Options ssh_scp

Parameter	Beschreibung
name	Frei wählbarer Name des Ziels, dient nur der Anzeige in den Benachrichtigungen.
server.host	Hostname bzw. IP des Zielservers.
server.username	Benutzername für die SSH Verbindung.
server.port	SSH Port des Zielservers.
server.privateKey	Pfad zur privaten SSH-Key Datei, mit der sich am Server angemeldet wird.
result_target	Array aus { from_path, to_path }. from_path ist ein Punkt-Pfad auf das Ergebnis-Objekt des Input/Output Laufs (z.B. crt.path, key.path oder pfx.path), to_path ist der Zielpfad auf dem Server.
post_command	Array von Shell-Befehlen, die nach der Übertragung nacheinander per SSH auf dem Zielserver ausgeführt werden, z.B. um einen Dienst neu zu starten.

Options opnsense

Parameter	Beschreibung
host	Basis-URL der OPNsense Instanz inkl. Port, z.B. https://opnsense.example.com:10555.
api_key	API Key für die OPNsense REST API.
api_secret	API Secret für die OPNsense REST API.
description	Eindeutige Bezeichnung, über die ein vorhandenes Zertifikat in OPNsense gefunden und aktualisiert wird (sonst wird ein neues angelegt).
verify_ssl	Wenn false, wird das TLS Zertifikat der OPNsense API nicht geprüft.
cert_from_path	Punkt-Pfad auf das Ergebnis-Objekt, aus dem der Zertifikatsinhalt für den Upload gelesen wird, z.B. crt.plain.

Notification

Informiert dich über den Verlauf. Liegt als Array unter notification - du kannst mehrere Kanäle gleichzeitig nutzen.

Modul	Beschreibung
console	Gibt Meldungen in der Konsole aus.
email	Sammelt alle Meldungen und verschickt sie am Ende des Laufs per Mail.

Jedes Modul kennt die Log-Level debug, information, warning und error. Über level in der Konfiguration legst du fest, ab welcher Stufe eine Benachrichtigung etwas anzeigt bzw. verschickt.

Options console

Parameter	Beschreibung
level	Ab welchem Log-Level (debug, information, warning, error) eine Meldung in der Konsole ausgegeben wird.

Options email

Parameter	Beschreibung
host	SMTP Host, über den die Mail verschickt wird.
port	SMTP Port.
secure	Wenn true, wird die Verbindung über TLS aufgebaut.
auth.user	Benutzername für die SMTP Authentifizierung.
auth.pass	Passwort für die SMTP Authentifizierung.
from	Absenderadresse der Mail.
to	Empfängeradresse der Mail.
subject	Betreff der Mail.
level	Ab welchem Log-Level (debug, information, warning, error) eine Meldung in die Mail aufgenommen wird.

Abhängigkeiten 📦

• Node.js
• OpenSSL (wird für das pfx_creator Output Modul benötigt)
• Zugriff auf deinen DNS Provider (z.B. eine PowerDNS Datenbank oder einen BuddyNS Account) für die DNS-01 Challenge

NPM Pakete

• acme-client
• axios
• cron
• moment
• mysql2
• node-cmd
• node-scp
• nodemailer
• ssh2

Konfiguration ⚙️

Die komplette Konfiguration liegt in einer JSON Datei und wird beim Start als Pfad übergeben:

node index.js ./config/config.json

Die Datei ist ein Array aus einzelnen Läufen. Jeder Lauf besteht aus einem trigger, einem input, beliebig vielen output und beliebig vielen notification Modulen:

[
    {
        "trigger": [
            { "module": "now" },
            { "module": "cron", "options": { "execution": "0 5 * * 7" } }
        ],
        "input": {
            "module": "acme_dns",
            "options": {
                "domain": "example.com",
                "wildcard": true,
                "email": "you@example.com",
                "directoryUrl": "https://acme-v02.api.letsencrypt.org/directory",
                "outputDir": "/app/config",
                "renewAfter": 7,
                "middleware": [
                    { "module": "powerdns", "options": { "...": "..." } }
                ]
            }
        },
        "output": [
            { "module": "pfx_creator", "options": { "...": "..." } },
            { "module": "ssh_scp", "options": { "...": "..." } }
        ],
        "notification": [
            { "module": "email", "options": { "level": "information", "...": "..." } },
            { "module": "console", "options": { "level": "debug" } }
        ]
    }
]

Du kannst beliebig viele Läufe im Array hinterlegen und pro Lauf beliebig viele Output- und Notification Module miteinander kombinieren.

Docker 🐳

Das Tool läuft auch als Docker Container:

docker build -t cert_tool .
docker run -v ./config:/app/config cert_tool

Mountpoint	Beschreibung
/app/config	Enthält die Konfigurationsdatei, die SSH Keys sowie die abgelegten Zertifikate.

Tags

• 0.0.1