Repository files navigation

Program to keep DNS A and/or AAAA records updated for multiple DNS providers

This readme and thedocs/ directory areversioned to match the program version:

• Available as a Docker imageqmcgaw/ddns-updater andghcr.io/qdm12/ddns-updater

• Available aszero-dependency binaries for Linux, Windows and MacOS

• 🆕 Available in the AUR asddns-updater - see#808

• Updates periodically A records for different DNS providers:

  • Aliyun
  • AllInkl
  • Changeip
  • Cloudflare
  • DD24
  • DDNSS.de
  • deSEC
  • DigitalOcean
  • Domeneshop
  • DonDominio
  • DNSOMatic
  • DNSPod
  • Dreamhost
  • DuckDNS
  • DynDNS
  • Dynu
  • EasyDNS
  • FreeDNS
  • Gandi
  • GCP
  • GoDaddy
  • GoIP.de
  • He.net
  • Hetzner
  • Infomaniak
  • INWX
  • Ionos
  • Linode
  • Loopia
  • LuaDNS
  • Myaddr
  • Name.com
  • Namecheap
  • NameSilo
  • Netcup
  • NoIP
  • Now-DNS
  • Njalla
  • OpenDNS
  • OVH
  • Porkbun
  • Route53
  • Selfhost.de
  • Servercow.de
  • Spdyn
  • Strato.de
  • Variomedia.de
  • Vultr
  • Zoneedit
  • Want more?Create an issue for it!

• Web user interface (Desktop)

  

• Web user interface (Mobile)

  

• Send notifications withShoutrrr usingSHOUTRRR_ADDRESSES

• Container (Docker/K8s) specific features:

  • Lightweight 12MB Docker image based on the Scratch Docker image
  • Docker healthcheck verifying the DNS resolution of your domains
  • Images compatible withamd64,386,arm64,armv7,armv6,s390x,ppc64le,riscv64 CPU architectures

• Persistence with a JSON fileupdates.json to store old IP addresses with change times for each record

1. Download the pre-built program for your platform from the assets of a release in thereleases page. You can alternatively download, build and install the latest version of the program by installingGo and then rungo install github.com/qdm12/ddns-updater/cmd/ddns-updater@latest.

2. For Linux and MacOS, make the program executable withchmod +x ddns-updater.

3. In the directory where the program is saved, create a directorydata.

4. Write a JSON configuration indata/config.json, for example:

   {"settings": [        {"provider":"namecheap","domain":"sub.example.com","password":"e5322165c1d74692bfa6d807100c0310"        }    ]}

   You can find more information in theconfiguration section to customize it.

5. Run the program with./ddns-updater (./ddns-updater.exe on Windows) or by double-clicking on it.

6. The following isoptional.

   • You can customize the program behavior using eitherenvironment variables or flags. For flags, there is a flag corresponding to each environment variable, where it's all lowercase and underscores are replaced with dashes. For example the environment variableLOG_LEVEL translates into--log-level.

➡️ Qnap guide by @Araminta

1. Create a directory, for example,data which is:

   • owned by user id1000, which is the built-in user ID of the ddns-updater container
   • has user read+write+execute permissions

   mkdir datachown 1000 datachmod u+r+w+x data

   If you want to use another user ID,build the image yourself with--build-arg UID=<your-uid>. You could also just run the container as root with--user="0" but this is not advised security wise.

2. Similarly, create adata/config.json file which is:

   • owned by user id1000
   • has user read permissions

   touch data/config.jsonchmod u+r data/config.json

3. Editdata/config.json, for example:

   {"settings": [        {"provider":"namecheap","domain":"sub.example.com","password":"e5322165c1d74692bfa6d807100c0310"        }    ]}

   You can find more information in theconfiguration section to customize it.

4. Run the container with

   docker run -d -p 8000:8000/tcp -v"$(pwd)"/data:/updater/data qmcgaw/ddns-updater

5. The following isoptional.

   • You can customize the program behavior usingenvironment variables
   • You can usedocker-compose.yml withdocker-compose up -d
   • Kubernetes: check out thek8s directory for an installation guide and examples.
   • OtherDocker image tags are available
   • You can update the image withdocker pull qmcgaw/ddns-updater
   • You can set your JSON configuration as a single environment variable line (i.e.{"settings": [{"provider": "namecheap", ...}]}), which takes precedence over config.json. Note however that if you don't bind mount the/updater/data directory, there won't be a persistent database file/updater/updates.json but it will still work.

Start by having the following content inconfig.json, or in yourCONFIG environment variable:

{"settings": [        {"provider":"",        },        {"provider":"",        }    ]}

For each setting, you need to fill in parameters.Check the documentation for your DNS provider:

• Aliyun
• Allinkl
• ChangeIP
• Cloudflare
• Custom
• DDNSS.de
• deSEC
• DigitalOcean
• DD24
• Domeneshop
• DonDominio
• DNSOMatic
• DNSPod
• Dreamhost
• DuckDNS
• DynDNS
• Dynu
• DynV6
• EasyDNS
• FreeDNS
• Gandi
• GCP
• GoDaddy
• GoIP.de
• He.net
• Infomaniak
• INWX
• Ionos
• Linode
• Loopia
• LuaDNS
• Myaddr
• Name.com
• Namecheap
• NameSilo
• Netcup
• NoIP
• Now-DNS
• Njalla
• OpenDNS
• OVH
• Porkbun
• Selfhost.de
• Servercow.de
• Spdyn
• Strato.de
• Variomedia.de
• Vultr
• Zoneedit

