The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

zsu - update serial numbers in DNS zone files

SYNOPSIS

zsu [-cdfhLnv] zone ...

README

zsu updates serial numbers in DNS zone files.

DESCRIPTION

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!

Introduction

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 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

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.

Details

zsu works with the standard YYYYMMDDN 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, YYYYMMDDNN and YYMMDDNN.

Unless the -n option is given, zsu will only process zone files with serial numbers in such formats; other zone files will be skipped. 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. Often NNNN format counters are used with some kind of DNS management system, and most such systems want to manage the serial numbers themselves, but when you know it is safe to do so, the -n option can be specified to force zsu to treat all serial numbers as plain integers.

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.

When the serial number indicates a date in the future, zsu will continue to use the future date, as long as the counter can still be incremented while retaining the date format. In verbose mode, a warning is issued when encountering such a timewarp. In a future release, serial number wraparound (see RFC 1982) may be supported to help fix inadvertent timewarps.

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.

Specify both -c and -n to convert from plain integer to date format serial numbers. You should only need to use -cn once if you are upgrading to date format serial numbers; subsequent invocations should not specify either -c or -n.

OPTIONS

-c Change serial number format if necessary (otherwise will simply warn about overflow and similar errors, and leave the zone file intact). In conjunction with the -c option, convert integer serial numbers to YYYYMMDDN format. Do not use -c if other programs rely on the serial format!
-d Print debugging information.
-f Force update, even if this host is not SOA origin.
-h Display a brief help message.
-L Show the software license.
-n Treat the serial number as a plain integer, and increment it. Take care with this option if zone files are generated automatically, for instance from a database!
-v Verbose mode. Show the progress of the program.

RETURN VALUE

Returns 0 on success, -1 if there was a problem with the command line arguments, or a positive integer indicating the number of zone files which could not be updated.

PREREQUISITES

You need Perl installed. See http://www.perl.org/ for details. Latest versions have been tested with perl 5.005_03 but should also work with other 5.x versions (including 5.6.1). Versions up to 1.18 were compatible with perl 4, but later versions require perl 5.

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

    original        zsu -cn                 zsu -n
    -----------     ----------------        ----------------
    837             200108120               838
    203456789       2001081200              203456790
    1034567890      2001081200              1034567891
    2147483646      warn: no change         2147483647
    2147483647      warn: no change         warn: no change

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.

SEE ALSO

named(8)

AUTHOR

Copyright 1994-2004 Andras Salamon <andras@dns.net>.

HISTORY

Version 1.20 added more information about the -n option.

Version 1.19 now requires Perl 5, added -n option, changed warnings to use NN instead of nn and (YY)YY instead of (yy)yy.

Version 1.18 supports dates in the future.

Version 1.17 moved to POD documentation.

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. This version introduced the -c option; previously the serial number format was silently changed when necessary. Use -c for the old behaviour.

AVAILABILITY

The latest version of zsu is available from http://www.dns.net/dist/zsu/ and also from CPAN, at http://www.cpan.org/authors/id/A/AZ/AZS/zsu/ and in http://www.cpan.org/scripts/Networking/ .

SCRIPT CATEGORIES

Networking VersionControl/CVS Unix/System_administration