DynDNS mit einer netcup-Domain: Heim-IP per ddns-updater aktuell halten

Wer zu Hause einen Dienst unter einem eigenen Namen erreichbar machen will, braucht einen DNS-Eintrag, der immer auf die aktuelle Adresse des Anschlusses zeigt. Liegt die Domain bei netcup, können Sie dafür auf einen fremden DynDNS-Dienst verzichten: Ein kleines Programm im Heimnetz prüft regelmäßig die eigene öffentliche Adresse und schreibt sie bei einer Änderung über die DNS-API von netcup in Ihre Zone. Diese Anleitung zeigt das mit dem Docker-Container ddns-updater für IPv4 und IPv6 und misst, wie lange netcup braucht, bis eine neue Adresse draußen ankommt.

Dies ist Teil 13 der Reihe „netcup Spezial“.

Testaufbau

Getestet haben wir am 04.11.2026 auf einem netcup VPS 500 G12.5 mit Ubuntu 24.04.5 und Docker 29.9.2. Die Domain sedv-lab.de liegt im klassischen netcup-DNS mit den Nameservern root-dns, second-dns und third-dns.netcup.net, die Zone hat eine TTL von 300 Sekunden. Gepflegt wurde der Name home.sedv-lab.de mit A- und AAAA-Eintrag.

Komponente	Version	Ergebnis
ddns-updater	v2.10.0	A und AAAA angelegt, absichtlich falschen Wert beim zweiten Prüflauf nach seiner Veröffentlichung erkannt und korrigiert
Image qmcgaw/ddns-updater	v2.10.0	19 MB groß, im Betrieb rund 5 MiB Arbeitsspeicher

Der Container lief auf dem VPS statt im Heimnetz. Das Programm arbeitet dort genauso: Es fragt die öffentliche Adresse bei externen Diensten ab und spricht danach nur mit der netcup-API. Den Adresswechsel eines Heimanschlusses haben wir nachgestellt, indem wir den Eintrag per API auf eine falsche Adresse gesetzt haben. Für ddns-updater sieht das genauso aus wie ein Anschluss mit neuer Adresse.

Die öffentlichen Adressen des Testservers sind in Bildern und Ausgaben durch Beispieladressen ersetzt.

Voraussetzungen

• Eine Domain bei netcup im klassischen DNS mit den netcup-Nameservern
• Ein Legacy-API-Key und das API-Passwort aus dem CCP, wie in Teil 14 beschrieben
• Ein Gerät im Heimnetz, das dauerhaft läuft und Docker kann, etwa ein NAS, ein Mini-PC oder ein Raspberry Pi
• Für IPv4: Ihr Anschluss hat eine eigene öffentliche IPv4-Adresse. Bei DS-Lite oder CGNAT sehen die Echo-Dienste nur die Adresse Ihres Providers. Pflegen Sie dann nur den AAAA-Eintrag und lassen Sie den Eintrag mit ipv4 in Schritt 3 weg.
• Für IPv6: Das Gerät hat selbst eine öffentliche IPv6-Adresse

Ein Hinweis vorab: netcup kennzeichnet die Legacy-API im CCP als auslaufend. Der netcup-Support schrieb uns am 04.11.2026 außerdem, dass Domains eines Kundenkontos nur auf das neue CloudDNS umgestellt werden können, wenn dort keine Legacy-API-Keys mehr existieren. Wer DynDNS auf diesem Weg betreibt, bleibt also vorerst beim klassischen DNS.

Schritt 1: Verstehen, warum der Router das nicht allein kann

Router wie die FRITZ!Box melden eine neue Adresse per einfachem Aufruf einer Update-Adresse. Die DNS-API von netcup funktioniert anders: Ein Programm meldet sich zuerst an, bekommt eine Sitzung, liest die Einträge der Zone, schickt die Änderung als JSON und meldet sich wieder ab. Das kann der Router nicht. Deshalb übernimmt ein Programm im Heimnetz diese Arbeit, hier ddns-updater.

Die Ablaufkette sieht so aus:

