README for zsu
(last updated for zsu 1.16)


What is it:

zsu is a script to automate updating serial numbers in DNS zone files.


Why is it useful:

After any changes are made to a DNS zone file, the serial number must be
increased -- otherwise changes will not propagate to the slave servers
(secondaries).  zsu handles the serial number update automatically,
while preserving everything else in the file.

Forgetting to increase the serial number is one of the most common causes
of hair loss among DNS administrators!


Where to get it:

http://www.dns.net/dist/zsu-1.16.tar.gz


How to use it:

First, you need Perl installed.  See http://www.perl.org/ for details.
Version 1.16 has been tested with perl 5.005_03 but should also work
with other 5.x versions (including 5.6.1) and with perl 4.036.

zsu expects one or more zonefile names as arguments.  The command
    zsu /etc/db.local 0.0.127.in-add.arpa /var/named/db.example.com
will update the serial numbers in each of the three zone files listed.

zsu will ignore zone files where the originating host in the SOA record
does not match the local hostname.  Use the -f option to override
this check.

zsu is most commonly used as part of a revision control system for zone
files, just before changes are committed to a repository.  The following
simple script demonstrates this.  The script expects a single zonefile
name as an argument, and relies on ci/co/rcsdiff (all parts of RCS,
from ftp://ftp.cs.purdue.edu/pub/RCS/ ):

#!/bin/sh
co -l $1
vi $1
rcsdiff -q $1 > /dev/null
if [ ! $? ]; then
    zsu -cf $1
    ci -u $1
fi


Details:

zsu works with the standard YYYYMMDDNN serial number format, which is
derived from the current date and a counter to distinguish multiple
changes made the same day.  zsu tries very hard to increase the serial
number while keeping its format.  zsu works with 2 or 4 digit years and
1 or 2 digit counters, so it will also try to work with formats YYMMDDN,
YYYYMMDDN and YYMMDDNN.

Other formats are currently not dealt with, and zsu will skip zone files
containing serial numbers in such formats. Unsupported formats include
YYYYMMDDmm, where mm is time since midnight expressed in 15-minute
units, or good old NNNN flat integer counters.  I could add support for
YYYYMMDDmm if there is demand.  NNNN format counters are not dealt with
since they usually indicate that some kind of DNS management system is in
place, and most such systems want to manage the serial numbers themselves.

zsu understands standard zonefile syntax and will attempt to change
the first SOA record found in each of the zones specified.  zsu will
silently ignore zone files which do not appear to be for the local host
to prevent changes to zone files on slave servers.  Use the -f option
to force updates even if the origin in the SOA record fails to match
the hostname as determined by zsu.

Use the -c option to allow zsu to change the format when necessary (by
default zsu will just complain about these situations).  Changing the
format is necessary if using two-digit years and the century has changed,
or if YYMMDDNN format is used and NN is 99, or if a 1 digit counter has
reached 9.


Examples:

The first few lines of a zone file will typically look something like:

; some comments
@ IN SOA myhost.example.com. hostmaster.example.com. (
  1998021503 ; the serial number
  28800 ; refresh

If the system date was 12 August 2001 and you updated the zone with zsu,
this snippet would end up as:

; some comments
@ IN SOA myhost.example.com. hostmaster.example.com. (
  2001081200 ; the serial number
  28800 ; refresh

Here is a table of what would be done to some other serial numbers,
if the system date was 12 August 2001:

original        zsu                     zsu -c
-----------     ----------------        ----------------
9712231         9712232                 9712232
97122301        97122302                97122302
199712231       199712232               199712232
1997122301      1997122302              1997122302
9712239         warn: no change         200108120
97122399        warn: no change         2001081200
199712239       warn: no change         200108120
1997122399      warn: no change         2001081200
0108129         warn: no change         01081210
01081299        warn: no change         2001081200
200108129       warn: no change         2001081210
2001081299      warn: no change         warn: no change


Changes:

Version 1.16 renamed the README.zsu file to README, and fixed the
availability information.

Version 1.15 fixed handling of SOA records where the serial is on the
same line as the SOA tag.  Thanks to Frederic Marchand for picking up
the problem and suggesting a solution.  Single line SOA records now also
don't require parentheses, as per RFC 1034.

Version 1.14 added documentation fixes, moved the distribution location,
and noted where to get zsu in the documentation.

Version 1.13 fixed various problems with 2-digit year and 1-digit counter
formats.  zsu is now able to change the format when appropriate, ie. when
the century has changed, or if YYMMDDNN format is used and NN is 99,
or if a 1 digit counter has reached 9.

The -c option is new; previously the serial number format was silently
changed when necessary.  Use -c for the old behaviour.


Bugs:

The hostname checking in zsu is known to be buggy; for instance it will
fail to produce a warning if it needs a domain name, but domainname
returns just whitespace.

Please report other programming errors to me.


Andras Salamon <andras@dns.net>
29 February 2004

