Wer Netcup-Infrastruktur automatisiert, stolpert in älteren Forenbeiträgen häufig über abgeschaltete SOAP-URLs oder verwechselt die Zugangsdaten der getrennten Verwaltungsportale. In der aktuellen Architektur gilt diese klare Aufgabenteilung:
| Portal & Ebene | Offizieller API-Endpunkt | Authentifizierung | Automatisierbare Funktionen |
|---|---|---|---|
| SCP (Server Control Panel) | https://www.servercontrolpanel.de/scp-core/api/v1 | Keycloak OAuth2 (client_id=scp, offline_access → Bearer-JWT + IP/CIDR-Allowlist) | KVM-Status, 0-€-Snapshots (Online-CoW auf BIOS-x86; Offline auf ARM64/UEFI), SCP-Firewall, IPv4/IPv6-rDNS (PTR), Rescue & ISO |
CCP – Neue netcup API (OAS 3.1) | https://api.netcup.com | API-Key (Bearer-Auth, unter CCP → Stammdaten → API) | Moderne OpenAPI-3.1-REST-Steuerung für CloudDNS & Domain-Verwaltung |
CCP – Legacy API | https://ccp.netcup.net/run/webservice/servers/endpoint.php?JSON | JSON/SOAP-Session (customernumber + Legacy-apikey + Legacy-apipassword) | Klassische CCP-DNS-Zonen (A, AAAA, TXT, CAA) & ACME DNS-01 (acme.sh dns_netcup, Traefik, Lego) |
1. SCP REST-API v1: Headless-Login per OAuth2 Device-Flow
Da moderne SCP-Konten mit 2FA/TOTP geschützt sind, werden keine Klartext-Passwörter im Skript gespeichert. Stattdessen erzeugen Sie einmalig über den Keycloak Device-Authorization-Flow ein langlebiges offline_access-Token:
# Schritt 1: Device-Code mit 'offline_access' anfordern (wichtig für unbeaufsichtigte Cronjobs!)
DEVICE_RESP=$(curl -sS -X POST \
"https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/auth/device" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "client_id=scp" \
-d "scope=openid offline_access")
echo "$DEVICE_RESP" | jq -r '"Im Browser öffnen: \(.verification_uri_complete)\nCode: \(.user_code)"'
DEVICE_CODE=$(echo "$DEVICE_RESP" | jq -r '.device_code')
# Schritt 2: Nach Browser-Freigabe das dauerhafte refresh_token abrufen und geschützt ablegen
TOKEN_RESP=$(curl -sS -X POST \
"https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
-d "client_id=scp" \
-d "device_code=${DEVICE_CODE}")
REFRESH_TOKEN=$(echo "$TOKEN_RESP" | jq -r '.refresh_token')
sudo install -m 600 /dev/null /etc/netcup-scp.env
echo "SCP_REFRESH_TOKEN=${REFRESH_TOKEN}" | sudo tee /etc/netcup-scp.env >/dev/null
OpenAPI-3.1- & MCP-Referenz: Die SCP REST-API folgt dem OpenAPI-3.1-Standard (dokumentiert unter
https://www.servercontrolpanel.de/scp-core/api/v1/openapisowie als MCP-Schema unterhttps://www.servercontrolpanel.de/scp-core/api/v1/openapi/mcp). Alle URL-Pfade sind strikt kleingeschrieben (case-sensitive lowercase), und in den SCP-Benutzereinstellungen (Account → API) lässt sich eine IP-/CIDR-Allowlist pflegen – prüfen Sie diese Freigabeliste zuerst, falls Requests von einem neuen Runner abgewiesen werden.
2. Automatische CoW-Snapshots vor Kernel- & Docker-Updates
G12.5 x86-Root-Server und x86-VPS im BIOS-Bootmodus unterstützen im SCP kostenlose lokale Online-Copy-on-Write-Snapshots (0,00 €) im laufenden Betrieb, solange freier Plattenplatz im Volume vorhanden ist. Wichtige Ausnahme: Alle ARM64-VPS G12.5 (sowie UEFI-gebootete VMs) erlauben technisch ausschließlich Offline-Snapshots – die VM muss vor dem Snapshot heruntergefahren werden ("onlineSnapshot": false samt "diskName"). Das folgende Bash-Skript holt ein kurzlebiges Bearer-Token und legt auf einem BIOS-x86-Server vor nächtlichen Wartungsarbeiten automatisch einen Online-Sicherungspunkt an:
#!/usr/bin/env bash
set -euo pipefail
source /etc/netcup-scp.env
API_BASE="https://www.servercontrolpanel.de/scp-core/api/v1"
TOKEN_URL="https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect/token"
# 1. Kurzlebiges Access-Token per Refresh-Token abrufen
ACCESS_TOKEN=$(curl -fsS -X POST "$TOKEN_URL" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=scp" \
-d "refresh_token=${SCP_REFRESH_TOKEN}" | jq -r '.access_token')
# 2. Eigene Server-ID ermitteln
SERVER_ID=$(curl -fsS -H "Authorization: Bearer ${ACCESS_TOKEN}" \
"${API_BASE}/servers" | jq -r '.[0].id')
SNAP_NAME="auto-$(date -u +%Y%m%d-%H%M)"
# 3. Online-CoW-Snapshot im laufenden Betrieb erstellen (BIOS-x86; für ARM64/UEFI VM vorher stoppen & onlineSnapshot:false + diskName nutzen)
curl -fsS -X POST "${API_BASE}/servers/${SERVER_ID}/snapshots" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d "{\"name\":\"${SNAP_NAME}\",\"description\":\"Automatischer Pre-Update CoW-Snapshot\",\"onlineSnapshot\":true}"
echo "SCP-Snapshot ${SNAP_NAME} für Server ${SERVER_ID} angelegt."
Ebenso lassen sich IPv4- und /64-IPv6-PTR-Einträge (rDNS) für eigene Mailserver (siehe Port-25- & Mailcow-Guide) automatisiert über ${API_BASE}/rdns/ipv4 und ${API_BASE}/rdns/ipv6 setzen.
3. Wildcard-SSL per CCP DNS-01 (acme.sh & Traefik v3)
Nutzen Ihre Domains (z. B. inklusive der Gratis-.de-Domains in NUE bzw. internationalen Inklusivdomains beim Netcup Webhosting) die kostenlosen Netcup-Nameserver, finden Sie im CCP (customercontrolpanel.de) → Stammdaten → API zwei getrennte API-Optionen: Für CloudDNS und moderne REST-Integrationen steht die neue OpenAPI-3.1-basierte netcup API (https://api.netcup.com) per Bearer-API-Key bereit; für klassische CCP-DNS-Zonen in bestehenden Clients wie acme.sh (dns_netcup), Traefik und Lego erzeugen Sie dort einen Legacy-API-Key samt Legacy-API-Passwort für https://ccp.netcup.net/run/webservice/servers/endpoint.php.
Variante A: acme.sh mit --dnssleep 600 (ohne Timeout-Fehler)
Da Netcup-Nameserver geänderte Zonendateien gebündelt alle ca. 5 bis 10 Minuten ausrollen, führt eine sofortige Let’s-Encrypt-Abfrage zu NXDOMAIN. Mit 600 Sekunden Wartezeit läuft jede Verlängerung stabil durch:
export NC_Apikey="IHR_CCP_API_KEY"
export NC_Apipw="IHR_CCP_API_PASSWORT"
export NC_CID="IHRE_KUNDENNUMMER"
acme.sh --issue --dns dns_netcup \
--dnssleep 600 \
-d example.de -d '*.example.de' \
--keylength ec-256
Variante B: Traefik v3 / Coolify Reverse-Proxy (Auch für interne VPN-Hosts)
Für Coolify- oder Dokploy-Setups hinter WireGuard stellt Traefik per DNS-01 gültige Zertifikate aus, ohne Port 80 öffentlich öffnen zu müssen:
services:
traefik:
image: traefik:v3.2
command:
- "--certificatesresolvers.le-netcup.acme.dnschallenge=true"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.provider=netcup"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.delaybeforecheck=600"
- "--certificatesresolvers.le-netcup.acme.dnschallenge.resolvers=46.38.225.230:53,1.1.1.1:53"
- "--certificatesresolvers.le-netcup.acme.email=admin@example.de"
- "--certificatesresolvers.le-netcup.acme.storage=/letsencrypt/acme.json"
environment:
NETCUP_CUSTOMER_NUMBER: "${NC_CID}"
NETCUP_API_KEY: "${NC_Apikey}"
NETCUP_API_PASSWORD: "${NC_Apipw}"
NETCUP_PROPAGATION_TIMEOUT: "900"
NETCUP_POLLING_INTERVAL: "30"
4. Einordnung für Terraform & OpenTofu
- DNS-Zonen (
CCP): Über den Terraform-Providernetcup-dnsverwalten SieA-,AAAA-,MX-,SPF- undDKIM-Einträge deklarativ per GitOps. - Server-Betrieb vs. Neubestellung: Während Hetzner Cloud Instanzen per Public-Cloud-API neu erzeugt und löscht, werden Netcup-Verträge im Warenkorb gebucht (1 Monat Frist zum Monatsende im Kündigungsfrist-Rechner prüfen) und anschließend im laufenden Betrieb vollständig über die SCP REST-API v1 und Ansible gesteuert.
RS 1000 G12.5
2 Monate gratis · Auch für Bestandskunden (12 Mon. Laufzeit)