1. ddns-updater fragt alle fünf Minuten die öffentliche IPv4- und IPv6-Adresse ab.
2. Es löst den Namen, etwa home.sedv-lab.de, über das normale DNS auf.
3. Stimmen beide nicht überein, schreibt es die neue Adresse über die netcup-API in die Zone.
4. netcup veröffentlicht die Änderung auf den drei Nameservern, danach läuft die TTL in fremden Resolvern ab.

Den Quelltext dazu haben wir für v2.10.0 nachgelesen. Der Vergleich in Punkt 3 geht gegen das DNS, nicht gegen einen eigenen Speicher. Ein Eintrag, den jemand von Hand im CCP verändert, wird deshalb ebenfalls wieder korrigiert.

Verifizieren: Sie kennen die drei Nameserver Ihrer Domain. dig +short NS sedv-lab.de zeigt sie, mit Ihrer Domain statt unserer.

Schritt 2: Ordner und Rechte anlegen

Die Befehle dieser Anleitung führen Sie als root oder mit sudo aus. Der Container läuft laut Projektdoku als Benutzer mit der ID 1000. Der Datenordner muss diesem Benutzer gehören, sonst kann das Programm seine Konfiguration nicht lesen und seinen Verlauf nicht schreiben:

mkdir -p /opt/ddns/data
chown 1000 /opt/ddns/data
chmod 700 /opt/ddns/data

Im Test lag der Ordner unter /root/ddns. Der Pfad ist frei wählbar.

Verifizieren: ls -ldn /opt/ddns/data zeigt drwx------ und als Besitzer 1000.

Schritt 3: Die Konfiguration schreiben

Legen Sie /opt/ddns/data/config.json an. Für einen Namen mit IPv4 und IPv6 brauchen Sie zwei Einträge:

{
  "settings": [
    {
      "provider": "netcup",
      "domain": "home.sedv-lab.de",
      "customer_number": "12345",
      "api_key": "IHR-API-KEY",
      "password": "IHR-API-PASSWORT",
      "ip_version": "ipv4"
    },
    {
      "provider": "netcup",
      "domain": "home.sedv-lab.de",
      "customer_number": "12345",
      "api_key": "IHR-API-KEY",
      "password": "IHR-API-PASSWORT",
      "ip_version": "ipv6",
      "ipv6_suffix": ""
    }
  ]
}

Unter domain steht der volle Name. ddns-updater zerlegt ihn selbst in Domain und Host, im Log und in der Oberfläche erscheint home als owner. Die Kundennummer steht laut Doku als Text in Anführungszeichen. password ist das API-Passwort, nicht das Passwort für das CCP. Die Doku nennt außerdem ipv6_suffix: Bleibt das Feld leer, trägt das Programm die IPv6-Adresse ein, mit der das Gerät nach außen geht. Auf Geräten mit Privacy Extensions ist das laut Doku eine temporäre Adresse, die regelmäßig wechselt. Mit einem Suffix wie 0:0:0:0:72ad:8fbb:a54e:bedd/64 setzt das Programm stattdessen das Präfix Ihres Anschlusses vor eine feste Geräteadresse. So zeigt der Eintrag auf die feste Adresse des Geräts oder auf ein anderes Gerät im Heimnetz. Unser VPS hat keine temporären Adressen, deshalb blieb das Feld im Test leer.

Schützen Sie die Datei, denn der API-Key gilt für alle Domains Ihres Kundenkontos:

chown 1000 /opt/ddns/data/config.json
chmod 600 /opt/ddns/data/config.json

Legen Sie für DynDNS einen eigenen Key an. Geht das Gerät einmal verloren, löschen Sie diesen Key im CCP und erzeugen ein neues API-Passwort. Laut Doku gibt es nur ein API-Passwort, das für alle Keys Ihres Kontos gilt. Ihre anderen Werkzeuge brauchen danach das neue Passwort.

Verifizieren: ls -ln /opt/ddns/data/config.json zeigt -rw------- und den Besitzer 1000. Ob das JSON gültig ist, zeigt der Start in Schritt 4.

Schritt 4: Den Container starten

Die compose.yaml in /opt/ddns:

