Updaters

Updaters are the parts of Ruddr that interface with your dynamic DNS provider. Different providers use different protocols and APIs, which correspond with the various updater types available.

Sample configurations are provided for some popular DDNS providers. However, if none of the built-in updaters below are compatible with your provider, you can write your own. (see Writing Your Own Updater).

Standard Updater

Type: standard

This updater is compatible with a wide variety of providers that mimic an API first introduced by Dyn (previously DynDNS, now owned by Oracle). Despite the updater’s name, the API is not officially standardized. However, it has effectively become a de facto standard. If your provider supports updates via a URL that looks like http[s]://<hostname>/nic/update?myip=<IP address> or http[s]://<username>:<password>@<hostname>/nic/update?myip=<IP address>, this is the updater to use.

Sample config for Dynu:

[updater.main]
type = standard
endpoint = https://api.dynu.com
username = <your-username>
password = <your-password>
hosts = foo.dynuddns.com/foo.dynuddns.com bar.dynuddns.com/::1a2b:3c3d
nameserver = ns1.dynu.com
ipv6_dialect = separate_no
min_retry_interval = 600

Sample config for NoIP:

[updater.main]
type = standard
endpoint = http://dynupdate.no-ip.com
username = <your-username>
password = <your-password>
hosts = foo.ddns.net/foo.ddns.net bar.ddns.net/::1a2b:3c3d
nameserver = ns1.no-ip.com
ipv6_dialect = combined
min_retry_interval = 1800

General sample config:

This config snippet shows all the options available for this updater. If your provider isn’t listed above, but does use an update URL that looks like http[s]://<hostname>/nic/update?myip=<IP address> or http[s]://<username>:<password>@<hostname>/nic/update?myip=<IP address>, there’s a good chance you can create a working config using these options.

[updater.main]
type = standard
endpoint = https://update.example.com
username = <your-username>
password = <your-password>
hosts = foo/foo.example.com bar/::1a2b:3c3d
#nameserver = ns.example.com
#ipv6_dialect = separate
#min_retry_interval = 300

Configuration options:

endpoint

The schema and hostname part of your provider’s update URL, that is, the part before /nic/update?.... Do not include a slash at the end and do not include a username or password.

username

The username to include with update requests

password

The password to include with update requests

hosts

A whitespace-separated list of hostnames to keep updated. Each entry must be in one of the following three formats:

<hostname>/- Ruddr requires an existing IPv6 address in order to do IPv6 updates, since it only changes the network prefix for IPv6 addresses. However, if you do not need IPv6 addresses, you can use this format, and the updater will ignore IPv6 addresses from the notifier.

<hostname>/<IPv6-address> For IPv6 updates, Ruddr will take the given address, replace its network prefix with the one from the notifier, and publish the resulting address.

<hostname>/<fqdn> For IPv6 updates, Ruddr will look up the given fully-qualified domain name to get an IPv6 address from an AAAA record. It will take that address, replace the network prefix with the one from the notifier, and publish the resulting address. This is the recommended format, since it will update the prefix of the address already in DNS.

nameserver

This option is used only if you used the <hostname>/<fqdn> format for any of the entries in hosts. It allows you to specify a specific nameserver to query. You can specify your provider’s nameserver here to ensure Ruddr gets the most up-to-date result directly from them. If not provided, your system’s default DNS server(s) will be used.

ipv6_dialect

The DynDNS API was originally designed for IPv4 only. As a result, different providers added IPv6 support in different ways. This option lets you specify how the updater should provide an IPv6 address to your provider. These are the possibilities:

separate provides IPv6 addresses using a separate myipv6 parameter in the URL. If only one address needs to be set (IPv4 or IPv6), the parameter for the other type of address will be omitted. This is the default.

separate_no is like separate, except if only one address can be set, no is sent in place of the other address.

combined provides both IP addresses together in the myip parameter, separated by a comma, e.g. myip=1.2.3.4,2001:0db8::4. If only one address needs to be set (IPv4 or IPv6), it will be sent in the myip parameter alone, without a comma.

min_retry_interval

The minimum number of seconds to wait between retries when an update fails. This minimum is used for the first retry, with an exponential backoff for subsequent retries. Some providers, especially free ones, have specific requirements for this.

Duck DNS Updater

Type: duckdns

This updater is for Duck DNS, the dynamic DNS service at duckdns.org. The API does not provide a way to obtain the current IP address, which Ruddr needs for IPv6 updates, so it uses DNS queries to the Duck DNS nameserver instead.

Sample config for Duck DNS (with defaults commented):

[updater.main]
type = duckdns
token = <duck-dns-token>
hosts = example1 example2
#nameserver = ns1.duckdns.org

Configuration options:

token

Your update token, found by logging into your account

hosts

A whitespace-separated list of hosts in your account to be updated. These should not include .duckdns.org.

nameserver

The DNS server to query for the current IPv6 address of each host. This should not need to be set, but can be if desired. Explicitly setting it to an empty value will use the system DNS resolver instead of a specific server.

FreeDNS Updater

Type: freedns

This updater is for FreeDNS, the dynamic DNS service at freedns.afraid.org.

Sample config for FreeDNS:

[updater.main]
type = freedns
username = <freedns-username>
password = <freedns-password>
fqdns = foo.example.com bar.example.com

Configuration options:

username

Your account’s username at freedns.afraid.org

password

Your account’s password at freedns.afraid.org

fqdns

A whitespace-separated list of domains or subdomains in your account whose IP address(es) should be updated.

Gandi Updater

Type: gandi

This updater uses Gandi’s LiveDNS API to update the A and AAAA records associated with a domain name. If your domain name is registered with Gandi and you use their DNS services (marketed as “LiveDNS”), this updater is a great choice for you.

Sample config for Gandi (with defaults commented):

[updater.main]
type = gandi
api_key = <your-api-key>
fqdns = example.com www.example.com
#endpoint = https://api.gandi.net/v5/livedns

Configuration options:

api_key

Your production LiveDNS API key. You can generate this by logging in to https://account.gandi.net/ and navigating to the “Security” section.

fqdns

A list of fully qualified domain names to update the A and AAAA records for. Multiple domain names should be separated by whitespace. These may be your root domains (e.g. example.com), subdomains (e.g. www.example.com), or any mixture of both.

endpoint

The API endpoint to use, that is, the base URL for the LiveDNS API. This should rarely need to be set explicitly, as it defaults to Gandi’s production LiveDNS API endpoint. However, if you wish to test in Gandi’s sandbox API environment, you can set this to https://api.sandbox.gandi.net/v5/livedns.

HE Updater

Type: he

This is a niche updater for those who use Hurricane Electric’s IPv6 tunnel broker service. The tunnel broker requires an up-to-date IPv4 address at all times, and this updater can be used to provide it. Since that is its only purpose, it ignores any IPv6 addresses supplied by a notifier.

Sample config for Hurricane Electric’s tunnel broker (with defaults commented):

[updater.main]
type = gandi
tunnel = <tunnel-id>
username = <username>
password = <password>
#url = https://ipv4.tunnelbroker.net/nic/update

Configuration options:

tunnel

Your Hurricane Electric tunnel ID

username

Your Hurricane Electric username

password

Your Hurricane Electric password

url

The URL to use for updates, if Hurricane Electric’s URL should not be used. The vast majority of users should not set this.