crazyus3r/ionos-ddns repository overview

⁠🌐 Go-DynDNS

Ein hochperformanter, in Go geschriebener Multi-Provider Dynamic DNS Client mit vollwertigem Web-Dashboard. Unterstützt IONOS, Cloudflare, IPv64, Hetzner DNS, Hetzner Cloud Febas und DNScale — gleichzeitig, pro Domain konfigurierbar.

⁠✨ Highlights

• Multi-Provider: IONOS, Cloudflare, IPv64, Hetzner DNS, Hetzner Cloud, Febas und DNScale — auch gemischt in einer Instanz
• Web-Dashboard: Echtzeit-Monitoring via WebSockets — IP-Historie, API-Metriken, Logs, Diagnose und Einstellungen
• Dashboard-Auth: Rollenbasierte Benutzerverwaltung (Admin / Editor / Viewer) mit sicherem PBKDF2-Passwort-Hashing
• 2FA / TOTP: Optionale Zwei-Faktor-Authentifizierung per RFC-6238-konformem TOTP (Google Authenticator, Authy)
• Dual-Stack: Gleichzeitige Aktualisierung von A (IPv4) und AAAA (IPv6) Records
• Pro Domain konfigurierbar: IP-Modus (IPV4/IPV6/BOTH/CNAME) und TTL lassen sich je Domain überschreiben
• Intelligente IPv6-Erkennung: Direkt vom Interface (via netlink) oder über öffentliche Endpunkte als Fallback
• Cache-First: Zonen- und Record-Caches werden auf Disk persistiert — kein unnötiger API-Call nach Neustart
• Cleanup: Automatisches Entfernen verwaister DNS-Records, die nicht mehr in der Konfiguration stehen
• Benachrichtigungen: Telegram (inkl. Bot-Commands), Gotify, Ntfy, Webhook, MQTT (inkl. Home Assistant Discovery) und E-Mail (SMTP)
• Backup & Restore: Export/Import von Config, Status und Benutzern direkt aus dem Dashboard
• Diagnose / Health Center: Übersicht über System-, Provider- und Notifier-Status mit konfigurierbaren Warnungen
• Prometheus-Metriken: Endpunkt /metrics/prometheus für Grafana & Co.
• Parallele Verarbeitung: Einstellbares Worker-Limit für schnelle Updates bei vielen Domains
• Multi-Architektur: Native Images für linux/amd64 und linux/arm64 (Raspberry Pi, NAS, Server)
• Keine externen Go-Abhängigkeiten für TOTP: Stdlib-only-Implementierung

⁠🚀 Quick Start (Docker Compose)

Das einfachste Setup — Dashboard unter http://server-ip:8080, Konfiguration über die UI:

services:
  go-dyndns:
    image: crazyus3r/ionos-ddns:latest
    container_name: go-dyndns
    ports:
      - "8080:8080"
    volumes:
      - ./config:/config
    restart: unless-stopped

Beim ersten Start öffnet sich die Setup-Seite zum Erstellen des Admin-Accounts. Domains und Provider werden danach vollständig über das Dashboard konfiguriert und in /config/config.json gespeichert.

⁠⚙️ Konfiguration

⁠Option A — Dashboard (empfohlen)

Alle Einstellungen lassen sich nach dem ersten Login unter Einstellungen im Dashboard verwalten:

• System (Intervall, IP-Modus, DNS-Server, Debug, Dry-Run, Sprache …)
• Domains mit Provider-Zugangsdaten
• Benachrichtigungen (Telegram, Gotify, Webhook, MQTT, E-Mail)
• Benutzerverwaltung

Änderungen werden sofort in /config/config.json übernommen.

⁠Option B — Umgebungsvariablen (Legacy / CI)

Für den ersten Start oder automatisierte Deployments können Domains auch per ENV konfiguriert werden. Beim ersten Schreiben wird automatisch eine config.json erzeugt.

⁠Allgemeine Variablen

⁠Single-Provider (Legacy)

# IONOS
PROVIDER=IONOS
API_PREFIX=dein_prefix
API_SECRET=dein_secret
DOMAINS=home.example.com,sub.example.com

# Cloudflare
PROVIDER=CLOUDFLARE
CLOUDFLARE_TOKEN=dein_api_token
DOMAINS=home.example.com

# IPv64
PROVIDER=IPV64
IPV64_TOKEN=dein_token
DOMAINS=home.example.ipv64.net

# Hetzner DNS
PROVIDER=HETZNER
HETZNER_TOKEN=dein_token
DOMAINS=home.example.com

# Hetzner Cloud DNS
PROVIDER=HETZNERCLOUD
HCLOUD_TOKEN=dein_token
DOMAINS=home.example.com

# Febas
PROVIDER=FEBAS
FEBAS_UPDATE_URL=https://www.febas.de/api/dyndns.php?kundenid=DEINE_ID&token=DEIN_TOKEN
DOMAINS=home.example.com

# DNScale
PROVIDER=DNSCALE
DNSCALE_TOKEN=dein_api_key
DOMAINS=home.example.com

⁠Multi-Provider via DOMAINS_CONFIG

Mehrere Provider gleichzeitig — auch gemischt:

DOMAINS_CONFIG='[
  {
    "fqdn": "home.example.com,sub.example.com",
    "provider": "IONOS",
    "api_prefix": "dein_prefix",
    "api_secret": "dein_secret"
  },
  {
    "fqdn": "home.example.ipv64.net",
    "provider": "IPV64",
    "ipv64_token": "dein_token"
  },
  {
    "fqdn": "cf.example.com",
    "provider": "CLOUDFLARE",
    "cf_token": "dein_cf_token",
    "cf_proxied": false
  },
  {
    "fqdn": "hz.example.com",
    "provider": "HETZNER",
    "api_secret": "dein_hetzner_token"
  },
  {
    "fqdn": "hc.example.com",
    "provider": "HETZNERCLOUD",
    "api_secret": "dein_hcloud_token"
  },
  {
    "fqdn": "febas.example.com",
    "provider": "FEBAS",
    "febas_update_url": "https://www.febas.de/api/dyndns.php?kundenid=DEINE_ID&token=DEIN_TOKEN"
  },
  {
    "fqdn": "dnscale.example.com",
    "provider": "DNSCALE",
    "dnscale_token": "dein_api_key"
  }
]'

Unterstützte Felder je Eintrag: fqdn, provider, api_prefix, api_secret, cf_token, cf_email, cf_secret, cf_proxied, ipv64_token, hetzner_token, hcloud_token, febas_update_url, dnscale_token, ttl, ip_mode

⁠📦 Unterstützte Provider

⁠📊 Dashboard

Das Dashboard ist unter http://server-ip:8080 erreichbar und bietet:

• Übersicht: Letzter Check, Uptime, IP-Endpunkt-Status
• Domains: IP-Historie pro Domain mit Zeitstrahl, Provider-Status, Orphan-Erkennung
• Metriken: Total Requests, Success Rate, Latenz-Perzentile (P50/P85/P99), HTTP-Methoden-Verteilung, stündliche Charts
• Diagnose / Health Center: System-, Config-, Provider- und Notifier-Status auf einen Blick
• Logs: Filterbar nach Level und Aktion, Export als TXT oder JSON
• Debug-Log: Live-Stream interner Ereignisse (nur bei aktiviertem Debug-Modus)
• Backup & Restore: Config, Domain-Status und Benutzer exportieren und wiederherstellen
• Einstellungen: Vollständige Konfiguration über die UI — kein manuelles Editieren von JSON nötig
• Benutzerverwaltung: Admin, Editor und Viewer-Rollen

⁠Rollenmodell

⁠🔔 Benachrichtigungen

Konfigurierbar über das Dashboard oder config.json:

Für jeden Notifier lassen sich die gewünschten Events einzeln auswählen (Update, Create, Error, Start, Stop, Cleanup, …).

⁠🩺 Health Check

GET http://server-ip:8080/health
GET http://server-ip:8080/health?detailed=true
GET http://server-ip:8080/metrics/prometheus

Die /health-Route liefert 200 OK, degraded oder 503 Unhealthy. Docker-HEALTHCHECK ist im Image bereits konfiguriert.

⁠📁 Datenverzeichnis (/config)

/config/
├── config.json             # Hauptkonfiguration
├── users.json              # Benutzerkonten (bcrypt/PBKDF2 gehashed)
├── lang/
│   ├── de.json
│   └── en.json
└── logs/
│   ├── dyndns.json         # Ereignis-Log (JSON Lines)
│   ├── update.json         # IP-Historie pro Domain
│   ├── metrics.json        # Persistierte Metriken
│   ├── ionos_cache.json    # Zonen-/Record-Cache IONOS
│   ├── cloudflare_cache.json
│   ├── ipv64_cache.json
│   ├── hetzner_dns_cache.json
│   └── hetzner_cloud_cache.json
└── tls/
    ├── dashboard.crt
    └── dashboard.key

Beispiel update.json:

{
  "home.example.com": {
    "provider": "IONOS",
    "last_changed": "18.01.2026 13:22:00",
    "ips": [
      {
        "time": "18.01.2026 13:22:00",
        "ipv4": "203.0.113.1",
        "ipv6": "2001:db8::1"
      }
    ]
  }
}

⁠🏗 Manuelle Installation (Binaries)

Vorkompilierte Binaries für Linux (amd64/arm64) und Windows sind unter Releases⁠ verfügbar.

# Umgebungsvariablen setzen, dann:
./go-dyndns

# Oder mit CONFIG_DIR
CONFIG_DIR=/pfad/zur/config ./go-dyndns

⁠🔑 API-Keys erstellen

IONOS: developer.hosting.ionos.com⁠ → neuen Key anlegen → Public Prefix + Secret kopieren

Cloudflare: Mein Profil → API-Token → Token erstellen → Zone:DNS:Edit-Berechtigung

IPv64: ipv64.net⁠ → API-Key aus dem Dashboard

Hetzner DNS: dns.hetzner.com⁠ → API-Tokens

Hetzner Cloud: console.hetzner.cloud⁠ → Projekt → API-Tokens

Febas: Kundenbereich auf febas.de⁠ → Update-URL mit kundenid und token aus dem DynDNS-Bereich kopieren

DNScale: dnscale.io⁠ → API-Bereich → Bearer-Token erstellen

⁠⚖️ Lizenz

Dieses Projekt steht unter der MIT-Lizenz⁠.