services:
  ddns:
    image: qmcgaw/ddns-updater:v2.10.0
    container_name: ddns-updater
    restart: unless-stopped
    network_mode: host
    environment:
      - PERIOD=5m
      - UPDATE_COOLDOWN_PERIOD=5m
      - LISTENING_ADDRESS=127.0.0.1:8000
      - TZ=Europe/Berlin
      - LOG_LEVEL=info
    volumes:
      - ./data:/updater/data

Zwei Zeilen sind wichtig. network_mode: host lässt den Container das Netz des Geräts mitbenutzen. So erreicht er die Echo-Dienste auch über IPv6, was im normalen Docker-Netz ohne eigene IPv6-Einrichtung nicht geht. LISTENING_ADDRESS=127.0.0.1:8000 beschränkt die Weboberfläche auf das Gerät selbst, denn sie hat keine Anmeldung. Wollen Sie sie im Heimnetz sehen, tragen Sie statt 127.0.0.1 die interne IPv4-Adresse des Geräts ein. Vermeiden Sie 0.0.0.0, [::] und den Standardwert :8000: Das Gerät hat eine öffentliche IPv6-Adresse, und die Oberfläche wäre sonst je nach Router-Firewall von außen erreichbar.

Das Image gibt es auch als ghcr.io/qdm12/ddns-updater:v2.10.0.

PERIOD und UPDATE_COOLDOWN_PERIOD stehen hier mit ihren Standardwerten von fünf Minuten. Starten Sie den Container:

cd /opt/ddns
docker compose up -d
docker logs ddns-updater

Gekürzt sah der erste Lauf bei uns so aus:

14:38:32 INFO Found 2 settings to update records
14:38:32 INFO ipv4 address of home.sedv-lab.de is 46.38.243.234 and your ipv4 address is 203.0.113.10
14:38:32 INFO ipv6 address of home.sedv-lab.de is <none> and your ipv6 address is 2001:db8:15:16ab:800:5eff:fe00:5301
14:38:32 INFO Updating record [domain: sedv-lab.de | owner: home | provider: netcup | ip: ipv4] to use 203.0.113.10
14:38:32 INFO Updating record [domain: sedv-lab.de | owner: home | provider: netcup | ip: ipv6] to use 2001:db8:15:16ab:800:5eff:fe00:5301

Die Adresse 46.38.243.234 in der zweiten Zeile ist kein Fehler. In unserer frisch bestellten Domain standen ab Werk die Einträge @ und * mit der Adresse 46.38.243.234, einem Parkserver von netcup. Solange es home nicht gibt, beantwortet dieser Platzhalter die Anfrage. ddns-updater erkennt den Unterschied, legt die Einträge home für A und AAAA neu an und braucht dafür keinen vorbereiteten Eintrag im CCP.

Verifizieren: docker logs ddns-updater zeigt Found 2 settings to update records, und docker inspect ddns-updater --format '{{.State.Health.Status}}' zeigt nach etwa einer Minute healthy.

Schritt 5: Ergebnis in der Weboberfläche und im DNS prüfen

Die Oberfläche öffnen Sie auf dem Gerät unter http://127.0.0.1:8000, von einem anderen Rechner aus etwa über einen SSH-Tunnel mit ssh -L 8000:127.0.0.1:8000 benutzer@geraet. Sie zeigt je Eintrag den Stand des letzten Updates und die aktuelle Adresse:

Wichtiger als die Oberfläche ist, was die netcup-Nameserver ausliefern. Fragen Sie alle drei direkt, damit kein Zwischenspeicher dazwischenfunkt:

for ns in root second third; do
  for t in A AAAA; do
    echo "$ns $t: $(dig +short +norec home.sedv-lab.de $t @$ns-dns.netcup.net)"
  done
done

Wir haben das alle zehn Sekunden wiederholt. Nach dem ersten Lauf um 14:38:32 Uhr lieferte root-dns die neuen Einträge um 14:41:05 Uhr, second-dns um 14:41:56 Uhr und third-dns um 14:42:46 Uhr, A und AAAA jeweils gleichzeitig. Wie in Teil 15 gemessen, veröffentlicht netcup Änderungen gebündelt in Abständen von etwa zehn Minuten, die drei Nameserver übernehmen sie nacheinander.

