Welcome to dnsupdate’s documentation!¶

Configuring dnsupdate¶

Configuration File¶

dnsupdate is configured using a single YAML configuration file. This file can specified on the command line, or placed at either ~/.config/dnsupdate.conf or /etc/dnsupdate.conf.

The available options are documented below.

`address_provider`¶

Controls how dnsupdate obtains IP addresses. If this option is not specified, a web service is used. When specified at the root of the file, this option applies to all DNS services.

Internally, address providers are Python classes which are initialized using this configuration option.

address_provider:
    type: ClassName;
    args:
        arg1: value1;
        arg2: value2;

type specifies the name of the class, while args is a list of constructor arguments.

Optionally, a shorthand notation can be used, which allows you to directly call the class’s constructor:

address_provider: ClassName(value1, value2)

In this case, the option value is simply passed to eval(), so it is possible to evaluate arbitrary Python code.

Address providers can be specified separately for IPv4 and IPv6 in this manner:

address_provider:
    ipv4:
        type: ...
        args:
            ...
    ipv6:
        type: ...
        args:
            ...

If only one of the two protocols is configured, the other protocol is disabled (unless a specific service overrides this option).

Default: Web()

`dns_services`¶

A list of services to update. Each service is represented internally as a Python class. The arguments specified in the configuration are directly passed to the class’s constructor.

It is also possible to override the global address provider for a specific entry, using the same format as the global address_provider option. If only one address provider protocol (IPv4 or IPv6) is specified, the other is inherited from the global configuration. It is possible to disable a protocol that was configured globally by assigning it the value None. See examples/provider_override.conf.

dns_services:
    - type: ServiceClassName1
      address_provider: &lt;see above&gt;
      args:
          arg1: value1
          arg2: value2
    - type: ServiceClassName2
      args:
          arg1: value1
          arg2: value2
    ...

The shorthand constructor notation can also be used to initialize a DNS service.

`cache_file`¶

Path to the file where dnsupdate will store information about the configured DNS services, such as their addresses and whether they are enabled. The specified file must be writable by dnsupdate.

Default: ~/.cache/dnsupdate.cache

Address Providers¶

class Web(ipv4_url='https://ipv4.icanhazip.com/', ipv6_url='https://ipv6.icanhazip.com/')¶

Retrieves addresses from a web service (by default: icanhazip). This provider expects the response to contain only the address in plain text (no HTML).

Parameters:	ipv4_url – URL of the service that retrieves an IPv4 address ipv6_url – URL of the service that retrieves an IPv6 address

class Local(interface)¶

Retrieves addresses from a local network interface. If you are behind NAT (which is often the case if you are using dynamic DNS), this provider will return your internal IPv4 address. In this case, you will want to use a different provider for IPv4.

Parameters:	interface – name of the interface to use

class ComcastRouter(ip, username='admin', password='password')¶

Scrapes the external IPv4 address from a Comcast/XFINITY router. This address provider does not support IPv6 because it doesn’t usually make sense to submit the router’s IPv6 address to a dynamic DNS service.

This has been tested with an Arris TG1682G, but may work with other routers using Comcast’s firmware.

Parameters:	ip – internal IP address of the router username – username for the web interface (usually ‘admin’) password – password for the web interface (router default is ‘password’)

DNS Services¶

class StandardService(service_ipv4, service_ipv6, username, password, hostname)¶

Updates a DNS service that uses the defacto standard protocol that has been defined by Dyn. All the standard return codes are handled. Client configuration errors will cause the service to be disabled.

Parameters:

service_ipv4 – domain name of the IPv4 update service
service_ipv6 – domain name of the IPv6 update service
username – service username (some services use the your (sub)domain name as the username)
password – service password (sometimes this is a unique password for a specific (sub)domain rather than your actual password)
hostname – fully qualified domain name to update

class FreeDNS(ipv4_key, ipv6_key=None)¶

Updates a domain on FreeDNS using the version 2 interface. This API uses a single key for each entry (separate ones for IPv4 and IPv6) instead of separately passing the domain, username and password. The keys are the last part of the given update URL, not including the trailing slash.

For example, the update key for the URL http://sync.afraid.org/u/VWZIcQnBScVv8yv8DhJxDbnt/ is VWZIcQnBScVv8yv8DhJxDbnt

