Informationen für Entwickler

Nach einer Anfrage des Clients (Request), antwortet der Server (Response, bei DynDNS.org Return Code genannt). Wenn mehrere Hostnamen angegeben werden, wird in der Regel auch für den Hostnamen eine Rückmeldung pro Zeile ausgegeben.

Wann kommt welcher Return Code?

• HTTP-Code: 200
• Bedeutung: Es ist alles in Ordnung und die gewünschten Änderungen wurden vollständig übernommen.
• Anmerkung: Einem good folgt die aktuell gesetzte IP-Adresse.

• HTTP-Code: 200
• Bedeutung: Es ist alles in Ordnung, aber es wurden keine Änderungen vorgenommen, denn die Anfrage entsprach schon den Daten im System.
• Anmerkung: Einem nochg folgt die aktuell gesetzte IP-Adresse.

• HTTP-Code: 401
• Bedeutung: Die Authorisation ist fehlgeschlagen. Die Parameter username und/oder password sind falsch.

• HTTP-Code: 401
• Bedeutung: Die Authorisation ist fehlgeschlagen. Der im HTTP-Header angegeben User-Agent ist nicht zugelassen.
• Anmerkung: badagent wird von uns (vorerst) nicht unterstützt.

• HTTP-Code: 401
• Bedeutung: Das erbitterte Feature ist dem Client nicht erlaubt.
• Anmerkung: Bei uns ist jedes implementierte Feature erlaubt

• HTTP-Code: 400
• Bedeutung: Der Parameter system ist ungültig. Gültige Werte sind dyndns, statdns oder ein Zahlenwert.

• HTTP-Code: 400
• Bedeutung: Der Parameter hostname ist leer oder gar nicht gesetzt.
• Anmerkung: Eine Begrenzung der maximalen Anzahl von Hostnamen gibt es bei uns nicht.

• HTTP-Code: 400
• Bedeutung: Der Parameter hostname existiert nicht im System.
• Anmerkung: Unser System macht von diesem Return Code keinen Gebrauch. Stattdessen wird ein abuse ausgegeben.

• HTTP-Code: 400
• Bedeutung: Der Parameter hostname ist ungültig, da der angegebene Domainname keinem Fully Qualified Domain Name entspricht.

• HTTP-Code: 400
• Bedeutung: Es wurde zwar ein Domainname im System gefunden, doch gehört er nicht dem User.
• Anmerkung: Bei uns wird dies mit einem abuse quittiert.

• HTTP-Code: 400
• Bedeutung: Entweder existiert die als hostname angegebene Zone bzw. der Domainname nicht, ist nicht dynamisch oder gehört nicht dem User.
• Anmerkung: abuse wird von DynDNS.org auch dazu benutzt, allzu vielen Anfragen einen Riegel vorzuschieben. Das ist uns egal. Das System verkraftet einiges. Sollte es zu exorbitant hohen Requests von einzelnen kommen, werden uns die Log-Einträge weiterhelfen.

• HTTP-Code: 500
• Bedeutung: Ein Fehler im DNS-System trat auf.
• Anmerkung: Einem dnserr folgt eine nähere Erläuterung. Wir bitten jeden, der so einen Return Code bekommt, ihn an unseren Support weiterzuleiten. Wir kümmern uns dann darum!

• HTTP-Code: 500
• Bedeutung: 911 ist die Notrufnummer in den USA. Bei Dynamic Domain Name System (DDNS) bedeutet dieser Return Code, dass ein fataler Fehler auftrat und der Request nicht weiterbearbeitet werden kann.
• Anmerkung: Dem 911 folgt eine nähere Fehlerbeschreibung, die sehr hilfreich sein kann. Sollte sie es nicht, bitte an den Support wenden!
• Fehlerbeschreibungen und Ursachen:
  • ddns down: Der DDNS-Service ist deaktiviert. Das kann bei Wartungsarbeiten schon mal vorkommen.
  • ssl mode [0|1|2]: Entweder akzeptiert das System nur noch Anfragen per SSL [2] oder solche Anfragen werden verweigert [0]. [1] bedeutet, dass beide Modi möglich sind.
  • hostname, myip, wildcard, mx, backmx, offline und ttl betreffen die jeweiligen Parameter. Diese sollten überprüft werden.

Wichtig: Sollten Fehler auftreten, dann sollte der Client keine weiteren Anfragen an unser System stellen, bis der Benutzer eingreift.

