NSSYNC
	DNS Zone Files Maintenance Utility	Sergey Poznyakoff

4 Nssync Configuration

4.1 General Settings

These settings modify the behavior of nssync as a whole.

Configuration: pidfile file

At startup, check if file already exists and is owned by an existing process. Exit if so. Use this statement to avoid accidentally running two copies of nssync simultaneously.

Configuration: tempdir dir

Sets the name for the temporary directory. This is a directory where nssync creates temporary zone files. The argument must point to an existing directory.

Configuration: check-ns bool

If set to true, nssync will check the list of NS servers prior to creating a zone file. The file will be created only if IPv4 address of one of the servers matches one of the IP addresses of the host on which nssync is run.

Configuration: named-conf file

Defines the full pathname of the named configuration file. Default is /etc/named.conf.

Configuration: bind-include-path list

Sets include search path for include directives found in BIND configuration. The argument is either a single directory or a list of directories (see list).

Configuration: zonefile-pattern pat

Defines the pattern for zone file names. The name of each zone file is created by expanding variable references in the pat argument. The following variable references are defined:

$zone

${zone}

Name of the zone, without the trailing dot.

$synctag

${synctag}

Zone synchronization tag (see Synchronization Block).

Both notations (with and without braces) are equivalent. The notation with curly braces should be used if the reference is immediately followed by a letter.

The default zone file pattern is ‘$zone.$synctag’.

Configuration: zone-conf pat

Defines the pattern for zone configuration file, i.e. a file containing zone statements.

The handling of pat is similar to that in zonefile-pattern, except that only the ‘$synctag’ reference is defined.

Configuration: compare-command cmd

Defines a command to be used for comparing two zone files. The cmd must be a command taking two files as its arguments and returning 0 if they are the same or non-zero if they differ. Nssync uses this command to determine whether a particular zone has changed. The following variable references are expanded in cmd:

$oldfile

${oldfile}

Old zone file.

$newfile

${newfile}

New zone file.

The default compare-command value is:

cmp $oldfile $newfile > /dev/null

Configuration: reload-command cmd

Defines a command to reload the nameserver. The default is ‘/usr/sbin/rndc reload’.

4.2 SQL Access

The following statements define the database server and the database to use:

Configuration: host hostname[:port-or-socket]

Defines the SQL server IP and port. The hostname can be either the server IP address or its hostname. The port-or-socket part, if supplied, can be either the number of TCP port to use instead of the default 3306 or the full pathname of the UNIX socket. In the latter case hostname is effectively ignored.

Configuration: database name

Sets the database name.

Configuration: ssl-ca file

Defines the name of the Certificate Authority (CA) file.

There are two ways to supply database access credentials. The simplest one is by using user and password statements:

Configuration: user name

Sets SQL user name.

Configuration: password arg

Sets SQL user password.

The drawback of this approach is that the password appears in plaintext, which means the permissions of the nssync.conf file must be tightened so as to avoid its compromise.

The following two statements provide an alternative, more safe and flexible way of setting access credentials:

Configuration: sql-config-file file

Read MySQL configuration from the option file file. See option files, for a description of MySQL option file format.

Configuration: sql-config-group name

Read the named group from the SQL configuration file.

To illustrate their use, suppose your nssync.conf file contains the following:

sql-config-file /etc/nssync.my;
sql-config-group nssync;

The the /etc/nssync.my will contain the actual SQL access configuration, which can look as in the example below:

[nssync]
socket = /var/db/mysql.sock
database = dns 
user = root
pass = guessme

Configuration: slave-status-file file

Use this statement if nssync reads data from a slave database. It allows you to avoid recreating zone files if the database information has not changed since the previous run.

If this statement is present, nssync will save the state of the SQL slave in file. Upon startup, it will read these data and compare them with the current state. If they are the same, it will exit immediately.

4.3 Synchronization Block

A synchronization block defines a set of zones to be synchronized from the database and configures SQL statements which return the zone data. This set is identified by synchronization tag, supplied as the argument to the sync statement:

# Define a synchronization block.
sync tag {
  # zone configuration file
  zone-conf pat;
  # pattern for new zone file names
  zonefile-pattern pat;
  # add these statements to each generated zone file
  add-statements text;
  # a query for retrieving SOA records
  soa-query string;
  # a query for retrieving NS and similar records
  ns-query string;
  # a query for retrieving the rest of RRs
  rr-query string;
  # a query for retrieving RRs from reverse delegation zones
  rev-rr-query string;
}

Statements within the sync block configure the zones:

Configuration: zone-conf pat

Defines the pattern for the name of zone configuration file for zones in this synchronization block. If not supplied, the global zone-conf statement will be used instead (see zone-conf).

Configuration: zonefile-pattern pat

Defines the pattern for zone file names. If not supplied, the global zonefile-pattern statement will be used instead (see zonefile-pattern).

Configuration: add-statements text

Append text to each generated zone statement. For example, the following can be used to redefine forwarders and query ACLs for zones in this synchronization block:

add-statements <<EOT
  forwarders { /* empty */ };
  allow-query { local-query-only; };
EOT;

Notice the use of the here-document construct.

The following statements define which zones pertain to this particular synchronization block:

Configuration: soa-query string

A query for retrieving SOA records.

Configuration: ns-query string

A query for retrieving NS and similar records. Use the ‘$zone’ reference for the zone name.

Configuration: rr-query string

A query for retrieving the rest of RRs. Use the ‘$zone’ reference for the zone name.

Configuration: rev-rr-query string

A query for retrieving RRs from reverse delegation zones. Use the ‘$zone’ reference for the zone name.

Here is an example of a working sync directive:

sync external {
  zone-conf "/var/namedb/nssync/zones.external";
  zonefile-pattern "/var/namedb/external/db.${zone}";
  
  soa-query    "select zone, ttl, type, data, resp_person, "
               "serial, refresh, retry, expire, minimum "
               "from dns_soa where type='SOA' "
               "and view='external' order by zone";
               
  ns-query     "select ttl, type, data "
               "from dns_soa where zone='$zone' "
               "and type<>'SOA' and view='external'";
               
  rr-query     "select host, ttl, type, mx_priority, "
               "case when type='TXT' then "
               "concat('\"', data, '\"') "
               "else data end "
               "from dns_records "
               "where zone='$zone' and view='external' "
               "order by 1";
               
  rev-rr-query "select host, ttl, type, mx_priority, "
               "case when type='TXT' then "
               "concat('\"', data, '\"') "
               "else data end "
               "from dns_records "
               "where zone='$zone' and view='external' "
               "order by cast(host as unsigned)";
}