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.

Implementations must use the requests library for all HTTP requests. This should be done by calling methods of the session variable in this module, rather than calling the global requests functions. This makes sure all requests have the correct user agent.

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.

Implementations must use the requests library for all HTTP requests. This should be done by calling methods of the session variable in this module, rather than calling the global requests functions. This makes sure all requests have the correct user agent.

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.

__str__()

If possible, implement this function to provide more information about the service, such as the hostname. The recommended format is ClassName [hostname, etc]. Use self.__class__.__name__ for the class name rather than hard-coding it.

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.