pydyndns 1.2.1

Sends dynamic DNS updates to a DNS server.

Overview

PyDynDNS sends dynamic DNS updates to a DNS server. PyDynDNS’s principles are as follows:

• PyDynDNS allows a computer to register its own address on a DNS server. PyDynDNS will not help a DHCP server register all its clients. PyDynDNS is useful for situations where the DHCP server in use is not able to issue DNS updates.
• PyDynDNS uses the DNS protocol to perform dynamic updates. Many commercial dynamic DNS providers use HTTP-based update interfaces instead. PyDynDNS does not support those interfaces.
• PyDynDNS will update A and AAAA records only.
• PyDynDNS is small and lightweight and is intended to be run from a Cron job or DHCP client address-change callback. It is perfectly reasonable to run PyDynDNS every minute or so. It will only send updates when changes have been made.

Dependencies

PyDynDNS requires the following packages, all of which are available via pip:

• dnspython
• ifaddr

Usage

PyDynDNS can be invoked from the command line. It uses standard command-line option parsing and understand the -h and --help options to display usage information.

The name to register is taken from the computer’s current hostname. The addresses to register is taken from one or more network interfaces, which are passed on the command line. The server to talk to is taken from the SOA record covering the computer’s hostname. Each update deletes all records associated with the hostname then registers a new A or AAAA record for each of the host’s IP addresses.

A pair of Windows Task Scheduler job files are provided in the examples/tasksched subdirectory. These assume PyDynDNS has been installed at C:\Python3.7\Bin\PyDynDNS. The Normal.xml job runs every ten minutes, starting ten minutes after system boot, to keep the DNS names up to date as IP addresses change. The Force.xml job runs once at boot with the -f option, to ensure that updates other operating systems may have made are flushed out and the system’s current address is registered properly.

Configuration File

PyDynDNS uses a JSON-formatted configuration file. The top-level configuration file must be a JSON object with the following keys:

• cache (required, string or boolean): The name of the cache file, true to use the platform-default cache file, or false to not use a cache file. PyDynDNS writes into this file each time it performs an update. When invoked, it first checks the cache file to decide whether an update needs to be performed; if no data has changed compared to the cache file, the update is skipped. On a single-OS computer, this file can be stored anywhere. On a multi-OS computer, this file should probably be stored somewhere that is destroyed on reboot, so that any registration changes made while other OSes are booted will be overwritten. If omitted, no cache file is used and every invocation results in an update being sent.
• ipv4 (required, boolean): Whether or not to register IPv4 (A) records.
• ipv6 (required, object): Configuration regarding IPv6; see below.
• logging (required, object): A logging configuration, as described by the Python logging configuration dictionary schema at https://docs.python.org/3/library/logging.config.html#logging-config-dictschema. Note that a logger named pydyndns is used for all output.
• ttl (required, number): The time to live for created DNS records, in seconds.
• tsig (optional, object): Configuration regarding TSIG authentication; see below.

ipv6 object

The ipv6 object contains the following keys:

• enable (required, boolean): Whether or not to register IPv6 (AAAA) records.
• teredo (required, boolean): Whether to include Teredo addresses.

tsig object

The tsig object, if present, contains the following keys:

• algorithm (required, string): The name of the TSIG algorithm to use, one of hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, or hmac-sha512.
• key (required, string): The base-64-encoded shared secret.
• keyname (required, string): The name of the key, which must match the key name the server is expecting.

Example logger object for UNIX syslog dæmon output

{
	"version": 1,
	"formatters": {
		"syslog": {
			"format": "%(name)s: %(message)s"
		}
	},
	"handlers": {
		"syslog": {
			"class": "logging.handlers.SysLogHandler",
			"address": "/dev/log",
			"facility": "local0",
			"formatter": "syslog"
		}
	},
	"root": {
		"level": "WARNING",
		"handlers": ["syslog"]
	}
}

Example logger object for Windows event logger output

This requires Python Win32 extensions to be installed (python -m pip install pypiwin32).

If you are running under a low-privilege Windows account (e.g. Local Service), you will be able to write messages to the event log, but not register new event sources. Running PyDynDNS once as an adminstrator with the NTEventLogHandler configured will register the event source, after which subsequent invocations can be made from the low-privilege account.

{
	"version": 1,
	"formatters": {
		"eventlog": {
			"format": "%(message)s"
		}
	},
	"handlers": {
		"eventlog": {
			"class": "logging.handlers.NTEventLogHandler",
			"appname": "PyDynDNS",
			"formatter": "eventlog"
		}
	},
	"root": {
		"level": "WARNING",
		"handlers": ["eventlog"]
	}
}