So installieren Sie ein ACME SSL-Zertifikat auf TrueNAS

Diese Anleitung zeigt Ihnen, wie Sie ein ACME SSL-Zertifikat auf TrueNAS unter Verwendung eines externen Hosts und EAB (External Account Binding) installieren. Sie ist sowohl mit TrueNAS CORE als auch mit TrueNAS SCALE kompatibel.

TrueNAS bietet native ACME-Unterstützung, allerdings nur für Let’s Encrypt über die integrierte DNS-01-Integration. Wenn Sie einen kommerziellen ACME-Anbieter (Sectigo, DigiCert usw.) mit ACME + EAB verwenden möchten, müssen Sie Ihr Zertifikat extern mit einem ACME-Client wie acme.sh generieren und erneuern und es dann in TrueNAS einsetzen.

---

Bevor Sie beginnen

Das brauchen Sie dazu:

• Ein Domainname, der auf Ihre öffentliche TrueNAS-IP verweist (z.B. nas.example.com)
• TrueNAS CORE 13.x oder TrueNAS SCALE 23.x+
• Ein externer Linux/BSD-Rechner, VPS oder Heimserver (zur Ausführung von acme.sh)
• ACME Directory URL, EAB Key ID und EAB HMAC von Ihrer kommerziellen CA
• SSH-Zugang zu TrueNAS, wenn Sie die Synchronisierung automatisieren möchten

Notiz: TrueNAS unterstützt NICHT beliebige ACME-Anbieter in seiner Benutzeroberfläche. Die gesamte kommerzielle ACME-Automatisierung muss außerhalb von TrueNAS erfolgen.

---

Schritt 1: Installieren Sie acme.sh auf Ihrem externen Host

Dieses Gerät ist für die Registrierung, Ausstellung und Erneuerung von ACME-Konten zuständig.

Laufen:

curl https://get.acme.sh | sh
source ~/.bashrc
acme.sh --version

Wenn die Version korrekt gedruckt wird, ist alles in Ordnung.

---

Schritt 2: Registrieren Sie Ihr ACME-Konto bei Ihrer kommerziellen CA (ACME + EAB)

Ihr CA-Dashboard wird Ihnen dies anzeigen:

• EAB Schlüssel-ID
• EAB HMAC-Schlüssel
• ACME Verzeichnis URL

Registrieren Sie Ihr ACME-Konto:

acme.sh --register-account \
  --server https://acme.yourca.com/v2/acme \
  --eab-kid YOUR_EAB_KID \
  --eab-hmac-key YOUR_EAB_HMAC_KEY \
  --accountemail [email protected]

Ersetzen Sie die Werte durch Ihre eigenen. Sie führen dies nur einmal aus.

---

Schritt 3: Ausstellen des Zertifikats (DNS-01 Validierung erforderlich)

TrueNAS befindet sich fast immer hinter NAT, so dass die DNS-Validierung am sichersten ist.

Hier ist ein Beispiel für eine manaul DNS:

acme.sh --issue \
  -d nas.example.com \
  --dns dns_manual \
  --server https://acme.yourca.com/v2/acme

acme.sh wird Sie auffordern, einen TXT-Eintrag zu erstellen:

_acme-challenge.nas.example.com   TXT   <token>

Erstellen Sie den TXT-Eintrag in Ihrem DNS-Manager und warten Sie auf die Weiterleitung.

Prüfen Sie die Ausbreitung:

dig TXT _acme-challenge.nas.example.com +short

Sobald das Token erscheint, führen Sie denselben Befehl erneut aus und acme.sh wird die Ausstellung des Zertifikats beenden. Ihre Dateien werden unter ~/.acme.sh/nas.example.com/ gespeichert.

Im Inneren finden Sie:

• fullchain.cer: Server-Zertifikat + Zwischenzertifikat
• nas.example.com.key: privater Schlüssel
• ca.cer: CA-Kette (falls separat bereitgestellt)

---

Schritt 4: Importieren Sie das Zertifikat in TrueNAS

1. Gehen Sie zu: TrueNAS UI > System > Zertifikate
2. Klicken Sie auf Hinzufügen und wählen Sie Zertifikat importieren
3. Laden Sie Ihre Zertifikatsdateien hoch und klicken Sie auf Speichern

Weisen Sie das Zertifikat Ihren Diensten zu:

• Web UI
• SMB / NFS-Dienste (falls zutreffend)
• Middleware-APIs
• Umgekehrte Proxies oder Anwendungen mit HTTPS (TrueNAS SCALE)

---

Schritt 5: Erneuerung und Bereitstellung automatisieren

TrueNAS zieht die Zertifikate nicht automatisch. Sie müssen erneuerte Zertifikate in TrueNAS übertragen.

1. Erstellen Sie ein Bereitstellungsskript

Erstellen Sie auf Ihrem externen ACME-Host /usr/local/bin/truenas-deploy.sh:

Hinweis: Dieses Skript funktioniert nur, wenn TrueNAS den SSH-Zugang mit einem Benutzer erlaubt, der midclt ausführen darf. Es lädt den neuen Schlüssel + Zertifikat auf /tmp/ hoch und ersetzt das aktive Zertifikat über die TrueNAS-API. Stellen Sie sicher, dass Ihre Pfade und Ihre Domäne mit Ihrer acme.sh-Einrichtung übereinstimmen.

