Dokumentation

Alles, was du in deinem Konto selbst erledigen kannst – von der ersten Zone bis zur API. Die Beispiele zeigen echte Aufrufe gegen diese Installation.

Überblick

NimbusDNS beantwortet DNS-Anfragen für deine Domains. Du legst im Dashboard eine Zone an (das ist deine Domain), setzt darin Records (die einzelnen Einträge) und hinterlegst beim Registrar die zugewiesenen Nameserver.

Der Aufbau besteht aus zwei Teilen:

• Panel – Dashboard, API und Datenhaltung. Hier arbeitest du.
• Nameserver – beantworten die Anfragen aus dem Internet. Sie holen sich den Zonenstand alle 15 Sekunden vom Panel.

Konto und E-Mail-Bestätigung

Nach der Registrierung schicken wir dir einen Bestätigungslink. Bis du ihn angeklickt hast, kannst du dich zwar anmelden und dich umsehen, aber noch keine Zone anlegen.

Im Dashboard steht so lange ein Hinweisband mit einem Knopf, um die Mail erneut zu schicken – falls sie im Spam gelandet oder verloren gegangen ist.

Anmelden mit Discord oder Google

Auf der Anmeldeseite stehen – sofern der Betreiber sie eingerichtet hat – Knöpfe für Discord und Google. Damit brauchst du kein eigenes Passwort.

Mit einem bestehenden Konto verknüpfen

Unter Mein Konto verbindest du beide Dienste mit deinem vorhandenen Zugang. Danach kommst du wahlweise per Passwort oder per Anbieter hinein.

Wieder trennen

Ebenfalls unter Mein Konto. Der letzte verbliebene Anmeldeweg lässt sich nicht kappen – hast du kein Passwort gesetzt, vergib erst eines und trenne dann die Verknüpfung.

Erste Zone anlegen

1. Im Dashboard auf Zonen → + Zone hinzufügen.
2. Die Domain eintragen, zum Beispiel deine-domain.de – ohne www und ohne https://.
3. Standard-TTL bestätigen (300 Sekunden sind ein guter Startwert).

NimbusDNS legt SOA und NS automatisch an und weist der Zone zwei Nameserver zu. Welche das sind, steht oben in der Zonenansicht.

Nameserver delegieren

Damit deine Domain weltweit auflöst, musst du die beiden Nameserver bei deinem Registrar eintragen – dort, wo du die Domain gekauft hast. Das ist der Schritt, an dem es am häufigsten hakt.

1. Im Dashboard die Zone öffnen und die beiden Nameserver kopieren.
2. Beim Registrar unter „Nameserver" bzw. „DNS-Einstellungen" beide eintragen – die vorhandenen ersetzen, nicht ergänzen.
3. Speichern und warten. Die Registry übernimmt das meist in Minuten, gelegentlich dauert es bis zu 48 Stunden.

Delegations-Check

In der Zonenansicht prüft der eingebaute Check, ob alles zusammenpasst, und sagt dir bei jedem Punkt, was zu tun ist:

• Lösen die Nameserver-Hostnamen auf?
• Zeigen sie auf verschiedene Server? (Registries verlangen das)
• Antwortet dort wirklich jemand auf Port 53 – über UDP und TCP?
• Führt die Registry die Nameserver schon?

Von einem anderen Anbieter umziehen

Damit während des Umzugs nichts ausfällt, in dieser Reihenfolge vorgehen:

1. Zuerst alle Records anlegen – am schnellsten über den Zonefile-Import. Beim alten Anbieter findest du meist einen Export.
2. Prüfen, ob alles stimmt: im Dashboard unter Werkzeuge die wichtigsten Namen abfragen.
3. Erst dann beim Registrar die Nameserver umstellen.
4. Den alten Anbieter noch ein paar Tage stehen lassen, bis alle Resolver die alte Antwort vergessen haben.

Record-Typen

NimbusDNS unterstützt diese Typen:

Der Name eines Records

• @ steht für die Domain selbst (deine-domain.de)
• www wird zu www.deine-domain.de
• * ist ein Wildcard – siehe unten

Regeln, die NimbusDNS durchsetzt