Sollte der Service überhaupt nichts zurückliefern, bitten wir, sich an unseren Support zu wenden.

Der Request ist eine HTTP- bzw. HTTPS-Anfrage an das System. Wir akzeptieren HTTP/1.1. Benutzername und Passwort werden gemäß den HTTP-Spezifkationen im Header der Anfrage in einem base64-enkodierten String übertragen, alle anderen Daten entweder per GET oder POST.

In der Anfrage enthalten sind die Parameter, die im folgenden näher erklärt werden:

• Beschreibung: Der Benutzname. Er muss im Klartext (Plain Text) im Header (HTTP 401) gesendet werden.
• mögliche Werte: ein gültiger Benutzername
• Optional: nein

• Beschreibung: Das Passwort. Es muss im Klartext (Plain Text) im Header (HTTP 401) gesendet werden.
• mögliche Werte: ein zum Benutzername passendes Passwort
• Optional: nein

• Beschreibung: Sozusagen ein Profil, das die Time to live (DNS) festlegt.
• mögliche Werte: dyndns (TTL: 120 Sekunden), statdns (3600 Sekunden) oder eine Zahl zwischen 120 und 10800 (3 Stunden). Defaultwert ist dyndns.
• Optional: ja

• Beschreibung: Welche Domainname soll aktualisiert werden?
• mögliche Werte: ein oder mehrere durch Kommata getrennte Domainnamen. Alternativ ist auch ein Array möglich.
• Optional: nein

• Beschreibung: Zu welcher IP-Adresse soll der Domainname aufgelöst werden?
• mögliche Werte: eine gültige öffentliche IP-Adresse. Sollte der Parameter nicht gesetzt werden, versucht das System, die IP-Adresse selbst zu bestimmen. Achtung: Sollte der Client hinter einem Proxy, NAT-Router o.ä. hängen, könnte die IP-Adresse auf ein falsches Ziel verweisen.
• Optional: ja

• Beschreibung: Sollen Wildcards akzeptiert werden? Diese würden dann wie der angegebene Domainname auf die gleiche IP-Adresse verweisen.
• mögliche Werte: ON, OFF oder NOCHG. Sollte dieser Parameter leer sein, wird er auf OFF gesetzt. Defaultwert ist OFF.
• Optional: ja

• Beschreibung: MX steht für Mail Exchanger. Dies ist ein Eintrag im Domain Name System (DNS), der eine IP-Adresse zu einem Mailserver angibt.
• mögliche Werte: ein gültiger Domainname, eine IP-Adresse, NOCHG oder REMOVE. NOCHG bedeutet, dass der Eintrag im System nicht geändert werden soll, REMOVE löscht den Eintrag. Ist der Parameter leer, so wird REMOVE angenommen. Defaultwert ist NOCHG.
• Optional: ja

• Beschreibung: Mehrere Mail Exchanger können im DNS mit unterschiedlichen Prioritäten abgelegt werden, um zum Beispiel Ausfälle zu vermeiden. Soll der im Parameter mx angegebene Mail Exchanger als Backup fungieren, muss dieser Parameter mitgesendet werden.
• mögliche Werte: YES, NO, NOCHG. Sollte der Wert leer sein, wird NO angenommen. Defaultwert ist NOCHG.
• Optional: ja

• Beschreibung: Soll der Domainname offline gesetzt werden? Sollte dies der Fall sein, werden alle Einträge gelöscht. Siehe auch Offline-Status
• mögliche Werte: YES oder NO. Defaultwert ist NO.
• Optional: ja

Anmerkung: Defaultwerte werden nur bei optionalen Parametern, die nicht gesetzt worden sind, vom System gesetzt.

Beispiele machen das Leben einfacher: Hier anhand eines Internet-Browsers als Client.

In jeder Zone einer dynamischen Domain existiert ein besonderer TXT-Datensatz, der Hinweise auf das letzte Update-Datum der Domain gibt. Das Format ist „c=Timestamp“, wobei der Timestamp dem Unix-Timestamp zum letzten Update auf dem Server entspricht.

Diese Information ist besonders hilfreich, wenn Clients sich z.B. nach dem Heartbeat richten müssen, damit Domains, deren IP sich nicht geändert hat, nicht offline gesetzt werden.

• Spezifikationen von DynDNS.org: http://www.dyndns.com/developers/specs/