% WTDNS-FROMLOG(8) - WtDNS dynamic DNS updater
% Jonas Eckerman <jonas@truls.org>
% 2012-10-16 15:09:39 UTC (v0.003)

# NAME

wtdns-fromlog - WtDNS dynamic DNS updater

# SYNOPSIS

	(something that outputs log lines) | wtdns-fromlog

# DESCRIPTION

The **wtdns-fromlog** reads formatted log lines on standard input, and updates
resource records used by WtDNSd when the lines match it's criteria.

When used with a custom log piped from a HTTP daemon this makes a simple and
effective HTTP/HTTPS based dynamic DNS update system. Since **wtdns-fromlog**
is processing log lines as they come, allready loaded, this is more resource
friendly than CGI and requires no modules for active web content.

## Authentication

This updater has no metods for authenticating the clients. This must be done
buy whatever creates the log lines that **wtdns-fromlog** reads.

# CONFIGURATION

The configuration file is automatically reloaded when it changes, so whatever
runs **wtdns-fromlog** and pipes data to it does not need to be reloaded when
the configuration is updated.

The following global options are recognized in the configuration file.

datadir = directory
:	The directory where WtDNS resource records are stored.
	Default is "/var/lib/wtdns".

domain = domainname
:	The base domain for dynamic DNS.
	This domain will be appended to any host names that does not contain
	a '.' when parsing reading ACLs and parsing requests.

hashing = yes/no
:	Wether to use the hash part in the domain name paths or not.
	For small sites turning of hashing might make things easier for the
	administrator. Default is to use hashing.

oldhash = yes/no
:	If on, WtDNS will omit the '#' i front of the hash, wich makes it
	compatible with the oriinal SheerDNS software.

hasher = command
:	The command to use when getting a hash for the host domain directory.
	Default is "/usr/bin/wtdnshash".

user = user
:	If the program is started as root it will change into this user before
	starting it's work.

group = group
:	If the program is started as root it will change into this group before
	starting it's work.

groups ( grouplist )
:	If the program is started as root it will change supplemental groups
	into this list before starting it's work.

fallback = time
:	Log lines older than this time will not be used.

purge = time
:	Log lines older than this time will not be used.

## Access Control Sections

Access controls are specified with section named like this:

	[acl:accountname]

where accountname is matched with the 'u' field (autheticated user) of the log
lines.

The following options are available in ACL sections:

host = hostname
:	A host name this account may update. If it is a fully qualified domain
	name, that name does not have to be in the base dynamic DNS domain. If
	it is outside the base domain, it will not be checked by the
	**wtdns-maintain** utility.
	Multiple host names can be specified by using multiple host
	statements.

ignore = yes/no
:	If this is on, any "myip" fields in the request from this account is
	ignored, otherwise it is checked against the 'i' field of the log
	line.

trust = yes/no
:	If this is on, and "ignore" is off, any "myip" fields in the requests
	for this account is trusted and used to update resource records even
	if they mismatch with the 'i' field in the log line.

parameters = trust, distrust, ignore, check
:	This can be used to set the trust and ignore parameters on one line.

# LOG FORMAT

**wtdns-fromlog** reads lines with fields separated by '|' (pipes). Each
field is of the format

	I=value

where I is an identifer. The following identifiers are recognized and used:

t=timestamp
:	Unix timespamp (Seconds since epoch).

T=datetime
:	Formatted date and time. **wtdns-fromlog** understands a bunch of
	common time formats.

i=ip-address
:	The clients IP address. This can be used to update the resource
	records.

c=code
:	The HTTP result code for the request. Unless this is 200 the line will
	not be used.

u=username
:	The authenticated user. Unless this is present and matches an existing
	ACL section, the line will not be used.

f=filepath
:	The path to the file the HTTP daemon served to the client.
	Unless this is present and indicating success the line will not be
	used. When checking the filename for success, **wtdns-fromlog** checks
	that the name, not including path, prefix and alphabetical extension
	is "ok", "good" or "received".

q=querystring
:	The query string from the request. This must contain the hostname to
	be updated, and may contain named options as well. Query parameters
	are separated by '&' or ';'. Parameters of the form "option=value"
	are parsed as named options, anything else is parsed as hostnames.
	Multiple host names can be specified, either as separate parameters,
	or separated by anything not in '.', '-', '_', a-z, A-Z or 0-9. The
	named option "myip" can be used to update resource records.

r=request-url
:	If the query string is missing or empty, and the next to last
	component of the request uri ends in a-z or A-Z, the last
	component will be used instead of the query string, using the same
	parsing rules.

# EXAMPLE

A request to update might look something like this:

	http://ddns.example.net/update?dynamichost;myip=192.0.2.99
	http://ddns.example.net/update?dynamichost1+dynamichost2;myip=192.0.2.33
	http://ddns.example.net/update?dynamichost.ddns.example.net
	http://ddns.example.net/update/dynamichost&myip=192.0.2.66

Logging directives for Apache httpd might look like this:

	LogFormat "t=%{%s}t|T=%{%Y-%m-%d %H:%M:%S}t|s=%A|p=%p|c=%>s|i=%a|u=%u|f=%f|r=%U|q=%q|a=%{User-Agent}i" DDNSUpdate
        CustomLog "||/usr/local/bin/wtdns-fromlog" DDNSUpdate

An alias in apache that satisfies common dynamic DNS clients and the updater
might look like this:

	AliasMatch (?i)^/?ddns-?update(?:[^a-z0-9]|$) /var/www/ddns-ok.txt

where the ddns-ok.txt contains this:

	good

# FILES

/var/lib/wtdns
:	All resource records are stored in this directory.

/etc/wtdns/wtdns.ini
:	The global configuration file.

/var/lib/wtdns/:www/ddns-ok.txt
:	A file suitable to return to dynamic DNS clients to indicate a
	succefull reception of the update request.