#!/bin/bash

DOMAIN="nas.example.com"
NAS_USER="root"
NAS_HOST="truenas.local"

CERT_PATH="$HOME/.acme.sh/$DOMAIN"
KEY="$CERT_PATH/$DOMAIN.key"
CERT="$CERT_PATH/fullchain.cer"

scp "$KEY" "$NAS_USER@$NAS_HOST:/tmp/key.key"
scp "$CERT" "$NAS_USER@$NAS_HOST:/tmp/cert.cer"

ssh "$NAS_USER@$NAS_HOST" <<EOF
midclt call certificate.update '{"certificate": "custom", "csr": null, "privatekey": "$(cat /tmp/key.key)", "certificate": "$(cat /tmp/cert.cer)"}'
EOF

Machen Sie es ausführbar:

chmod +x /usr/local/bin/truenas-deploy.sh

2. Einen Verlängerungshaken hinzufügen

Fügen Sie einen Deploy-Hook in acme.sh hinzu:

acme.sh --deploy-hook truenas-deploy \
  -d nas.example.com

Oder fügen Sie dies in ~/.acme.sh/deploy/truenas-deploy.sh ein.

3. Lassen Sie acme.sh alles erledigen

Hier sehen Sie, was acme.sh automatisch tut:

• Prüft täglich auf Verlängerungen
• Erneuert das Zertifikat
• Löst Ihr Deployment-Skript aus
• Pusht aktualisierte Zertifikate in TrueNAS
• Übernimmt Änderungen stillschweigend

Einmal konfiguriert, müssen Sie TrueNAS für Zertifikatserneuerungen nicht mehr anfassen.

---

Allgemeine Fragen

Wenn Sie die ACME-Automatisierung auf TrueNAS zum ersten Mal einrichten, decken diese Kurzantworten die Probleme ab, auf die Benutzer am häufigsten stoßen.

Kann ich ein Zertifikat sowohl für die TrueNAS GUI als auch für andere Dienste (SMB, NFS, iSCSI-Portale) verwenden?

Ja. Sobald Sie das Zertifikat in System > Zertifikate importiert haben, können Sie dasselbe Zertifikat für die Web-Benutzeroberfläche und für jeden Dienst auswählen, der HTTPS verwendet (Web-Benutzeroberfläche, API, eventuell Reverse Proxy/HAProxy, wenn Sie diese verwenden). Sie benötigen keine separaten Zertifikate für jeden Dienst, es sei denn, Sie möchten unterschiedliche Hostnamen verwenden.

Mein NAS befindet sich hinter CGNAT oder doppeltem NAT. Kann ich trotzdem ACME verwenden?

Ja, aber Sie müssen die DNS-01-Validierung verwenden. HTTP-01 wird nicht funktionieren, da der ACME-Server Ihr NAS nicht über Port 80 erreichen kann. Mit DNS-01 prüft die Zertifizierungsstelle nur Ihren TXT-Eintrag unter _acme-challenge.yourdomain.com, so dass es ihr egal ist, wo sich der NAS tatsächlich befindet.

Was passiert, wenn acme.sh das Zertifikat erneuert, ich aber vergesse, es wieder in TrueNAS zu importieren?

TrueNAS verwendet einfach weiterhin das alte Zertifikat, das Sie beim letzten Mal importiert haben. Die erneuerten Dateien befinden sich auf Ihrem externen Host, bis Sie sie erneut hochladen (oder Ihr Skript/API dies übernimmt).

Ihre Website wird weiterhin funktionieren, aber irgendwann werden die Browser eine Warnung über ein abgelaufenes Zertifikat ausgeben. Deshalb lohnt es sich, entweder ein Skript für den Re-Import zu erstellen oder eine Erinnerung kurz vor dem Ablaufdatum einzurichten.

Kann ich ein Wildcard-Zertifikat (wie *.example.com) mit TrueNAS verwenden?

Ja. Solange der private Schlüssel und das Zertifikat übereinstimmen, ist es TrueNAS egal, ob es sich um eine Wildcard oder ein Single-Host-Zertifikat handelt. Sie müssen den Platzhalter trotzdem über DNS-01 in acme.sh ausstellen und dann fullchain.cer + *.example.com.key in TrueNAS importieren. Seien Sie nur vorsichtig, wo Sie diesen Schlüssel wiederverwenden. Ein Wildcard-Zertifikat gibt Ihnen die volle Kontrolle über alle von ihm abgedeckten Subdomänen.

---

Letzte Worte

Dieser Arbeitsablauf bietet Ihnen eine stabile, zuverlässige Möglichkeit, ein ACME-Zertifikat auf TrueNAS zu installieren, ohne das System zu bekämpfen. Ihr externer Host kümmert sich um die Ausstellung, Erneuerung und Verwaltung des Zertifikats, während TrueNAS einfach saubere Importe erhält, wenn die Dateien aktualisiert werden.

Sobald der Prozess eingerichtet ist, läuft alles leise im Hintergrund, und Sie müssen nur eingreifen, wenn Sie Skripte anpassen oder Anmeldedaten ändern möchten.