• Neben einem CNAME darf auf demselben Namen kein weiterer Record stehen.
• Ein CNAME darf nicht auf sich selbst zeigen.
• Identische Records lassen sich nicht doppelt anlegen.
• Die Nameserver der Zone sind gesetzt und nicht überschreibbar.

Wildcards

Ein Record auf * beantwortet alle Subdomains – und zwar in jeder Verschachtelungstiefe:

*  A  203.0.113.99

a.deine-domain.de        → 203.0.113.99
a.b.deine-domain.de      → 203.0.113.99
tief.verschachtelt.deine-domain.de → 203.0.113.99

Ein genauer Eintrag gewinnt immer gegen den Wildcard: Steht www auf einer eigenen IP, bekommt www diese – alle anderen den Wildcard.

CNAME am Zonen-Apex

Eigentlich verbietet der Standard einen CNAME direkt auf der Domain (@) – trotzdem braucht man ihn ständig, etwa wenn ein Dienst nur einen Hostnamen und keine feste IP nennt.

NimbusDNS löst das mit Flattening: Du trägst den CNAME ganz normal ein, im Hintergrund wird das Ziel regelmäßig aufgelöst und als A/AAAA ausgeliefert. Ändert der Dienst seine IP, zieht NimbusDNS nach.

TTL richtig wählen

Die TTL sagt Resolvern, wie lange sie eine Antwort behalten dürfen – ein Kompromiss zwischen Geschwindigkeit und Beweglichkeit. Im Record-Dialog wählst du sie aus einer Liste:

Wichtig: Eine Änderung wirkt erst, wenn die alte TTL abgelaufen ist. Vor geplanten Umstellungen also rechtzeitig heruntersetzen.

Zonefile Import/Export

NimbusDNS liest und schreibt das übliche BIND-Format. Zum Umziehen oder Sichern reicht ein Knopfdruck in der Zonenansicht – oder die API:

# Sichern
curl "http://nimbusdns.crazyde.de/api/v1/zones/$ZONE/export" \
  -H "Authorization: Bearer $NIMBUS_TOKEN" > sicherung.zone

# Einspielen
curl -X POST "http://nimbusdns.crazyde.de/api/v1/zones/$ZONE/import" \
  -H "Authorization: Bearer $NIMBUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"zonefile\": \"$(cat sicherung.zone)\", \"replace\": false}"

Beim Import meldet die Antwort, wie viele Records übernommen wurden und welche Zeilen übersprungen wurden – samt Grund. SOA und die NS am Apex werden bewusst ignoriert, die verwaltet NimbusDNS selbst.

SSL-Zertifikate

In der Zonenansicht gibt es kostenlose Zertifikate von Let's Encrypt. Der Nachweis läuft über einen TXT-Eintrag in deiner Zone, den NimbusDNS selbst setzt und danach wieder entfernt (DNS-01).

Zwei Vorteile gegenüber dem üblichen Weg:

• Wildcard-Zertifikate sind möglich (*.deine-domain.de).
• Es muss kein Webserver erreichbar sein – der Nachweis läuft ausschließlich über DNS.

Erneuert wird automatisch 30 Tage vor Ablauf. Zertifikat und Schlüssel liegen auf dem Panel-Server; der private Schlüssel wird nur für seinen Eigentümer lesbar gespeichert.

Analytics

Jede Zone hat einen eigenen Verlauf: Anfragen pro Stunde, Verteilung nach Record-Typ und Antwortcode, die häufigsten Namen und die Antwortzeiten – aufgeschlüsselt nach Nameserver.

Die Antwortcodes bedeuten:

Zone im Team bearbeiten

Jede Zone gehört einem Konto, kann aber mit beliebig vielen weiteren Personen geteilt werden: Zone öffnen, Karte Team, + Mitglied. Die Person braucht bereits ein eigenes NimbusDNS-Konto – eingeladen wird über ihre E-Mail-Adresse.

Geteilte Zonen erscheinen in der Zonenliste der Mitglieder mit einem Abzeichen für die eigene Rolle. Wer den Zugriff nicht mehr möchte, kann die Zone in der Team-Karte selbst verlassen; der Besitzer kann jederzeit jemanden entfernen.

Dynamisches DNS

