% WTDNSD(8) - WtDNS daemon
% Jonas Eckerman <jonas@truls.org>
% 2012-10-16 15:36:01 UTC (v0.013)

# NAME

wtdnsd - WtDNS daemon

# SYNOPSIS

	wtdnsd [options] ...

# DESCRIPTION

WtDNSd is a master DNS server working with zone records stored on a
one-type-per-file basis. This makes it simple to configure, easy to update, 
and efficient for systems with very frequent updates.

WtDNSd is _not_ a caching or recursive DNS server and has no built in
resolver.

For more information about the resource record store, see wtdns(8).

# OPTIONS

-p <port>
:	Listen port for all following interfaces.
	Default is 53.

-i <ip-address>
:	The IP address you want the WtDNSd to listen on.
	Multiple interfaces can be specified.
	If omitted, it defaults to "0.0.0.0" meaning _all_ interfaces.

-u <user>
:	Change identity to this user just before starting to serve. This is
	done after opening logs and ports, creating PID, and forking.
	Default is user _nobody_ if started by root and no change otherwise.

-g <group>
:	Change identity to this user just before starting to serve. This is
	done after opening logs and ports, creating PID, and forking.
	Default is group _nogroup_ if started by root and no change otherwise.

-d
:	Fork twice into the background (to run as a daemon process); otherwise
	WtDNSd runs in the foreground.

-pf <filename>
:	Write process ID to this file. This is done after the forks when _-d_
	is used. Note that WtDNSd does not lock or check the file at start,
	and does not delete it when exiting.

-cs
:	Create control sockets on a randomized port on localhost, generate a
	random token domain name used for control queries, and write both of
	them to a file, readable only by owner, in the resource data
	directory.

-oh
:	Omit the hash mark '#' from the hashes. This makes WtDNS use the same
	hash directories as the original SheerDNS.
	Remember to use this option with **wtdnshash** if you use it with
	**wtdnsd**.

-nh
:	Omit the hash (two character hex) part of the path when looking up
	queries. This is useful for smaller sites.
	Do _not_ use **wtdnshash** to create directories when using this option.

-dd <directory>
:	The directory where WtDNS resource records are stored.

-ttl <time>
:	The time-to-live field to be set on normal responses.
	Records that are likely to be fixed (not dynamic) are given a 3-day
	ttl. Examples are the IP address of the NS record, and the CNAME, MX,
	NS, and SOA records. Other records are given the ttl specified in
	this option. The default is one day.

-attl <time>
:	The time-to-live field to be set on authority records (SOA and NS) in
	responses. Default is three days.

-ds
:	Use DNSSEC, wich requires some extra processing and adds some extra
	data to packets whenever a client requests secure data.

-ad
:	Assure clients using DNSSEC that the served data is authentic (except
	for names in the base dynamic dns domain).

-ddad
:	Assure clients using DNSSEC that the served data is authentic for
	names in the base dynamic dns domain as well.

-ddttl <time>
:	The time-to-live field to be set on responses for subdomains of the
	base dynamic domain. For a frequently updated dynamic domain a TTL as
	low as 10 seconds might make sense here.
	Default is 10 minutes.

-ddto
:	Honour timeouts configured for **purge** and **fallback** for dynamic
	domains. Dynamic records older than **purge** will not be found, while
	dynamic records older than **fallback** will be replaced with fallback
	records if such are defined.
	When using this, regularly running **wtdns-maintain** is not needed.

-ddug
:	Only honour timeouts for dynamic records where the record files user
	or group matches the one set in the configuration file.
	Note: **wtdnsd** _never_ honours timeouts for records with user or
	group 0.

-cf <filename>
:	Read specified configuration file.

-ls
:	Log to syslog (using the daemon facility).

-lf <filename>
:	Log to file. If using this together with _-ls_, less information will
	be logged to syslog.

-ld <filename>
:	Log debug information to a separate file. If using this together with
	_-ls_ and/or _-lf_, less information will be logged to syslog and the
	other file.

-ll <level>
:	An integer value specifying how much to log. Level 2 means only
	critical errors, while levels 7 and above are for debugging. Default
	is 5.
-v
:	Increase log level by 1.

-V
:	Print WtDNSd name and version, then exit.

-h
:	Print usage information, then exit.

# CONFIGURATION

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.
	**wtdnsd** will only honour **purge** and **fallback** times for
	records for subdomains of this domain.

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.
	Do _not_ use wtdnshash to create directories when this is turned
	off.

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

user = user
:	User to match for dynamic resource records file owner.

group = group
:	Group to match for dynamic resource records file group.

fallback = time
:	Dynamic records older than this time will be replaced with fallback
	values (if avalilable).

purge = time
:	Dynamic records older than this time will not be found.

# Macros

A TXT record (one line in a TXT record file) can be replaced with a macro. For
this to be done the line must consist only and totally of the macro, wich has
the following syntax:

	%%wtdns:macrotag%%

where "macrotag" is the one of the macros listed below.

connections

:	Connection counters from the running instance of WtDNSd, including
	the following fields:

	cTot
	:	Total number of connections (one received UDP packet counts as
		one connection)

	cUDP
	:	Number of UDP packets received.

	cTCP
	:	Number of TCP connections accepted.

queries

:	Counters for the number of incoming messages (wether they actually
	contains a valid query or not), including the following fields:

	mTot
	:	Total number of messages (packets) received.

	mUDP
	:	Number of messages received with UDP.

	mTCP
	:	Number of messages received over TCP.

	mOPT
	:	Number of messages received with an EDNS OPT pseudo RR.

	mDO
	:	Number of messages received with the DNSSEC OK bit set.

	mBad
	:	Number of bad or broken messages received.

responses

:	Counters for the number of sent responses, including the following
	fields:

	rTot
	:	Total number of messages sent.

	rUDP
	:	Number of messages sent with UDP.

	rTCP
	:	Number of messages sent over TCP.

	rOPT
	:	Number of messages sent with an EDNS OPT pseudo RR.

	rNon
	:	Number of non-error responses sent with NXDOMAIN or no
		answers.

	rErr
	:	Number of error reponses sent.

	rBig
	:	Number of answers that had to be truncated.

querytypes

:	Counters for resource record types queried for.

responsetypes

:	Counters for resource record types included in responses.

sizes

:	Average size of different messages (not including network overhead),
	including the following fields:

	ziMsg
	:	Average size of received messages.

	ziUDP
	:	Average size of messages received with UDP.

	ziTCP
	:	Average size of messages received over TCP.

	ziOPT
	:	Average size of received messages with an EDNS OPT pseudo RR.

	zmOPT
	:	Average UDP payload size advertized in EDNS OPT pseudo RRs.

	zoMsg
	:	Average size of sent messages.

	zoUDP
	:	Average size of messages sent with UDP.

	zoTCP
	:	Average size of messages sent over TCP.

	zoOPT
	:	Average size of sent messages with an EDNS OPT pseudo RR.

time

:	Time at which **wtdnsd** was started and how long ago that was.

version

:	**wtdnsd** version and build date.

There could be an example TXT record file with macros installed to your WtDNS
documentations var directory.

# FILES

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

/var/lib/wtdns/:control
:	This file contains the information needed to connect to the control
	sockets.

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