ddns.conf — Configuration file for the DDNS update client
The ddns.conf file is the main configuration file of the
ddns update client.
This file specifies runtime configuration parameters for the program and
contains configurations for dynamic host entries that are managed by
ddns.
The syntax of the configuration file is based on the INI configuration file format. Lines starting with hash (#) or semi-colon (;) are ignored.
The following options can be configured:
proxy = http://HOST:PORT
This option will configure the HTTP proxy server that is used to communicate with the providers HTTP APIs.
The proxy is given as an URL, with or without http://, and may
contain a username and a password.
For example: proxy = http://user:pass@proxy.example.org:3128
guess_external_ip = [true|false]
Determine the public IP addresses by using external servers.
By default, this option is disabled and automatically enabled if the client has only IP addresses defined in RFC1918 or other reserved address space.
interface = name
The interface whose addresses are used when the IP addresses are not being guessed with help of external servers.
By default, this is the interface with the default route. Only addresses that can be reached from the Internet are being used, and temporary IPv6 addresses (privacy extensions) are being skipped.
The DDNS client supports the configuration of an unlimited amount of entries for different providers. Each entry has to be configured as an own section named by the FQDN (Fully Qualified Domain Name) inside squared brackets.
The FQDN of the dynamic host, which must not be a handle or something other than a FQDN. Wildcards (*.example.com) are allowed if the provider supports them.
ddns remembers the addresses that it has sent, and only sends an update when they have changed, or when the provider wants to have its records refreshed. Before the first update, the name is being resolved to find out whether an update is needed.
The provider which is responsible for this host.
A list of all supported providers can be looked up by running ddns list-providers.
The username to authenticate against the provider's update service.
In most cases this will be the same username which can be used to login on your provider's web page.
The chosen password for the specified username.
An authentication token.
If your dynamic DNS provider supports token-based authentication, this method should be prefered. You do not need to specify the username if token-based authentication is used.
The domain that the host belongs to.
This is only used by providers that need the host and the domain separately (e.g. cloudflare.com, hetzner.com or namecheap.com), and only needs to be set if ddns cannot find out the domain itself (e.g. for host.example.co.uk). Hosts with only two parts (example.com) are the domain itself.
The TTL in seconds of records that are being created by providers that manage the records of a zone (e.g. cloudflare.com or hetzner.com), and by nsupdate. The default is 60, or the lowest TTL that the provider accepts (300 for dynadot.com, gandi.net, linode.com, luadns.com, name.com, scaleway.com and vultr.com, 600 for porkbun.com, and 3600 for namesilo.com).
Most providers authenticate with a username and a
password, or with a token. These
providers need something else, or call it differently:
token is an API token, which may edit the DNS
records of the zone.
token is an API key of the Hosting DNS API
(as prefix.secret).
token is the API key, and secret
the secret API key. The API has to be enabled for the domain.
username is the customer number,
token the API key, and password
the API password.
username is the token, and password
the secret of the API credentials.
username is the account name (e.g. S123456), and
password an API key.
password is the DonDNS key.
username and password are the
ones of the router, and not the ones to log in.
The hostname is the username, so that only the
password (or for nsupdate.info the
secret) is needed.
token is the DynDNS update hash.
username is the email address of the account, and
password an API key. API access has to be enabled
in the settings of the account.
username is the key, and password
the secret of an API key, which may edit the records of the host.
username is the username of the account, and
token an API token.
password is the DDNS password, which is created
when Dynamic DNS is enabled for the domain (and not the password
of the account).
token is the key of the dynamic record of the host.
The nsupdate provider sends updates to any DNS server
that accepts dynamic updates (RFC 2136), like BIND, Knot DNS or PowerDNS,
with the nsupdate utility. It knows these settings:
The server that the updates are sent to. By default, nsupdate finds out the primary server of the zone.
The zone of the host, if nsupdate cannot find it out itself.
The name and the secret of the TSIG key that signs the updates.
The TTL of the records in seconds (default: 60).
Example 1. For providers which use username and password for client authentication
| [somehost.provider.com] |
| provider = provider.com |
| username = username |
| password = password |
Example 2. For providers which supports token-based authentication
| [anotherhost.provider.com] |
| provider = provider.com |
| token = token |
Example 3. For a DNS server that accepts updates sent by nsupdate
| [host.example.org] |
| provider = nsupdate |
| server = ns1.example.org |
| key = host.example.org |
| secret = base64-encoded-secret |