Verifizieren: Alle drei Nameserver liefern Ihre aktuelle Adresse.

Schritt 6: Was bei einem Adresswechsel passiert

Um einen Wechsel nachzustellen, haben wir den A-Eintrag um 14:43:47 Uhr per API auf die falsche Adresse 198.51.100.23 gesetzt. Damit stimmte das DNS nicht mehr mit der tatsächlichen Adresse überein, wie nach einer Zwangstrennung zu Hause. So lief es weiter:

Uhrzeit	Ereignis
14:43:47	Falsche Adresse per API gesetzt
14:51:12 bis 14:53:03	Die drei Nameserver liefern die falsche Adresse aus
14:53:32	Planmäßiger Prüflauf, keine Änderung (bei LOG_LEVEL=info nicht im Log)
14:58:33	Prüflauf erkennt den Unterschied und schreibt die richtige Adresse
15:01:17	root-dns liefert wieder die richtige Adresse
15:02:17	second-dns ebenso
15:03:08	third-dns ebenso
15:03:33	Planmäßiger Prüflauf, kein weiteres Update (nicht im Log)

Der Prüflauf um 14:53:32 Uhr hat nichts geändert. Vermutlich lieferte der Resolver des Geräts noch die Antwort aus dem Lauf um 14:48:32 Uhr aus seinem Zwischenspeicher, die bei einer TTL von 300 Sekunden bis etwa 14:53:32 Uhr gültig war. Erst der nächste Lauf bemerkte die Abweichung.

Für einen echten Wechsel zu Hause entfällt dieser Teil, denn dort weicht die neue Adresse sofort vom DNS ab. Rechnen Sie dann mit drei Wartezeiten: bis zu fünf Minuten bis zum nächsten Prüflauf, im Test gut vier bis gut neun Minuten, bis alle netcup-Nameserver die Änderung ausliefern, und die TTL Ihrer Zone in fremden Resolvern. Da netcup etwa alle zehn Minuten veröffentlicht, kann der mittlere Teil im ungünstigen Fall auch etwas länger dauern als gemessen. In unserer neuen Domain stand die TTL der Zone ab Werk auf 86400 Sekunden, also einem Tag. So lange darf ein Resolver die alte Adresse behalten. Setzen Sie die TTL der Zone im CCP deshalb herunter, wir haben 300 Sekunden verwendet. ddns-updater ändert die TTL laut Doku nicht selbst.

In der Oberfläche steht der Wechsel danach unter Previous IPs:

Der Verlauf kennt nur Änderungen, die ddns-updater selbst geschrieben hat. Die falsche Adresse, die wir von außen gesetzt hatten, erscheint dort nicht, nur zweimal die richtige. Gespeichert ist der Verlauf in data/updates.json, mit Zeitstempel je Update.

Verifizieren: docker logs ddns-updater | grep Updating zeigt eine Zeile je Update, im Test drei: A und AAAA beim Start, A nach dem Wechsel.

Schritt 7: Den Betrieb absichern

• Key begrenzen: Ein eigener API-Key nur für DynDNS, wie in Schritt 3 beschrieben. Wer Docker-Rechte auf dem Gerät hat, kann die Datei config.json über den Container lesen.
• Oberfläche nicht öffnen: Sie hat keine Anmeldung, deshalb nur auf 127.0.0.1 oder eine interne Adresse binden.
• Version festhalten: Mit qmcgaw/ddns-updater:v2.10.0 statt latest ändert sich das Verhalten nicht unbemerkt. Updates spielen Sie bewusst ein.
• Fehler bemerken: Der Container hat einen eingebauten Healthcheck, den Docker als healthy oder unhealthy meldet. Laut Doku prüft er die Namensauflösung der eingetragenen Domains. Wer ohnehin ein Monitoring betreibt, kann den Status dort mit abfragen.

Verifizieren: ss -ltnp | grep ddns-updater zeigt 127.0.0.1:8000 für die Oberfläche und 127.0.0.1:9999 für den Healthcheck, keine Adresse wie 0.0.0.0 oder *.

Typische Fehler

