API-Dokumentation

Authentifizierung

Jede Anfrage benötigt deinen persönlichen API-Schlüssel. Du findest ihn in den Einstellungen. Am sichersten übergibst du ihn als Bearer-Token im Authorization-Header.

Authorization: Bearer DEIN_API_KEY
X-API-Key: DEIN_API_KEY

Alternativ werden die URL-Parameter key und api_key unterstützt.

Request senden

Query-Parameter werden bei allen Methoden gelesen. POST, PATCH und DELETE akzeptieren zusätzlich einen JSON-Body mit Content-Type application/json.

Unterstützte Record-Typen: A, AAAA, CNAME, TXT sowie MX für eigene Domains.

Beispiele

A-Record auf die erkannte Client-IP setzen

curl "https://rb-ddns.net/?api=update&host=zuhause&type=A&key=DEIN_API_KEY"

AAAA-Record mit JSON aktualisieren

curl -X PATCH "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"zuhause","record_type":"AAAA","target_value":"2001:db8::24","ttl":300}'

Zusätzlichen TXT-Wert in einer eigenen Domain anlegen

curl -X POST "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"_acme-challenge","domain":"example.com","record_type":"TXT","target_value":"challenge-token","ttl":300,"append":true}'

Die Antwort enthält die public_id dieses einzelnen TXT-Werts. Verwende genau diese ID beim Löschen, damit weitere Werte im selben TXT-RRset erhalten bleiben.

Record einer eigenen Domain löschen

curl -X DELETE "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_id":"rec_..."}'

Let’s Encrypt Wildcard-Zertifikate

Wildcard-Zertifikate werden über die DNS-01-Challenge ausgestellt. Der Auth-Hook legt den von Certbot gelieferten Wert als zusätzlichen TXT-Record unter _acme-challenge an, wartet auf die Sichtbarkeit bei allen autoritativen Nameservern und gibt die eindeutige public_id an Certbot zurück. Der Cleanup-Hook löscht danach ausschließlich diesen Wert.

Damit können example.com und *.example.com gemeinsam in einem Zertifikat stehen, obwohl Let’s Encrypt dafür gleichzeitig zwei unterschiedliche TXT-Werte am selben Namen verlangen kann.

Automatisch einrichten

Der folgende Befehl lädt den RB-ddns-Installer und führt ihn mit root-Rechten aus:

curl -fsSL "https://rb-ddns.net/public/downloads/install-certbot-rbddns.sh" | sudo bash

Eine feste Zone ist nicht erforderlich. Der Auth-Hook übergibt den vollständigen Challenge-Namen an die API. RB-ddns erkennt daraus automatisch die verwaltete Domain und liefert sie für die Nameserver-Prüfung zurück. Derselbe API-Schlüssel kann dadurch für beliebig viele Domains des Kontos verwendet werden.

Für die Installation werden Linux oder ein anderes Unix-System, Bash und curl benötigt. Für die Zertifikatsanforderung müssen außerdem Certbot, Python 3 und dig installiert sein; fehlende Programme werden vom Installer angezeigt.

Zertifikat anfordern

sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook /usr/local/lib/rb-ddns/auth.sh \
  --manual-cleanup-hook /usr/local/lib/rb-ddns/cleanup.sh \
  -d *.example.com -d example.com

Certbot speichert die Hook-Konfiguration für spätere Verlängerungen. Der API-Schlüssel wird automatisch aus der geschützten Konfigurationsdatei gelesen; die passende Domain wird bei jeder Challenge neu erkannt. Prüfe den vollständigen Ablauf anschließend mit sudo certbot renew --dry-run.

Antworten und Fehler

Die API antwortet immer mit JSON. Eine erfolgreiche Aktualisierung enthält ok, Informationen zur DNS-Synchronisierung und den aktualisierten Record.

{
  "ok": true,
  "sync": {
    "ok": true,
    "message": "DNS-Record wurde aktualisiert."
  },
  "record": {
    "public_id": "rec_...",
    "hostname": "zuhause",
    "domain": "rb-ddns.net",
    "record_type": "A",
    "target_value": "203.0.113.24",
    "ttl": 300,
    "enabled": true
  }
}