path: root/doc/nssync.8

.\" This file is part of Nssync. -*- nroff -*-
.\" Copyright (C) 2011, 2014 Sergey Poznyakoff
.\"
.\" Nssync is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" Nssync is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with Nssync.  If not, see <http://www.gnu.org/licenses/>.
.TH NSSYNC "8" "December 1, 2014" "NSSYNC" ""
.SH NAME
\fBnssync\fR \- A DNS Zone File Maintenance Utility

.SH SYNOPSIS
\fBnssync\fR [\-EVXdfhntx] [\-D \fISYMBOL[=VALUE\fR]] [\-I \fIDIR\fR]\
 [\-c \fIFILE\fR] [\-\-config\-file=\fIFILE\fR] [\-\-config\-help]\
 [\-\-debug] [\-\-debug\-lexer] [\-\-debug\-parser]\
 [\-\-define=\fISYMBOL\fR[=\fIVALUE\fR]] [\-\-dry\-run] [\-\-force]\
 [\-\-help] [\-\-include\-directory=\fIDIR\fR] [\-\-lint]\
 [\-\-no\-preprocessor] [\-\-preprocessor=\fICOMMAND\fR]\
 [\-\-usage] [\-\-version]
.SH WARNING
This manpage is a short description of the \fBnssync\fR utility.
For a detailed discussion, including examples of the configuration and
usage recommendation, refer to the \fBNssync User Manual\fR available in
Texinfo format.  To access it, run:

  \fBinfo nssync\fR

Should any discrepancies occur between this manpage and the
\fBNssync User Manual\fR, the later shall be considered the authoritative
source.
.SH DESCRIPTION
BIND, the most frequently used DNS server, normally keeps its zone
data in plain text files. This approach becomes inconvenient when the
number of zones grows beyond a certain limit. When this happens, the
obvious solution is to move all data to a database and make named read
it from there, and the recent versions of BIND are able to do so by
using dynamically loadable zones (DLZ).  However, DLZ has problems of
its own, one of them being that it is unable to propagate glue records. 

The nssync utility provides an alternative solution, which makes it
possible to keep your zone data in an SQL database without using DLZ
and with glue records working.
 
It does so by periodically polling the database to determine which
data have recently changed and converting the database into BIND zone
files.

The \fBnssync\fR utility is normally started periodically from
crontab.  Upon startup it reads its configuration file, which supplies
the necessary program settings.  Then, if the settings require so, it
verifies that no other copy of the \fBnssync\fR is already
running.  Further on, it parses the \fBnamed\fR configuration file
\fBnamed.conf\fR to determine several settings needed for its further
operation, in particular, the value of the \fBdirectory\fR statement
in the \fBoptions\fR block.

Once these preliminary operations are over, \fBnssync\fR starts
its main task.  Its configuration file defines, among other data, one
or more synchronization blocks.  Each such block defines SQL
statements which return information about DNS zones as well as the
location of \fBnamed\fR configuration file where the \fBzone\fR
statements for these zones are to be stored (it is supposed that this
file is included somewhere in the main \fBnamed.conf\fR file).  For
each synchronization block, the utility retrieves the zone data from
the database and formats them into separate zone files.  Each of these
files is then compared to an already existing one (locations of the
zone files are defined in the synchronization block they pertain to).
If the files differ, new zone file replaces the old one and a flag is
set indicating that the \fBnamed\fR daemon needs to be restarted
in order to read new configuration.

When this stage is finished, \fBnssync\fR reloads the name server
(if required) and exits.