Dein Internetanschluss bekommt vom Anbieter regelmäßig eine neue IP-Adresse – meist bei jeder Neueinwahl. Ein Name im DNS zeigt aber auf eine feste Adresse. Genau diese Lücke schließt dynamisches DNS.

Du brauchst dafür keine eigene Domain: Der Betreiber stellt eine oder mehrere Domains bereit, und du sicherst dir darunter einen Namen. Im Dashboard unter Dynamisches DNS → + Name sichern.

Wie es funktioniert

1. Melden. Dein Router oder ein kleines Programm zu Hause stellt fest, welche öffentliche Adresse der Anschluss gerade hat, und ruft eine URL auf. Darin stecken dein Name und dein Token.
2. Eintragen. Wir prüfen das Token und schreiben die Adresse als ganz normalen A- bzw. AAAA-Record in die Zone.
3. Ausliefern. Die Nameserver beantworten Anfragen nach deinem Namen ab dem nächsten Abgleich mit der neuen Adresse.

Im Router einrichten

FritzBox, Speedport, OPNsense und die meisten anderen können das ab Werk. Dort „Eigener Anbieter" wählen und die drei Angaben eintragen, die dir das Dashboard fertig zum Kopieren hinlegt:

Die FritzBox setzt <ipaddr>, <ip6addr> und <domain> selbst ein. Andere Hersteller schreiben die Felder anders (myip, ip, ipv6) – wir verstehen alle Varianten.

Ohne Router

Ein Aufruf genügt, zum Beispiel per Cron:

curl "http://nimbusdns.crazyde.de/ddns/update?hostname=heim.beispiel-domain.de&token=DEIN_TOKEN"

Ohne ip-Parameter nehmen wir die Adresse, von der der Aufruf kommt. Wer wissen will, welche das ist, ruft http://nimbusdns.crazyde.de/ip auf.

Für den Dauerbetrieb gibt es einen fertigen Client (ddns-client/ im Projekt): Er meldet nur, wenn sich etwas geändert hat, und bringt eine systemd-Unit samt Timer mit.

Antworten der Update-Schnittstelle

/nic/update spricht dyndns2 und antwortet mit reinem Text. Router prüfen wörtlich auf diese Wörter:

Wenn der Anschluss keine öffentliche Adresse hat

Der häufigste Grund, warum DDNS nicht funktioniert, liegt gar nicht am DNS: Viele Anschlüsse haben schlicht keine eigene öffentliche IPv4 mehr. Der Anbieter teilt eine Adresse auf hunderte Kunden auf – das heißt DS-Lite oder CGNAT und ist bei Kabel- und Mobilfunkanschlüssen die Regel.

Erkennen kannst du das an einer Adresse aus 100.64.0.0/10 im Router (etwa 100.72.13.9) – oder daran, dass wir die Meldung mit einem entsprechenden Hinweis ablehnen. Ein Blick auf http://nimbusdns.crazyde.de/ip sagt dir, was von deinem Anschluss bei uns ankommt.

Der Umweg über einen Server mit fester Adresse

Wenn wirklich nichts hereinkommt, dreht man die Richtung um: Dein Rechner baut selbst eine Verbindung zu einem Server auf, der eine feste Adresse hat, und der reicht Anfragen durch diesen Tunnel zurück. Üblich sind ein kleiner VPS mit WireGuard, ein SSH-Reverse-Tunnel oder ein fertiger Tunneldienst.

Für DDNS heißt das: Der Name zeigt dann auf den Tunnelserver, nicht auf deinen Anschluss – und weil dessen Adresse fest ist, brauchst du dafür streng genommen gar kein DDNS mehr, sondern nur einen normalen A-Record.

Grenzen

• Bis zu fünf Namen je Konto.
• Höchstens 20 Meldungen pro Minute und Name. Gezählt werden Aufrufe, nicht Änderungen – ein echter Adresswechsel wird nie abgelehnt.
• Nur öffentlich routbare Adressen. Private Netze, Link-Local und CGNAT-Adressen weisen wir ab: Der Name zeigte sonst ins Nichts.
• Namen wie www, mail oder ns1 sind reserviert, ebenso alles, was der Betreiber schon vergeben hat.

Passwort-Tresor

Für Node-Keys, Server-Zugänge und API-Tokens gibt es einen verschlüsselten Tresor: AES-256-GCM, der Schlüssel entsteht per scrypt aus deinem Master-Passwort und wird nirgends gespeichert.

