uDDNS

Micro multi-provider Dynamic DNS updater. Defaults to Cloudflare, and also supports DuckDNS, No-IP, Dynu, Namecheap, Route53, Porkbun, Hetzner, DigitalOcean, Gandi, Linode, OVH, bunny.net, Contabo, and generic DynDNS-compatible endpoints.

Checks your public IP on an interval and updates DNS only when it changes. Recommended interval: 900000 (15 minutes). Allowed range: 60 s–24 h.

One process manages one provider/account by default. Use UDDNS_CONFIG_FILE for multi-account YAML, or run separate processes (with separate .env and state files) when you prefer isolation.

Requirements

• Vite+ (vp)
• Node.js (managed by Vite+ / Corepack)
• pnpm via Corepack (packageManager in package.json)

Install

corepack enable
vp install

Or open the repo in a Dev Container (VS Code "Reopen in Container" or devcontainer up): .devcontainer/ provisions Node 24, pnpm, the Vite+ toolchain, and Docker, then installs dependencies automatically.

Run

vp run build
vp run start

start loads .env via Node's --env-file-if-exists=.env (no dotenv package) and runs the core updater daemon. .env is read only at process start; SIGHUP rereads UDDNS_CONFIG_FILE YAML, while .env changes require a restart.

CLI helpers after build:

node dist/cli.js init --defaults
node dist/cli.js once --dry-run
node dist/cli.js once --force
node dist/cli.js check-config

Configuration is validated before any network request. After building, validate and exit:

vp run config:check

Documentation

• Providers and configuration
• Security (outbound HTTPS, auth, allowlists)
• Optional MCP server
• Deployment with systemd, Docker, or Compose
• Development, architecture, and adding providers

Logging

Set UDDNS_LOG_LEVEL to error, warn, info (default), or debug. Set UDDNS_LOG_FORMAT to text (default) or json.

• Timestamps include seconds
• Failures include HTTP status/timing, sanitized URLs, response previews, and hints
• Secrets (tokens, passwords, Authorization, usernames, OAuth client IDs) are redacted from log context
• Use debug when chasing provider/API issues

Public IP discovery

Public addresses are discovered without a third-party IP package: HTTPS echo services first (icanhazip, ipify, ifconfig.co — TLS authenticates the answer). Connections use pin-on-connect so DNS cannot rebind to a private/metadata host between resolve and dial. Optional DNS fallbacks (OpenDNS myip.opendns.com, then Google o-o.myaddr.l.google.com TXT) are off by default because plain DNS can be spoofed on-path; enable with UDDNS_IP_DNS_FALLBACK=true only on networks where HTTPS echo is unreachable and you trust the DNS path. Override endpoints with UDDNS_IP_HTTPS_V4 / UDDNS_IP_HTTPS_V6.

See Security for host-safety rules and notification URL policy.

Configuration

Copy .env.example, choose one provider/account, and configure one or more hosts. The default interval is 900000 ms and checkpoints persist in .uddns-state.json.

See Providers and configuration for provider-specific examples. Transient provider updates retry with configurable backoff (UDDNS_RETRY_*). For multiple accounts in one process, set UDDNS_CONFIG_FILE to a YAML file (see examples/uddns.multi.yaml). For ordered DNS-provider failover on the same hostname, see examples/uddns.failover.yaml.