ACME / Let's Encrypt-Integration

Übersicht

Das ACME-Protokoll (verwendet von Let's Encrypt und anderen Zertifizierungsstellen) unterstützt die DNS-01-Challenge zur Domain-Validierung. DNS-01 ist der einzige Challenge-Typ, der Wildcard-Zertifikate (*.example.com) unterstützt, und er erfordert keinen HTTP-Server auf dem Zielrechner.

NexDNS bietet native Integrationen mit gängigen ACME-Clients sowie einen generischen CLI-Hook für jeden Client, der manuelle DNS-Hooks unterstützt.

Alle ACME-Integrationen erfordern ein API-Token, das ab dem Pro-Tarif verfügbar ist. Jeder Client sucht die Zone, bevor er die Challenge schreibt – das Token benötigt daher zones.read zusätzlich zu records.read und records.write. Erstellen Sie eines unter nexdns.tech/settings/api-keys.

Wie eine Wildcard validiert wird

Die Challenge ist ein TXT-Eintrag unter _acme-challenge beim jeweils validierten Namen. Ein Zertifikat, das sowohl example.com als auch *.example.com abdeckt, erzeugt zwei unterschiedliche Challenge-Werte unter demselben Namen, und beide müssen gleichzeitig vorhanden sein – jede Integration weiter unten berücksichtigt das, weshalb Sie den Eintragssatz zwischen den beiden Validierungen niemals löschen sollten.

Zeit für die Propagierung einplanen

Ein Challenge-Record braucht etwa 30 Sekunden bis zu den Nameservern, deshalb lässt eine Wartezeit von 30 Sekunden keinerlei Reserve - wir haben erlebt, wie eine Prüfung mit NXDOMAIN fehlschlug. Geben Sie der Zertifizierungsstelle mindestens 60 Sekunden: Das certbot-Plugin und lego warten standardmäßig 60, bei acme.sh und dem CLI-Hook bestimmen Sie die Wartezeit selbst.

acme.sh

acme.sh ist ein reiner Shell-ACME-Client. Unser DNS-Hook ist noch in keinem acme.sh-Release enthalten, legen Sie ihn also vor dem ersten Lauf in ~/.acme.sh/dnsapi/ ab: curl -fsSL https://get.nexdns.tech/acme/dns_nexdns.sh -o ~/.acme.sh/dnsapi/dns_nexdns.sh. Dieselbe Datei liegt in dem CLI-Repository, falls Sie sie lieber vorher lesen möchten.

Zertifikat ausstellen

export NEXDNS_Token="nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
acme.sh --issue --server letsencrypt --dns dns_nexdns \
    --dnssleep 60 \
    -d example.com -d '*.example.com'

Das Token wird nach dem ersten Durchlauf in ~/.acme.sh/account.conf gespeichert, sodass Sie es für Verlängerungen nicht erneut exportieren müssen.

Verlängern

Verlängerungen erfolgen automatisch über Cron. Um eine manuelle Verlängerung zu erzwingen:

acme.sh --renew -d example.com

lego für Traefik

lego ist ein Go-basierter ACME-Client, der auch die automatische Zertifikatsverwaltung von Traefik antreibt. Der Provider ist ab lego v5.4.0 enthalten.

Standalone-Nutzung

NEXDNS_API_TOKEN=nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
NEXDNS_PROPAGATION_TIMEOUT=300 \
lego --dns nexdns \
    --domains example.com \
    --domains '*.example.com' \
    --email admin@example.com \
    --accept-tos \
    run

lego liest seine Timeouts als reine Sekundenzahl: NEXDNS_PROPAGATION_TIMEOUT=300 funktioniert, 300s lässt sich nicht parsen und wird stillschweigend durch den Standardwert von 60 Sekunden ersetzt.

Traefik-Konfiguration

Traefik bindet die Provider-Tabelle von lego beim Build ein und verwendet noch eine ältere Version, daher wird hier ein Traefik-Build mit lego v5.4.0 benötigt. Fügen Sie den NexDNS-DNS-Challenge-Resolver zu Ihrer Traefik-Konfiguration hinzu - das folgende docker-compose.yml zeigt einen typischen Aufbau:

services:
  traefik:
    image: traefik:v3  # lego >= v5.4.0
    command:
      - "--certificatesresolvers.nexdns.acme.dnschallenge=true"
      - "--certificatesresolvers.nexdns.acme.dnschallenge.provider=nexdns"
      - "--certificatesresolvers.nexdns.acme.email=admin@example.com"
      - "--certificatesresolvers.nexdns.acme.storage=/letsencrypt/acme.json"
    environment:
      NEXDNS_API_TOKEN: "nxd_xxxxxxxxxxxxxxxxxxxx"
    volumes:
      - letsencrypt:/letsencrypt
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "443:443"

volumes:
  letsencrypt:

Verwenden Sie dann den Resolver in Ihren Service-Labels:

labels:
  - "traefik.http.routers.myapp.tls.certresolver=nexdns"
  - "traefik.http.routers.myapp.tls.domains[0].main=example.com"
  - "traefik.http.routers.myapp.tls.domains[0].sans=*.example.com"

Certbot-Client

certbot ist der offizielle Let's Encrypt-Client. Verwenden Sie das NexDNS DNS-Authenticator-Plugin für die automatisierte DNS-01-Validierung.

Plugin installieren

Installieren Sie das Plugin von PyPI oder nutzen Sie das Docker-Image unten, das es bereits enthält.

pip install certbot-dns-nexdns

Anmeldedatendatei erstellen

Erstellen Sie ~/.nexdns/certbot-credentials.ini mit Ihrem API-Token:

dns_nexdns_token = nxd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Dateiberechtigungen einschränken:

chmod 600 ~/.nexdns/certbot-credentials.ini

Zertifikat ausstellen

certbot certonly \
    --authenticator dns-nexdns \
    --dns-nexdns-credentials ~/.nexdns/certbot-credentials.ini \
    -d example.com \
    -d '*.example.com'

Docker-Nutzung

docker run --rm \
    -v /etc/letsencrypt:/etc/letsencrypt \
    -v ~/.nexdns/certbot-credentials.ini:/credentials.ini:ro \
    nexdns/certbot certonly \
        --non-interactive --agree-tos --email admin@example.com \
        --authenticator dns-nexdns \
        --dns-nexdns-credentials /credentials.ini \
        -d example.com \
        -d '*.example.com'

CLI-Hook

Wenn Ihr ACME-Client manuelle DNS-Hooks unterstützt, können Sie das NexDNS CLI als Hook-Skript verwenden. Dies funktioniert mit jedem Client, der die Optionen --manual-auth-hook und --manual-cleanup-hook bereitstellt (z. B. certbot im manuellen Modus).

certbot mit CLI-Hook

certbot certonly --manual --preferred-challenges dns \
    --manual-auth-hook "nexdns acme hook --action create && sleep 60" \
    --manual-cleanup-hook "nexdns acme hook --action delete" \
    -d example.com \
    -d '*.example.com'

Der Hook liest die von certbot gesetzten Umgebungsvariablen CERTBOT_DOMAIN und CERTBOT_VALIDATION und erstellt oder entfernt den _acme-challenge TXT-Eintrag automatisch.

Das CLI muss vor der Verwendung von Hooks authentifiziert sein. Führen Sie nexdns auth token nxd_xxx aus oder setzen Sie die Umgebungsvariable NEXDNS_TOKEN.