Die Anmeldepasswörter der Konten liegen dagegen als scrypt-Hash vor und sind grundsätzlich nicht einsehbar – auch nicht für Administratoren.

Schutz vor Bots

Beim ersten Aufruf des Dashboards siehst du kurz eine Zwischenseite: Dein Browser löst dabei still eine kleine Rechenaufgabe. Das dauert einen Augenblick und hält automatisierte Zugriffe fern. Danach hast du für Stunden Ruhe.

Fällt dein Verhalten auf – etwa nach mehreren Fehlanmeldungen –, kommt zusätzlich eine Bild-Abfrage. Sie verschwindet von selbst wieder, sobald eine Weile nichts mehr auffällt.

REST-API

Alles, was das Dashboard kann, geht auch über die API. Das Antwortformat ist immer gleich:

{ "success": true, "errors": [], "messages": [], "result": … }

Die wichtigsten Endpunkte

Aufgeführt ist, was dein eigenes Konto darf. Serverweite Endpunkte gibt es zusätzlich, die brauchen aber Administratorrechte.

Beispiel

curl -X POST "http://nimbusdns.crazyde.de/api/v1/zones/$ZONE/dns_records" \
  -H "Authorization: Bearer $NIMBUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","content":"203.0.113.10","ttl":300}'

Bei MX kommt priority dazu, bei SRV zusätzlich weight und port, bei CAA flags und tag.

API-Tokens

Tokens erstellst du im Dashboard unter API-Tokens. Sie werden nur beim Anlegen einmal angezeigt und danach ausschließlich als Hash gespeichert.

curl "http://nimbusdns.crazyde.de/api/v1/zones" \
  -H "Authorization: Bearer ndns_dein-token"

DNS-over-HTTPS

Dieser Server beantwortet DoH-Anfragen unter http://nimbusdns.crazyde.de/dns-query – im JSON-Format von Cloudflare und Google sowie binär nach RFC 8484.

# JSON
curl "http://nimbusdns.crazyde.de/dns-query?name=www.example.com&type=A"

# RFC 8484 (binär)
curl -X POST "http://nimbusdns.crazyde.de/dns-query" \
  -H "Content-Type: application/dns-message" \
  --data-binary @anfrage.bin

Fehlersuche

Die Domain löst nicht auf

1. Zonenansicht öffnen und den Delegations-Check laufen lassen.
2. Zeigt die Registry noch die alten Nameserver, ist die Änderung beim Registrar hängengeblieben – dort erneut versuchen.
3. Direkt beim Nameserver nachfragen:

dig @ns1.deine-nameserver.de deine-domain.de A
nslookup deine-domain.de ns1.deine-nameserver.de

Kommt hier eine Antwort mit aa=1, arbeitet NimbusDNS korrekt und es liegt an der Delegation oder an einem Cache.

Änderung wirkt nicht

Fast immer die TTL: Resolver behalten die alte Antwort so lange, wie sie durften. Prüfen lässt sich das mit einer direkten Abfrage am Nameserver – die zeigt sofort den neuen Stand.

Alte Website erscheint weiter

Wenn DNS bereits die neue Adresse liefert, liegt es am Browser-Cache oder an einem CDN davor. Ein Test im privaten Fenster oder mit curl -I trennt beides sauber.

Zertifikat schlägt fehl

Meist ist die Delegation noch nicht durch – Let's Encrypt fragt die offiziell eingetragenen Nameserver. Zum Ausprobieren gibt es die Staging-Umgebung, die keine Kontingente verbraucht.

Was NimbusDNS nicht kann

Damit du nicht danach suchst:

• DNSSEC-Signierung – Zonen werden nicht signiert. Der Schalter in der Oberfläche ist ein Platzhalter.
• Zonentransfer (AXFR/IXFR) – die Nameserver synchronisieren über die HTTP-API statt über klassische Transfers.
• Rekursive Auflösung – die Nameserver sind rein autoritativ und lehnen fremde Namen mit REFUSED ab. Das ist Absicht: sonst wären sie offene Resolver.
• Domain-Registrierung – Domains kaufst du weiterhin bei einem Registrar.