DNSCHECK-DISPATCHER(1)

NAME
dnscheck-dispatcher - daemon program to run tests from a database queue

  SYNOPSIS
    dnscheck-dispatcher [--debug]

  DESCRIPTION
This daemon puts itself into the background (unless the --debug flag is given) and repeatedly queries the table "queue" in the configured database for domains to test. When it gets one, it spawns a new process to run the tests. If there are no domains to check, or if the configured maximum number of active child processes has been reached, it sleeps 0.25 seconds and then tries again. It keeps doing this until it is terminated by a SIGTERM. At that point, it will wait until all children have died and cleanups been performed before it removes its PID file and then exits.

Undelegated tests

In order to run undelegated tests, extra data can be put in the "fake_parent_glue" field in the queue table in the database. This data needs to be formatted in a particular way in order to be useful. Overall, it consists of a number of entries separated by whitespace. Each entry represents either one NS record or one DS record.

NS record entries are simple. They consist of either a single name (in which case the corresponding IP number(s) will be looked up in the live DNS tree), or a name followed by a slash (/) and an IP address. For example, an entry might look like "ns.example.org/192.168.2.2" (and give an error message during testing for being in a reserved IP range).

DS records are a bit more complicated. They should start with the exact string "ds:/" in order to mark them as not NS records. The rest of the record should be a DS record in BIND zone file format, but with all whitespace replaced with underscores (_). The dispatcher will replace back the underscores with spaces, and then try to create a Net::DNS::RR::DS object from the resulting string. If that fails, it will currently die.

  OPTIONS

--debug
    Prevents the daemon from going into the background and duplicates log information to standard output (it still goes to syslog as well).

CONFIGURATION
dnscheck-dispatcher shares configuration files with the DNSCheck perl modules. Or, to be more precise, it creates such an object and then queries its configuration object for its configuration information. It also uses the DNSCheck object to get its database connection.

There are two keys in the configuration YAML files that are of interest for the dispatcher. The first one is "syslog". It has the subkeys "ident", which specifies the name the daemon will use when talking to syslogd, and "facility", which specifies the syslog facility to use.

The second one is "daemon". It has the subkeys "pidfile", "errorlog", "maxchild", "user", "group" and "savelevel". They specify, in order, the file where the daemon will write its PID after it has detached, the file it will redirect its standard error to, the maximum number of concurrent child processes it may have and the minumum log level to save to the database. Make sure to set the pathnames to values where the user the daemon is running under has write permission, since it will terminated if they are specified but can't be written to. Additionally, running with a maxchild value of n means that at least n+1 simultaneous connections to the database will be opened. Make sure that the database can actually handle that, or everything will die with more or less understandable error messages. The "user" and "group" keys specify the user and group that the dispatcher will change too after opening the pid and errorlog files, if it is started as the root user. Note that if only the root user can open the PID and error files, restarting the dispatcher by sending it a HUP signal will fail.

If everything works as intended nothing should ever be written to the errorlog. All normal log outout goes to syslog (and, with the debug flag, standard output).