krimsn/dnspatch repository overview

Keep your DNS records pointed at your home or server IP, even when your ISP changes it.

dnspatch is a dynamic DNS daemon in Go. It watches your public IPv4 and IPv6 address and updates your DNS records when it changes. It is a single static binary or a container image of a few megabytes, with no runtime dependencies.

Documentation⁠ · Config builder⁠ · Releases⁠ · Docker Hub⁠ · GitHub Container Registry⁠ · API reference⁠ · Issues⁠

⁠Why dnspatch

• Many providers, one tool. Cloudflare, DuckDNS, No-IP, Dynu, Namecheap, your own BIND or PowerDNS over RFC 2136, any dyndns2 service⁠ and several regional hosts (REG.RU, NIC.RU, Selectel, Timeweb, Yandex Cloud, Beget).
• No single point of failure for the lookup. Several retrievers per instance with fallback between them (ipify, icanhazip, ifconfig.co, ident.me, 2ip, or a local network interface), so one flaky lookup service doesn't break updates.
• IPv4, IPv6 and dual-stack. A and AAAA records are handled independently.
• Several sites in one process. Independent instances, each with its own interval, retrievers and providers.
• Knows when something breaks. A container health check, pings to Healthchecks.io or Uptime Kuma, and events published to Redis, RabbitMQ or MQTT for your own alerts. A failing provider backs off instead of hammering an API.
• Secrets stay out of the config. ${ENV} substitution and ${file:...} for Docker and Kubernetes secrets.
• Extensible without forking. Retrievers, providers and notifiers are plugins, and the plugin contract is a public Go package, so you can add your own in your own module.

⁠Quick start

Prefer a form to a text editor? The online builder⁠ assembles dnspatch.toml and tells you which image or build tags you need.

1. Create dnspatch.toml. This keeps home.example.com on Cloudflare pointed at your current public IP:

   [[instance]]
   name = "home"
   
   [[instance.retriever]]
   type = "ipify"
   
   [[instance.provider]]
   type    = "cloudflare"
   zone_id = "YOUR_ZONE_ID"
   zone    = "example.com"
   rr_name = "home"
   token   = "${CF_TOKEN}"   # read from the environment
   

   Copy

2. Put the secret in .env, which stays out of the config file:

   CF_TOKEN=your-api-token-scoped-to-Zone-DNS-Edit
   

   Copy

3. Create compose.yml next to them:

   services:
     dnspatch:
       image: krimsn/dnspatch:latest
       restart: unless-stopped
       env_file: .env
       volumes:
         - ./dnspatch.toml:/etc/dnspatch/config.toml:ro
   

   Copy

4. Run it:

   docker compose up -d
   

   Copy

dnspatch --check-config validates the file without starting the daemon. Ready-made configs for dual-stack, fallback between retrievers, several providers, proxies, secrets from files and your own name server are in examples/⁠. The compose.yml⁠ in the repository root is a fuller version with log rotation and a read-only filesystem.

⁠Install

• Binary for Linux, macOS and Windows from the releases page⁠.

• Container image from Docker Hub (krimsn/dnspatch) or the GitHub Container Registry (ghcr.io/dnspatch/dnspatch). The latest-full tag adds the notifiers and the rfc2136, yandexcloud and namecheap providers.

• From source, with Go 1.27 or newer:

  go install github.com/dnspatch/dnspatch/cmd/dnspatch@latest
  

  Copy

  This builds the lightweight version: without the notifiers (Redis, RabbitMQ, MQTT) and without the rfc2136, yandexcloud and namecheap providers. To get them, add the full build tag, or the tag of just the plugin you need:

  go install -tags full github.com/dnspatch/dnspatch/cmd/dnspatch@latest
  

  Copy

Docker Compose, build tags for a smaller binary and cross-compiling are in the installation guide⁠. Not sure which build or tags you need? The builder⁠ picks them from the plugins in your config.

⁠Supported providers

The full list with every parameter is in the parameter reference⁠. Your provider isn't there? Use dyndns2 if it speaks that protocol, or write a plugin⁠.

⁠Documentation

The full documentation is at dnspatch.github.io/dnspatch⁠:

• Quick start⁠ and configuration⁠: instances, dual-stack, fallback between retrievers, secrets, proxies
• Config builder⁠: an interactive form that produces a config and the matching image or build tags
• Built-in plugins⁠ and the parameter reference⁠ of every retriever and provider
• Docker⁠ and building from source⁠ with build tags
• Monitoring⁠: health check, pings, notifications
• Writing a plugin⁠
• Plugins outside the repository⁠: your own module and binary

Ready-made configs for specific scenarios are in examples/⁠.

⁠Contributing

Bug reports and ideas go to GitHub Issues⁠. CONTRIBUTING.md⁠ covers commit messages and pull requests; the documentation sources are in docs/⁠.

⁠License

MIT — see LICENSE⁠.