Note that:

• you can specify multiple owners/hosts for the same domain using a comma separated list. For example with"domain": "example.com,sub.example.com,sub2.example.com",.⚠️ this is a bit different for DuckDNS and GoIP, see their respective documentation.

🆕 There are now flags equivalent for each variable below, for example--log-level.

By default, all public IP fetching types are used and cycled (over DNS and over HTTPs).

On top of that, for each fetching method, all echo services available are cycled on each request.

This allows you not to be blocked for making too many requests.

You can otherwise customize it with the following:

• PUBLICIP_HTTP_PROVIDERS gets your public IPv4 or IPv6 address. It can be one or more of the following:
  • ipify usinghttps://api64.ipify.org
  • ifconfig usinghttps://ifconfig.io/ip
  • ipinfo usinghttps://ipinfo.io/ip
  • spdyn usinghttps://checkip.spdyn.de
  • ipleak usinghttps://ipleak.net/json
  • icanhazip usinghttps://icanhazip.com
  • ident usinghttps://ident.me
  • nnev usinghttps://ip.nnev.de
  • wtfismyip usinghttps://wtfismyip.com/text
  • seeip usinghttps://api.seeip.org
  • changeip usinghttps://ip.changeip.com
  • You can also specify an HTTPS URL with prefixurl: for exampleurl:https://ipinfo.io/ip
• PUBLICIPV4_HTTP_PROVIDERS gets your public IPv4 address only. It can be one or more of the following:
  • ipleak usinghttps://ipv4.ipleak.net/json
  • ipify usinghttps://api.ipify.org
  • icanhazip usinghttps://ipv4.icanhazip.com
  • ident usinghttps://v4.ident.me
  • nnev usinghttps://ip4.nnev.de
  • wtfismyip usinghttps://ipv4.wtfismyip.com/text
  • seeip usinghttps://ipv4.seeip.org
  • You can also specify an HTTPS URL with prefixurl: for exampleurl:https://ipinfo.io/ip
• PUBLICIPV6_HTTP_PROVIDERS gets your public IPv6 address only. It can be one or more of the following:
  • ipleak usinghttps://ipv6.ipleak.net/json
  • ipify usinghttps://api6.ipify.org
  • icanhazip usinghttps://ipv6.icanhazip.com
  • ident usinghttps://v6.ident.me
  • nnev usinghttps://ip6.nnev.de
  • wtfismyip usinghttps://ipv6.wtfismyip.com/text
  • seeip usinghttps://ipv6.seeip.org
  • You can also specify an HTTPS URL with prefixurl: for exampleurl:https://ipinfo.io/ip
• PUBLICIP_DNS_PROVIDERS gets your public IPv4 address only or IPv6 address only or one of them (see #136). It can be one or more of the following:
  • cloudflare
  • opendns

If you have a host firewall in place, this container needs the following ports:

• TCP 443 outbound for outbound HTTPS
• UDP 53 outbound for outbound DNS resolution
• TCP 8000 inbound (or other) for the WebUI

At program start and every period (5 minutes by default):

1. Fetch your public IP address
2. For each record:
   1. DNS resolve it to obtain its current IP address(es)
      • If the resolution fails, update the record with your public IP address by calling the DNS provider API and finish
   2. Check if your public IP address is within the resolved IP addresses
      • Yes: skip the update
      • No: update the record with your public IP address by calling the DNS provider API

💡 We do DNS resolution every period so it detects a change made to the record manually, for example on the DNS provider web UI💡 As DNS resolutions are essentially free and without rate limiting, these are great to avoid getting banned for too many requests.

For Cloudflare records with theproxied option, the following is done.

At program start and every period (5 minutes by default), for each record:

1. Fetch your public IP address
2. For each record:
   1. Check the last IP address (persisted inupdates.json) for that record
      • If it doesn't exist, update the record with your public IP address by calling the DNS provider API and finish
   2. Check if your public IP address matches the last IP address you updated the record with
      • Yes: skip the update
      • No: update the record with your public IP address by calling the DNS provider API

This is the only way as doing a DNS resolution on the record will give the IP address of a Cloudflare server instead of your server.

⚠️ This has the disadvantage that if the record is changed manually, the program will not detect it.We could do an API call to get the record IP address every period, but that would get you banned especially with a low period duration.

• The automated healthcheck verifies all your records are up to dateusing DNS lookups
• You can also manually check, by:
  1. Going to your DNS management webpage
  2. Setting your record to127.0.0.1
  3. Run the container
  4. Refresh the DNS management webpage and verify the update happened

You can build the image yourself with:

docker build -t qmcgaw/ddns-updater https://github.com/qdm12/ddns-updater.git

You can use optional build arguments with--build-arg KEY=VALUE from the table below:

• Contribute with code
• Github workflows to know what's building
• List of issues and feature requests

This repository is under anMIT license

• Starttoaster/docker-traefik

Sponsor me onGithub or donate topaypal.me/qmcgaw

Many thanks to J. Famiglietti for supporting me financially 🥇👍