DDNS

DDNS is a golang tool used to update dynamic DNS entries on supported dynamic DNS services.

Command line flags

The DDNS CLI lets you interact with the DDNS service

Usage:
  ddns [flags]
  ddns [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  run         Run A record synchronization once
  serve       Serve daemon that periodically performs A record synchronization

Flags:
      --config string     relative or absolute path to the config file (default "./config.yml")
  -h, --help              help for ddns
      --loglevel string   log level, possible values: trace, debug, info, warn, error, fatal, panic (default "info")
  -v, --version           version for ddns

Use "ddns [command] --help" for more information about a command.

Example Config File

waitInterval: "1m"
retryInterval: "10s"

metricsServer:
  enable: true
  host: 127.0.0.1
  port: 8080

staticIPAddressProvider:
  enable: false
  address: "10.0.0.1"

urlIPAddressProvider:
  enable: true
  url: "www.example.com/ipaddress"
  https: true
  insecureSkipVerify: false
  regex: ""
  username: "username"
  password: "password"

cloudflareDNSProvider:
  enable: true
  apiToken: "12345"
  zoneID: "12345"
  aRecords:
    - "example.com"
    - "www.example.com"

If multiple DNS or IP Address providers are specified in the config file, only one will take effect, The order of precedence is the order in which the providers are listed below, with the first provider having the highest priority.

Configuration parameters specified via environment variables take precedence over those specified in the config file.

Global Configuration Parameters

Key	Env Var	Type	Default Value	Required	Description
waitInterval	DDNS_WAIT_INTERVAL	time.Duration	1m	false	time.Duration to wait after successfully updating records
retryInterval	DDNS_RETRY_INTERVAL	time.Duration	5s	false	time.Duration to wait after a failed attempt to update records

Metrics Server Configuration Parameters

Configuration Key: metricsServer

Key	Env Var	Type	Default Value	Required	Description
enable	DDNS_METRICS_ENABLE	bool	true	true	Enable metrics endpoint listening on /metrics path
host	DDNS_METRICS_HOST	string	0.0.0.0	false	Host to be bound by the metrics handler
port	DDNS_METRICS_PORT	string	9097	false	Port to be bound by the metrics handler

Available Metrics

Name	Type	Help
ddns_build_info	Gauge	Metric with a constant '1' value labeled by version and goversion from which ddns was built.
ddns_start_time_seconds	Gauge	Start time of the process since unix epoch in seconds.
ddns_dns_a_record_info	Gauge	Metric with a constant '1' value showing the current a records and their ip addresses.

Available Providers for Retrieving the IP Address

StaticIPAddressProvider

Ip address provider that returns the static ip address that is provided in the config file.

Configuration Key: staticIPAddressProvider

Key	Env Var	Type	Default Value	Required	Description
enable	DDNS_STATIC_PROVIDER_ENABLE	bool	false	true	Enable this provider
address	DDNS_STATIC_PROVIDER_ADDRESS	string	127.0.0.1	false	Static ip address to return

URLIPAddressProvider

Ip address provider that makes a get request against the url that is provided in the config file and parses the response body using the regex if defined.

Configuration Key: urlIPAddressProvider

Key	Env Var	Type	Default Value	Required	Description
enable	DDNS_URL_PROVIDER_ENABLE	bool	false	true	Enable this provider
url	DDNS_URL_PROVIDER_URL	string	127.0.0.1	false	URL to get the ip address from with a GET request
https	DDNS_URL_PROVIDER_HTTPS	bool	true	false	Use https when accessing the url if true, http otherwise
insecureSkipVerify	DDNS_URL_PROVIDER_INSECURE	bool	false	false	Ignore bad certificates when accessing the url
regex	DDNS_URL_PROVIDER_REGEX	string		false	Regex to match the ip address containing a single numbered match group, see https://pkg.go.dev/regexp/syntax
username	DDNS_URL_PROVIDER_USERNAME	string		false	Basic auth username to use when accessing the url, only set if required
password	DDNS_URL_PROVIDER_PASSWORD	string		false	Basic auth password to use when accessing the url, only set if required

For example, if the website https://www.example.com/ipaddress returned this json:

{"address":"192.168.0.100"}

Then the following configuration could be used to get the ip address from there:

urlIPAddressProvider:
  enable: true
  url: "www.example.com/ipaddress"
  regex: '"address":\s?"(.*)"'

Available DNS Providers

CloudflareDNSProvider

Configuration Key: cloudflareDNSProvider

Key	Env Var	Type	Default Value	Required	Description
enable	DDNS_CLOUDFLARE_PROVIDER_ENABLE	bool	false	true	Enable this provider
apiToken	DDNS_CLOUDFLARE_API_TOKEN	string		true	Cloudflare API token with All zones - DNS:Read, DNS:Edit permissions
zoneID	DDNS_CLOUDFLARE_PROVIDER_ZONE_ID	string		true	Cloudflare zone id
aRecords	DDNS_CLOUDFLARE_PROVIDER_RECORDS	[]string		true	List of A records to update

Build Docker Image

Docker image is available at Docker Hub.

export VERSION=`cat VERSION`
docker build . -t ddns:v${VERSION}

Example Systemd Service File

This service file assumes that a user called ddns exists, and that the config file is located at /etc/ddns/ddns.yaml.

sudo groupadd ddns
sudo useradd -r -g ddns ddns
sudo mkdir /etc/ddns
# Write config file to /etc/ddns/ddns.yaml
sudo chmod 600 /etc/ddns/ddns.yaml
sudo chown ddns:ddns -R /etc/ddns/

[Unit]
Description=Dynamic DNS Client
After=network.target

[Service]
Type=simple
User=ddns
ExecStart=/usr/local/bin/ddns -config /etc/ddns/ddns.yaml

[Install]
WantedBy=multi-user.target