Several command line options can be supplied in order to modify the
program's behavior.  In particular, it is possible to check the
configuration file syntax or even instruct the utility to do
everything, except modifying the zone files (a so-called dry-run
mode).  This allows you to debug your configuration before actually
starting using \fBnssync\fR.
.SH OPTIONS
.TP
\fB\-E\fR
Preprocess configuration file and exit.
.TP
\fB\-c\fR \fIFILE\fR, \fB\-\-config\-file=\fIFILE\fR
Use \fIFILE\fR instead of the default configuration file.
.TP
\fB\-f\fR, \fB\-\-force\fR
Proceed even if SQL slave status has not changed.
.TP
\fB\-n\fR, \fB\-\-dry\-run\fR
Do nothing, print almost everything; implies
\fB\-\-debug \-\-stderr\fR.  Use additional \fB\-\-debug\fR options to get
even more info.
.TP
\fB\-t\fR, \fB\-\-lint\fR
Parse configuration file and exit.  The return status is 0 if the
syntax is OK, and 78 if errors were detected (see \fBEXIT CODES\fR below).
.TP
\fB\-D\fR \fISYMBOL\fR=\fIVALUE\fR, \fB\-\-define\fR=\fISYMBOL\fR[=\fIVALUE\fR]
Define a preprocessor symbol.
.TP
\fB\-I \fIDIR\fR, \fB\-\-include\-directory\fR=\fIDIR\fR
Add preprocessor include directory.
.TP
\fB\-\-no\-preprocessor\fR
Disable preprocessing.
.TP
\fB\-\-preprocessor\fR=\fICOMMAND\fR
Use \fICOMMAND\fR instead of the default preprocessor.
.TP
\fB\-d\fR, \fB\-\-debug\fR
Increase debug level.
.TP
\fB\-X\fR, \fB\-\-debug\-lexer\fR
Debug configuration file lexer.
.TP
\fB\-x\fR, \fB\-\-debug\-parser\fR
Debug configuration file parser.
.TP
\fB\-\-config\-help\fR
Show configuration file summary.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version.
.TP
\fB\-h\fR, \fB\-\-help\fR
Give this help list.
.TP
\fB\-\-usage\fR
Give a short usage message.
.SH CONFIGURATION FILE
.SS General Settings
.TP
\fBcheck\-ns\fR \fIBOOL\fR;
If set to \fBtrue\fR, \fBnssync\fR 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 \fBnssync\fR is run.
.TP
\fBpidfile\fR \fIFILE\fR;
At startup, check if \fIFILE\fR already exists and is owned by an existing
process.  Exit if so.  Use this statement to avoid accidentally
running two copies of \fBnssync\fR simultaneously.
.TP
\fBtempdir\fR \fIDIR\fR;
Sets the name for the temporary directory.  This is a directory where
\fBnssync\fR creates temporary zone files.  The argument must
point to an existing directory.
.TP
\fBnamed\-conf\fR \fIfile\fR;
Defines the full pathname of the \fBnamed\fR configuration file.
Default is \fB/etc/named.conf\fR.
.TP
\fBbind\-include\-path\fR \fILIST\fR;
Sets include search path for \fBinclude\fR directives found in BIND
configuration.  The argument is either a single directory or a list of
directories.
.TP
\fBzonefile\-pattern\fR \fIPAT\fR;
Defines the pattern for zone file names.  The name of each zone
file is created by expanding variable references in the \fIPAT\fR
argument.  The following variable references are defined: \fB$zone\fR
(or \fB${zone}\fR), which is replaced with the name of the zone
(without the trailing dot), and \fB$synctag\fR (or \fB${synctag}\fR),
replaced with the synchronization tag (see below).

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 \fB$zone.$synctag\fR.
.TP
\fBzone\-conf\fR \fIPAT\fR;
Defines the pattern for zone configuration file, i.e. a file
containing \fBzone\fR statements.

The handling of \fIPAT\fR is similar to that in \fBzonefile-pattern\fR,
except that only the \fB$synctag\fR reference is defined.
.TP
\fBcompare\-command\fR \fICMD\fR;
Defines a command to be used for comparing two zone files.  The
\fICMD\fR must be a command taking two files as its arguments and
returning 0 if they are the same or non-zero if they differ.
\fBNssync\fR uses this command to determine whether a particular
zone has changed.  The variable references \fB$oldfile\fR and
\fBnewfile\fR are replaced with the old and new zone file names,
accordingly.

The default \fBcompare\-command\fR value is:

   cmp $oldfile $newfile > /dev/null
