Netcup DNS API & Let's Encrypt Wildcard-Zertifikate automatisiert einrichten: acme.sh & Certbot Praxishandbuch

Während einfache Hostnamen bequem per HTTP-01 Challenge validiert werden können, erfordern Wildcard-Zertifikate (*.example.de) zwingend die DNS-01 Challenge.

Über die offizielle Netcup DNS API lässt sich das Setzen und Löschen der temporären _acme-challenge TXT-Einträge vollständig automatisieren.

Hier zeigen wir die Einrichtung mit den beiden verbreitetsten Tools: dem leichtgewichtigen Shell-Client acme.sh und dem etablierten Certbot inklusive automatischer Nginx- und Docker-Neuladung.

1. API-Schlüssel im Netcup CCP generieren

Bevor du auf deinem Server Befehle ausführst, benötigst du deine individuellen API-Zugangsdaten:

1. Logge dich im Customer Control Panel (CCP) ein.
2. Navigiere in der linken Menüleiste auf Stammdaten ➔ API.
3. Klicke auf die Schaltfläche Neuen API-Schlüssel generieren.
4. Notiere dir die folgenden drei Werte sicher in deinem Passwort-Manager:
   • Kundennummer (NC_CID): Deine 5- bis 6-stellige Netcup-Kundennummer.
   • API-Key (NC_Apikey): Ein 32-stelliger alphanumerischer Schlüssel.
   • API-Passwort (NC_ApiPw): Das generierte geheime Passwort für API-Sessions.
5. Stelle sicher, dass der API-Status auf Aktiv steht.

2. Methode A: Einrichtung mit acme.sh (Empfohlen)

acme.sh ist ein extrem ressourcenschonender, reiner POSIX-Shell-Script-Client ohne schwere Python-Abhängigkeiten und bringt native Netcup-Unterstützung mit.

Schritt 1: acme.sh auf dem Server installieren

Führe auf deinem Netcup Root Server oder VPS folgenden Befehl aus:

# acme.sh mit deiner E-Mail-Adresse für Let's Encrypt Benachrichtigungen installieren
curl https://get.acme.sh | sh -s email=admin@example.de

# Shell-Umgebung neu laden
source ~/.bashrc

Schritt 2: API-Zugangsdaten hinterlegen

Hinterlege deine Netcup-Credentials in den Umgebungsvariablen. acme.sh speichert diese nach dem ersten erfolgreichen Durchlauf verschlüsselt in ~/.acme.sh/account.conf ab:

export NC_CID="123456"                          # Deine Netcup Kundennummer
export NC_Apikey="dein_32stelliger_api_key"     # Dein API Key
export NC_ApiPw="dein_geheimes_api_passwort"    # Dein API Passwort

Schritt 3: Wildcard-Zertifikat mit DNS-Sleep beantragen

[!IMPORTANT] Da die Netcup Nameserver einige Zeit zur weltweiten DNS-Zonensynchronisation benötigen, solltest du zwingend den Parameter --dnssleep 180 setzen, um Validierungsfehler durch zu frühes Abfragen zu verhindern.

~/.acme.sh/acme.sh --issue \
  --dns dns_netcup \
  -d example.de \
  -d '*.example.de' \
  --dnssleep 180

Schritt 4: Zertifikate in Nginx einbinden & automatischer Reload Hook

Verwende niemals die Rohdateien im .acme.sh-Verzeichnis direkt in deiner Webserver-Konfiguration. Installiere sie stattdessen mit dem install-cert-Befehl an ihren finalen Ort:

# Zielverzeichnis anlegen
sudo mkdir -p /etc/nginx/ssl/example.de

# Zertifikate installieren und Nginx Reload Hook aktivieren
~/.acme.sh/acme.sh --install-cert -d example.de \
  --key-file       /etc/nginx/ssl/example.de/privkey.pem \
  --fullchain-file /etc/nginx/ssl/example.de/fullchain.pem \
  --reloadcmd     "sudo systemctl reload nginx"

Sobald acme.sh das Zertifikat alle 60 Tage per automatischem Cronjob erneuert, führt es selbstständig den reloadcmd aus – 100% wartungsfrei.

3. Methode B: Einrichtung mit Certbot & certbot-dns-netcup

Falls du in deinem Unternehmen standardmäßig auf Certbot (EFF) setzt, kannst du das offizielle Community-Plugin nutzen.

Schritt 1: Certbot und Netcup DNS Plugin installieren (Debian / Ubuntu)

sudo apt update
sudo apt install -y certbot python3-certbot python3-pip

# Plugin installieren
sudo pip3 install certbot-dns-netcup --break-system-packages

Schritt 2: Konfigurationsdatei mit Zugriffsrechten erstellen

Erstelle eine geschützte Konfigurationsdatei unter /etc/letsencrypt/netcup.ini:

# /etc/letsencrypt/netcup.ini
dns_netcup_customer_id = 123456
dns_netcup_api_key = dein_32stelliger_api_key
dns_netcup_api_password = dein_geheimes_api_passwort

Setze zwingend restriktive Dateirechte, damit unberechtigte Systembenutzer die Passwörter nicht auslesen können:

sudo chmod 600 /etc/letsencrypt/netcup.ini

Schritt 3: Wildcard-Zertifikat ausstellen

sudo certbot certonly \
  --authenticator dns-netcup \
  --dns-netcup-credentials /etc/letsencrypt/netcup.ini \
  --dns-netcup-propagation-seconds 180 \
  -d example.de \
  -d '*.example.de' \
  --post-hook "systemctl reload nginx"

Certbot richtet automatisch einen systemd-Timer (certbot.timer) ein, der zweimal täglich auf anstehende Zertifikatserneuerungen prüft.

4. Häufige Fehler & Netcup API Troubleshooting

1. Fehler: Status: 4013 (Invalid session ID)

• Ursache: Das API-Passwort oder der Key wurde fehlerhaft kopiert (z. B. unsichtbares Leerzeichen am Zeilenende) oder die IP-Adresse des Servers hat gewechselt.
• Lösung: Generiere im CCP unter Stammdaten -> API ein frisches Schlüsselpaar und aktualisiere deine Umgebungsvariablen.

2. Fehler: DNS challenge failed: NXDOMAIN looking up TXT for _acme-challenge

• Ursache: Let’s Encrypt hat die Nameserver befragt, bevor der neue TXT-Eintrag auf allen Netcup-Anycast-Instanzen repliziert war.
• Lösung: Erhöhe den Parameter --dnssleep bei acme.sh von 120 auf 180 oder 240 Sekunden.

3. Rate Limits der Netcup API

• Netcup limitiert API-Aufrufe zum Schutz der Infrastruktur auf vertretbare Grenzwerte (ca. 20–30 Requests pro Minute pro Account).
• Vermeide es, in kurzen Test-Schleifen Dutzende Domains parallel anzufragen. Teste neue Setups immer mit dem Let’s Encrypt Staging-Server (--staging), um nicht in das wöchentliche Let’s Encrypt Zertifikatslimit zu laufen.