ddnsd

Unified DDNS Client

ddnsd is a single-binary daemon that keeps DNS records and CDN/edge origins pointed at your current public IP. It periodically detects the machine's public IPv4/IPv6 address and, whenever it changes, pushes the new address to every configured target — a Cloudflare record, an Alibaba Cloud DNS record, a Tencent EdgeOne origin, and more — from one config file.

• One daemon, many targets — sync any number of DNS records and CDN origins across different providers at once.
• DNS and origin following — besides classic A/AAAA record updates, it can rewrite the origin address of CDN / edge-acceleration services (Tencent EdgeOne, Tencent CDN, Alibaba Cloud ESA), which plain DDNS clients cannot do.
• Dual stack — IPv4 and IPv6 are detected, tracked, and retried independently per target.
• Change detection — provider APIs are only called when the IP actually changed since the last successful apply; failed applies are retried on the next tick.
• Deterministic IP detection — the v4/v6 probes use address-family-pinned HTTP clients, so a dual-stack IP service always reports the right family.
• Hot reload — send SIGHUP to reload config.yaml without restarting; check period, probe DNS resolver, and provider list are updated in place, and last-applied state is carried over so nothing is re-applied spuriously.
• Structured logging with rotation — zap logs to stdout plus optional rotating JSON files (a full log and a warn+ error log) via lumberjack.

Requires Go ≥ 1.26.

go build -ldflags="-s -w" -trimpath -o ddnsd

ddnsd reads config.yaml from its working directory. The config.yaml in this repository is a fully commented example — copy it next to the binary and edit it. A minimal config:

# Check interval in seconds.
period: 60

api:
  # Public IP source per family: "ipip.net", "gh.ink", or a custom URL.
  # Leave blank to disable that family.
  v4: "ipip.net"
  v6: ""
  # resolver: ""   # optional custom DNS server for probe-hostname lookups

providers:
  - type: cloudflare
    name: home
    ipv4: true
    ipv6: false
    token: "your-api-token"
    zone: "your-zone-id"
    record: "home.example.com"

./ddnsd

The daemon runs in the foreground, checks the public IP every period seconds, and applies changes to all configured providers. Reload the config at runtime with:

kill -HUP $(pidof ddnsd)

A custom IP source must respond 200 OK with a bare IP as the body (e.g. 1.1.1.1) and include the protocol in the URL. The URL is fetched over the matching address family only, so the service must be reachable via that family.

Probe hostnames (myip.ipip.net, v4/v6-myip.gh.ink, or the host in a custom API URL) are resolved with the system resolver by default. Set api.resolver to a DNS server IP — optionally with a port, e.g. 1.1.1.1:5353 — to route those lookups through that server instead; useful when the probe hostnames are only reachable via a specific resolver.

Every entry under providers: shares four common fields; the rest are provider-specific:

At least one of ipv4/ipv6 must be true, otherwise the entry is skipped.

Set exactly one of origin_group_id / domain_name.

• Each provider entry becomes one independent job per enabled family, so v4 and v6 are change-detected and retried separately.
• A provider API is only called when the detected IP differs from the last successfully applied value; a failed apply keeps the old state so the next tick retries it.
• Every provider API call is bounded by a 30-second timeout.
• If an IP probe fails or a family is disabled, that family is simply skipped for the tick — other targets still sync.
• On SIGHUP the config is re-read: the check period is re-registered if changed and the provider set is rebuilt, carrying over last-applied state for entries that still exist.
• If a config_debug.yaml exists in the working directory it is loaded instead of config.yaml and the log level switches to debug.

[Unit]
Description=ddnsd - unified DDNS client
After=network-online.target
Wants=network-online.target

[Service]
WorkingDirectory=/opt/ddnsd
ExecStart=/opt/ddnsd/ddnsd
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=multi-user.target

go test ./...

Project layout:

main.go                    entry point: config → logger → checker → cron
internal/config            viper-based config loading, SIGHUP hot reload hooks
internal/checker           public IP detection (family-pinned clients) + sync driver
internal/provider          Provider interface, registry, change-detecting Manager
internal/provider/<type>   one package per provider, self-registered via init()
internal/cron              periodic scheduler (gocron)
internal/logger            zap + lumberjack logging

Adding a provider: create internal/provider/<name>, implement the Provider interface (Name() + idempotent Apply(ctx, family, ip)), call provider.Register("<type>", factory) in init(), and blank-import the package in internal/provider/all/all.go.

Apache-2.0