Caddy DNS Challenge Provider

Mit dem Caddy-DNS-Plugin für Servercow kann Caddy DNS-Einträge über die Servercow DNS API verwalten. Das ist besonders dann nützlich, wenn du TLS-Zertifikate per ACME DNS-01 Challenge ausstellen möchtest, zum Beispiel für Wildcard-Zertifikate wie *.example.com.

Voraussetzungen¶

Bevor du das Plugin nutzen kannst, brauchst du:

eine Domain, die in Servercow DNS verwaltet wird
einen DNS API Zugang (siehe diese Anleitung)
einen Caddy-Server, auf dem du Plugins einbinden oder eine eigene Caddy-Binary bauen kannst

Achtung

Caddy wird, wenn per Repository installiert immer ohne jegliche Plugins ausgeliefert. Das bedeutet, dass du entweder eine eigene Caddy-Binary mit dem Servercow-Plugin bauen oder eine Custom Build Binary von der Caddy-Webseite herunterladen musst, um das Plugin nutzen zu können (siehe unten).

Modulname¶

Das Caddy-Plugin registriert sich unter folgendem Modulnamen:

dns.providers.servercow

Caddy mit dem Plugin bereitstellen¶

Es gibt zwei gängige Wege, um Caddy mit dem Servercow-DNS-Plugin zu nutzen.

Variante 1: Eigene Caddy-Binary mit xcaddy bauen¶

Für Techies und Entwickler empfohlen

Diese Variante erfordert eine lokale Go-Toolchain und ist eher für fortgeschrittene Nutzer geeignet, die bereits Erfahrung mit dem Bauen von Caddy-Binaries haben. Eine genaue Erklärung wie xcaddy funktioniert findest du in der offiziellen Caddy-Dokumentation.

Das Plugin wird über xcaddy in eine eigene Caddy-Binary eingebaut.

xcaddy build --with github.com/caddy-dns/servercow

Wenn du bereits eine bestehende Build-Pipeline für Caddy nutzt, kannst du das Plugin dort analog ergänzen.

Variante 2: Custom Build direkt über die Caddy-Webseite herunterladen¶

Von uns empfohlen

Diese Variante ist besonders einfach und erfordert keine lokale Go-Installation. Du kannst direkt eine fertige Caddy-Binary mit eingebautem Servercow-Plugin herunterladen.

Wenn du kein xcaddy auf dem Server verwenden möchtest, kannst du dir auch direkt über die offizielle Caddy-Webseite eine Custom Build-Binary mit eingebundenen Modulen erstellen und herunterladen.

Dafür wählst du auf der Download-Seite von Caddy einen Custom Build aus und fügst das Modul hinzu:

github.com/caddy-dns/servercow

Anschließend kannst du die fertig gebaute Binary für dein Betriebssystem herunterladen und wie eine normale Caddy-Version installieren.

Konfiguration mit Caddyfile¶

Globale ACME-DNS-Konfiguration¶

Wenn du die DNS Challenge global für Caddy setzen möchtest, kannst du das so konfigurieren:

{
    acme_dns servercow <username> <password>
}

TLS-Konfiguration pro Host¶

Alternativ kannst du die DNS-Challenge direkt pro Site definieren:

tls {
    dns servercow <username> <password>
}

Empfohlene Variante mit Umgebungsvariablen¶

Damit Zugangsdaten nicht direkt im Caddyfile stehen, solltest du Umgebungsvariablen verwenden:

tls {
    dns servercow {
        username {env.SERVERCOW_USERNAME}
        password {env.SERVERCOW_PASSWORD}
    }
}

Beispiel für eine komplette Site¶

example.com, *.example.com {
    tls {
        dns servercow {
            username {env.SERVERCOW_USERNAME}
            password {env.SERVERCOW_PASSWORD}
        }
    }

    respond "Hello from Caddy with Servercow DNS"
}

Dieses Setup ist besonders hilfreich, wenn du ein Wildcard-Zertifikat für deine Domain brauchst.

JSON-Konfiguration¶

Falls du Caddy per JSON konfigurierst, kann der ACME-Issuer so aussehen:

{
  "module": "acme",
  "challenges": {
    "dns": {
      "provider": {
        "name": "servercow",
        "username": "YOUR_SERVERCOW_USERNAME",
        "password": "YOUR_SERVERCOW_PASSWORD"
      }
    }
  }
}

Sicherheitshinweise¶

Wir empfehlen dir, die API-Zugangsdaten nicht direkt im Caddyfile zu hinterlegen, sondern ausschließlich über Umgebungsvariablen bereitzustellen.

Beispiel:

export SERVERCOW_USERNAME="dein-benutzername"
export SERVERCOW_PASSWORD="dein-passwort"

Anschließend kann Caddy die Werte über {env.SERVERCOW_USERNAME} und {env.SERVERCOW_PASSWORD} verwenden.

Typische Einsatzszenarien¶

Das Plugin eignet sich unter anderem für:

automatische Zertifikatsausstellung mit Let's Encrypt
Wildcard-Zertifikate für Subdomains
Setups ohne offene Port-80-Validierung
interne oder segmentierte Infrastrukturen, in denen DNS-Validation bevorzugt wird

Troubleshooting¶

Wenn die Zertifikatsanforderung fehlschlägt, prüfe bitte:

Sind die Zugangsdaten zur Servercow DNS API korrekt?
Wird die Domain wirklich über Servercow DNS verwaltet?
Wurde Caddy mit dem Plugin github.com/caddy-dns/servercow gebaut oder als Custom Build mit diesem Modul heruntergeladen?
Sind die Umgebungsvariablen auf dem System korrekt gesetzt?
Kann Caddy ausgehend die API erreichen?