Parameters:	ipv4_key – update key for IPv4 ipv6_key – update key for IPv6

class NSUpdate(hostname, secret_key)¶

Updates a domain on nsupdate.info. nsupdate.info uses the Dyn protocol.

Parameters:	hostname – fqdn to update secret_key – update key

class StaticURL(ipv4_url, ipv6_url=None)¶

Updates addresses by sending an HTTP GET request to statically configured URLs. When using this type of service, the remote server will automatically detect your IP and therefore the address provided by the configured address provider will not be used. In most cases, the result will be the same as if the Web provider had been used.

Parameters:	ipv4_url – URL used to update the IPv4 address ipv6_url – URL used to update the IPv6 address

Using dnsupdate¶

Dynamic DNS update client

usage: dnsupdate [-h] [-f] [config]

Positional arguments:

config

the config file to use

Options:

`-f, --force-update`
	force an update to occur even if the address has not changed or a service has been disabled

dnsupdate can be run as a cron job or with any other scheduler. A systemd service file (for use with a systemd timer) is included in the root of the repository, but it will have to be manually installed unless you are using the Arch Linux AUR package.

On startup, dnsupdate checks if the addresses for any of the configured services have changed, and if so it will attempt to update them. If an update fails and the service reports that the problem was due to client misconfiguration (such as an incorrect password or hostname), the service will be disabled until the config file is edited.

The -f flag can be used to force the update of all services, even if no addresses have changed or a service is disabled. This flag should not be used as part of the automatic update process because too many update attempts that result in no change will cause some services to ban you.

Extending dnsupdate¶

dnsupdate is designed to make it easy to add new address providers and DNS services.

If you add a new address provider, DNS service or any other feature that might be useful to others, feel free to submit a pull request on GitHub.

Adding an address provider¶

To add support for a new address provider, add a new subclass of AddressProvider to the the module, and it will become available to use in a configuration file.

class AddressProvider¶

Provides a standard interface for retrieving IP addresses. Any information needed to obtain the addresses (such as authentication information) should be specified in the constructor. Constructor arguments will become options that can be specified in the config file.

ipv4()¶

Return an IPv4 address to assign to a dynamic DNS domain. Only implement this method if your address provider supports IPv4.

Return type:	`ipaddress.IPv4Address`

ipv6()¶

Return an IPv6 address to assign to a dynamic DNS domain. Only implement this method if your address provider supports IPv6.

Return type:	`ipaddress.IPv6Address`

Adding a DNS service¶

Likewise, a new DNS service can be created by subclassing DNSService.

class DNSService¶

Provides a standard interface for updating dynamic DNS services. Any information needed to perform an update (such as the domain name and password) should be specified in the constructor. Constructor arguments will become options that can be specified in the config file.

If possible, implementations should send the address parameter of the update methods to the service, rather than letting the service automatically detect the client’s address. This makes it possible (with a custom address provider) for a client to point a domain at another device.

To indicate errors during the update process, implementations of the update methods can raise one of three special exceptions: UpdateException, UpdateServiceException or UpdateClientException. See the documentation for these classes for information on when they should be raised.

update_ipv4(address)¶

Update the IPv4 address of a dynamic DNS domain.

Parameters:	address (`ipaddress.IPv4Address`) – the new IPv4 address

update_ipv6(address)¶

Update the IPv6 address of a dynamic DNS domain.

Parameters:	address (`ipaddress.IPv6Address`) – the new IPv6 address

Update exceptions¶

class UpdateException¶: Signals that an error has occurred while attempting to perform an address update, but the client does not know whether it was caused by a misconfiguration or a problem with the service. If the reason for the error is known, one of this exception’s subclasses should be used instead.

class UpdateClientException¶: Signals that an error has occurred as the result of a misconfiguration of the client. This exception should only be raised when there is very little chance that an error occurred due to a temporary problem with the DNS update service. The reason for this is that when this exception is thrown, the service that was being updated will be disabled until the user edits the configuration file.

class UpdateServiceException¶: Signals that an error has occurred on the DNS service’s server while attempting an update. In this case, an error will be printed, but the service will not be disabled.

Index