Home

Awesome

Lightweight universal DDNS Updater program

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

<img height="200" alt="DDNS Updater logo" src="https://raw.githubusercontent.com/qdm12/ddns-updater/master/readme/ddnsgopher.svg">

Build status

dockeri.co

Last release Last Docker tag Last release size GitHub last release date Commits since release

Latest size

GitHub last commit GitHub commit activity GitHub closed PRs GitHub issues GitHub closed issues

Lines of code Code size GitHub repo size Go version

MIT Visitors count

Versioned documentation

This readme and the docs/ directory are versioned to match the program version:

VersionReadme linkDocs link
LatestREADMEdocs/
v2.7.0READMEdocs/
v2.6.1READMEdocs/
v2.5.0READMEdocs/

Features

Setup

Binary programs

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

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

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

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

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

    You can find more information in the configuration 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 is optional.

    • You can customize the program behavior using either environment 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 variable LOG_LEVEL translates into --log-level.

Container

āž”ļø Qnap guide by @Araminta

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

    • owned by user id 1000, which is the built-in user ID of the ddns-updater container
    • has user read+write+execute permissions
    mkdir data
chown 1000 data
chmod 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 a data/config.json file which is:

    • owned by user id 1000
    • has user read permissions
    touch data/config.json
chmod u+r data/config.json

  3. Edit data/config.json, for example:

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

    You can find more information in the configuration 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 is optional.

    • You can customize the program behavior using environment variables
    • You can use docker-compose.yml with docker-compose up -d
    • Kubernetes: check out the k8s directory for an installation guide and examples.
    • Other Docker image tags are available
    • You can update the image with docker 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.

Configuration

Start by having the following content in config.json, or in your CONFIG environment variable:

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

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

Note that:

Environment variables

šŸ†• There are now flags equivalent for each variable below, for example --log-level.

Environment variableDefaultDescription
CONFIGOne line JSON object containing the entire config (takes precedence over config.json file) if specified
PERIOD5mDefault period of IP address check, following this format
PUBLICIP_FETCHERSallComma separated fetcher types to obtain the public IP address from http and dns
PUBLICIP_HTTP_PROVIDERSallComma separated providers to obtain the public IP address (ipv4 or ipv6). See the Public IP section
PUBLICIPV4_HTTP_PROVIDERSallComma separated providers to obtain the public IPv4 address only. See the Public IP section
PUBLICIPV6_HTTP_PROVIDERSallComma separated providers to obtain the public IPv6 address only. See the Public IP section
PUBLICIP_DNS_PROVIDERSallComma separated providers to obtain the public IP address (IPv4 and/or IPv6). See the Public IP section
PUBLICIP_DNS_TIMEOUT3sPublic IP DNS query timeout
UPDATE_COOLDOWN_PERIOD5mDuration to cooldown between updates for each record. This is useful to avoid being rate limited or banned.
HTTP_TIMEOUT10sTimeout for all HTTP requests
SERVER_ENABLEDyesEnable the web server and web UI
LISTENING_ADDRESS:8000Internal TCP listening port for the web UI
ROOT_URL/URL path to append to all paths to the webUI (i.e. /ddns for accessing https://example.com/ddns through a proxy)
HEALTH_SERVER_ADDRESS127.0.0.1:9999Health server listening address
HEALTH_HEALTHCHECKSIO_BASE_URLhttps://hc-ping.comBase URL for the healthchecks.io server
HEALTH_HEALTHCHECKSIO_UUIDUUID to idenfity with the healthchecks.io server
DATADIR/updater/dataDirectory to read and write data files from internally
CONFIG_FILEPATH/updater/data/config.jsonPath to the JSON configuration file
BACKUP_PERIOD0Set to a period (i.e. 72h15m) to enable zip backups of data/config.json and data/updates.json in a zip file
BACKUP_DIRECTORY/updater/dataDirectory to write backup zip files to if BACKUP_PERIOD is not 0.
RESOLVER_ADDRESSYour network DNSA plaintext DNS address to use to resolve your domain names defined in your settings only. For example it can be 1.1.1.1:53. This is useful for split dns, see #389
LOG_LEVELinfoLevel of logging, debug, info, warning or error
LOG_CALLERhiddenShow caller per log line, hidden or short
SHOUTRRR_ADDRESSES(optional) Comma separated list of Shoutrrr addresses (notification services)
SHOUTRRR_DEFAULT_TITLEDDNS UpdaterDefault title for Shoutrrr notifications
TZTimezone to have accurate times, i.e. America/Montreal
UMASKSystem current umaskUmask to set for the program in octal, i.e. 0022

Public IP

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:

Host firewall

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

Architecture

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.

Special case: Cloudflare

For Cloudflare records with the proxied 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 in updates.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.

Testing

Build the image

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:

Build argumentDefaultDescription
UID1000User ID running the container
GID1000User group ID running the container
VERSIONunknownVersion of the program and Docker image
CREATEDan unknown dateBuild date of the program and Docker image
COMMITunknownCommit hash of the program and Docker image

Development and contributing

License

This repository is under an MIT license

Used in external projects

Support

Sponsor me on Github or donate to paypal.me/qmcgaw

Many thanks to J. Famiglietti for supporting me financially šŸ„‡šŸ‘