Beobachtung	Erklärung und Lösung
Im Log steht beim ersten Start eine fremde Adresse wie 46.38.243.234	Der Platzhalter * einer netcup-Domain zeigt auf den Parkserver. ddns-updater legt den eigenen Eintrag trotzdem an, siehe Schritt 4.
Die Oberfläche meldet Success, der Name zeigt aber noch die alte Adresse	netcup hat die Änderung noch nicht veröffentlicht, oder ein Resolver liefert die alte Antwort bis zum Ablauf der TTL. Mit dig +norec direkt an den netcup-Nameservern prüfen, siehe Schritt 5.
Ein von Hand geänderter Eintrag wird einen Prüflauf später korrigiert als erwartet	Der Resolver des Geräts hatte vermutlich die alte Antwort noch im Zwischenspeicher, siehe Schritt 6. Bei einem echten Adresswechsel tritt das nicht auf.
Im Log steht nach dem Start nichts mehr	Normal. Bei LOG_LEVEL=info erscheinen nur Prüfläufe, die etwas ändern.

Häufige Fragen

Kann ich die FRITZ!Box direkt mit netcup verbinden?

Nicht mit der DNS-API allein, denn sie verlangt Anmeldung, Sitzung und JSON, siehe Schritt 1. Es gibt Projekte wie ownDynDNS, die ein PHP-Skript auf einem Webhosting als Mittler zwischen Router und API einsetzen. Mit einem Container im Heimnetz brauchen Sie keinen zusätzlichen Webspace.

Wie viele Namen kann ein Container pflegen?

Beliebig viele, jeder Name und jede IP-Version ist ein eigener Eintrag unter settings. Laut Doku sind auch Platzhalter wie *.sedv-lab.de möglich. Getestet haben wir einen Namen mit A und AAAA.

Wie oft spricht ddns-updater mit netcup?

Nur wenn das DNS eine andere Adresse liefert als die öffentliche. Die Prüfung alle fünf Minuten geht an Echo-Dienste und das DNS, nicht an die netcup-API. Im Test gab es in einer halben Stunde drei Updates, alle durch echte Abweichungen ausgelöst. Veröffentlicht netcup eine Änderung erst nach dem nächsten Prüflauf, kann das Programm laut Quelltext denselben Wert ein zweites Mal schreiben. Das schadet nicht.

Was passiert, wenn netcup die Legacy-API abschaltet?

Dann schlagen die Updates fehl, der Name zeigt nach dem nächsten Wechsel auf die alte Adresse. Beobachten Sie die Ankündigungen von netcup und prüfen Sie dann, ob ddns-updater die neue API unterstützt.

Lohnt sich das gegenüber einem kostenlosen DynDNS-Dienst?

Sie hängen nicht an einem Dienst, der eingestellt werden kann, wie zuletzt ddnss.de. Dafür tragen Sie selbst die Verantwortung für API-Key und Gerät.

Fazit

DynDNS mit einer netcup-Domain funktionierte im Test mit ddns-updater ohne Umwege: Konfiguration mit Kundennummer und API-Zugang, Container starten, fertig. Das Programm legt fehlende Einträge selbst an und korrigiert Abweichungen beim nächsten passenden Prüflauf. Die Wartezeit nach einem Wechsel bestimmt vor allem netcup: Im Test vergingen gut vier bis gut neun Minuten, bis alle Nameserver die Änderung auslieferten. Mit einer kurzen TTL in der Zone ist der Name danach schnell überall richtig.

Weiterführende Anleitungen und Quellen

• Teil 14: netcup-DNS mit Ansible pflegen
• Teil 15: Wildcard-Zertifikat mit Traefik und Caddy über die netcup-DNS-API
• Teil 7: netcup-Server nur mit IPv6
• Ubuntu-Server mit Docker als Grundlage
• Docker Compose absichern: Secrets, Healthchecks, Non-Root
• ddnss.de stellt DynDNS ein
• netcup: DNS-Einstellungen
• netcup: DNS-API (Legacy)
• ddns-updater auf GitHub
• ddns-updater: Anbieter netcup
• ownDynDNS auf GitHub