.TP
\fBreload\-command\fR \fIcmd\fR;
Defines a command to reload the nameserver.  The default is
\fB/usr/sbin/rndc reload\fR.
.SS SQL Access
.TP
\fBhost\fR \fIHOSTNAME\fR[:\fIPORT\-OR\-SOCKET\fR];
Defines the SQL server IP and port.  The \fIHOSTNAME\fR can be either
the server IP address or its hostname.  The \fIPORT\-OR\-SOCKET\fR 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 \fIHOSTNAME\fR is effectively ignored.
.TP
\fBdatabase\fR \fINAME\fR;
Sets the database name.
.TP
\fBssl\-ca\fR \fIFILE\fR;
Defines the name of the Certificate Authority (CA) file.
.TP
\fBuser\fR \fINAME\fR;
Sets SQL user name.
.TP
\fBpassword\fR \fIARG\fR;
Sets SQL user password.
.TP
\fBsql\-config\-file\fR \fIFILE\fR;
Read MySQL configuration from the \fBoption file\fR \fIFILE\fR. 
.TP
\fBsql\-config\-group\fR \fINAME\fR;
Read the named group from the SQL configuration file.
.TP
\fBslave\-status\-file\fR \fIFILE\fR;
Use this statement if \fBnssync\fR 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, \fBnssync\fR will save the state of
the MySQL slave in \fIFILE\fR.  Upon startup, it will read these data
and compare them with the current state.  If they are the same, it
will exit immediately.
.SS Synchronization Block
A \fBsynchronization block\fR 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 \fBsynchronization
tag\fR, supplied as the argument to the \fBsync\fR statement:

  # Define a synchronization block.
  \fBsync\fR \fITAG\fR {
    # zone configuration file
    \fBzone\-conf\fR \fIPAT\fR;
    # pattern for new zone file names
    \fBzonefile\-pattern\fR \fIPAT\fR;
    # add these statements to each generated zone file
    \fBadd\-statements\fR \fITEXT\fR;
    # a query for retrieving SOA records
    \fBsoa\-query\fR \fISTRING\fR;
    # a query for retrieving NS and similar records
    \fBns\-query\fR \fIstring\fR;
    # a query for retrieving the rest of RRs
    \fBrr\-query\fR \fIstring\fR;
    # a query for retrieving RRs from reverse delegation zones
    \fBrev\-rr\-query\fR \fIstring\fR;
  }

Statements within the \fBsync\fR block configure the zones:
.TP
\fBzone\-conf\fR \fIPAT\fR;
Defines the pattern for the name of zone configuration file for zones
in this synchronization block.  If not supplied, the global
\fBzone\-conf\fR statement will be used instead (see above).
.TP
\fBzonefile\-pattern\fR \fIPAT\fR;
Defines the pattern for zone file names.  If not supplied, the global
\fBzonefile\-pattern\fR statement will be used instead (see above).
.TP
\fBadd-statements\fR \fITEXT\fR;
Append \fITEXT\fR 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;
.TP
The following statements define which zones pertain to this particular
synchronization block:
.TP
\fBsoa\-query\fR \fISTRING\fR;
A query for retrieving SOA records.
.TP
\fBns\-query\fR \fISTRING\fR;
A query for retrieving NS and similar records.  Use the \fB$zone\fR
reference for the zone name.
.TP
\fBrr\-query\fR \fISTRING\fR;
A query for retrieving the rest of RRs.  Use the \fB$zone\fR
reference for the zone name.
.TP
\fBrev\-rr\-query\fR \fISTRING\fR;
A query for retrieving RRs from reverse delegation zones.  Use the
\fB$zone\fR reference for the zone name.

.SH EXIT CODES
The following exit codes are defined:
.RS
.PD 0
.TP 3
.B 0
Normal termination.
.TP 3
.B 64
Invalid command line usage.
.TP 3
.B 69
Some error occurred.  For example, the program was unable to open
output file, etc.
.TP 3
.B 70
Internal software error.  This usually means hitting a bug in the
program, so please report it.
.TP 3
.B 98
Program terminated due to errors in configuration file.
.PD
.RE
If a non-0 code is returned the exact cause of failure is
reported on the currently selected logging channel.
.SH BUGS
Only MySQL is supported.
.SH AUTHORS
Sergey Poznyakoff
.SH "BUG REPORTS"
Report bugs to <gray+nssync@gnu.org.ua>.
.SH COPYRIGHT
Copyright \(co 2011, 2012, 2014 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH NSSYNC \"8\" \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 18
.\" end: