Zonetool

Download
Mailing list
Report a bug

About

Zonetool is a command-line tool for managing DNSSEC-signed DNS zones. It
handles zone and key maintenance for manually-updated and dynamic zones and
zones with multiple views, using the BIND utilities.

Before signing your zones, please read some information about DNSSEC. I
recommend the following:

There are other similar tools for managing DNSSEC zones and keys:

  • zkt by Holger Zuleger (also distributed with BIND >= 9.6.0a1).
  • dnssec-tools by SPARTA, Inc.

Please note that this tool was created to fill some specific needs in the
environment in which it was developed, and although the intention was to make
it general, it has not been comprehensively tested in diverse environments.
If you would like to use it, please test functionality in a non-production
environment, and provide feedback. Thanks!

Installation

Zonetool should be installed on the primary master server for your zone(s).
Its installation is typical of python applications:

python setup.py build
sudo python setup.py install

BIND >= 9.3 should also be installed on your server, in /usr or /usr/local (in
the future this will be more flexible).

Usage

The 'zonetool' script is the administrators interface to DNS zone and DNSSEC
key management. Run 'zonetool help' for a listing of subcommands and
command-line options.

Getting started

For each zone you would like to sign and manage with Zonetool, run the
following, where "example.com" is the origin of your zone:

zonetool bootstrap example.com

See 'zonetool help bootstrap' for more information and complete command
options.

Updating your zones

If you update your zone file manually (i.e., it is not subject to dynamic
updates in your named.conf file), then simply update the zone file (and its
serial), then run:

zonetool resign example.com

See 'zonetool help resign' for more information and complete command options.

If your zone is dynamically updated, then signatures and denial-of-existence
records will be updated automatically by named as the updates are received.
There is no further effort required.

Rolling DNSSEC keys

To roll a ZSK using the pre-published key method, or a KSK using the
double-signature method, respectively, use the following:

zonetool rollzsk example.com

OR

zonetool rollksk example.com

See 'zonetool help rollzsk' and 'zonetool help rollksk' for more information
and complete command options. The commands themselves may take a while to
complete. If they are interrupted, you may rerun the command, and it will
resume where it left off. In the case that the state of a zone becomes
inconsistent with that saved by Zonetool, an error will be printed, preventing
any issues that may cause name resolution failure.

Scheduling maintenance

The 'maintenance' subcommand was designed to be run on a daily basis to resign
zones with expiring signatures, roll keys that have been active for more than
the recommended period of time, and check for consistent state of zones. To
schedule maintenance, you may copy doc/examples/cron.daily to
/etc/cron.daily/zonetool or do something similar. It is important that
maintenance be run regularly--at least daily--to prevent signatures from
expiring.

Some maintenance--particular KSK rollovers--require manual intervention. In
such cases, it will exit with a message indicating that the administrator
should resume maintenance (or the particular rollover) interactively. Zonetool
will detect the state of the zone and resume activity appropriately.

Customization

In addition to the options that can be specified on the command line, other
options may be specified in zonetool.cfg (the default location is
/etc/zonetool/zonetool.cfg, but can be overridden on the command-line) in INI
file format. See doc/examples/zonetool.cfg for details of these options.

Chroot/jail environment

If you run named in a chroot or jail environment, you should pass the location
to zonetool using '-t', or specify it in zonetool.cfg using the 'chroot'
option.

Data

DNSSEC keys and meta information associated with zones are maintained under the
/var/lib/zonetool directory, which is further subdivided by $ORIGIN and view.
All private/public DNSKEY files are stored in this directory, except the active
ZSKs of dynamic zones, which are stored in the directory specified by the
'key-directory' statement in named.conf. In addition to keys, the following
are also stored in this meta directory:

  • The 'log' file contains the history of states of a zone, in terms of KSK and
    ZSK roles
  • The 'log_version' file contains a number specifying the version of the 'log'
    file
  • The 'archive' directory contains keys previously used for signing the zone
    in some capacity, filed by archive year and month
  • The 'dsset-example.com.' and 'keyset-example.com.' contain the DS RRs and
    (KSK) DNSKEY RRs for zone example.com., which are output by the
    dnssec-signzone command

Managing DS records of delegated zones

If example.com. is managed by Zonetool and sub.example.com. is a delegated
child zone that is also signed with DNSSEC, the sub.example.com. administrators
may want to establish trust with example.com. To accomplish this:

  1. Obtain the file 'keyset-sub.example.com.' containing the DNSKEY RRs
    corresponding to sub.example.com.'s KSK
  2. Placed the keyset-sub.example.com. in the meta directory (under
    /var/lib/zonetool) corresponding to example.com
  3. Set 'gen_ds_rrs = yes' in zonetool.cfg
  4. Run 'zonetool resign example.com'

NOTE: If example.com. has delegated any other child zones, which do not have
keyset-* files in example.com.'s meta directory and 'gen_ds_rrs = yes', then
the DS RRs corresponding to those zones will be stripped from example.com.
When using 'gen_ds_rrs = yes' *all* secure delegated zones must have
corresponding keyset-* files in example.com.'s meta directory.

Changing DNSSEC algorithms

Occasionally, it may be necessary to change the algorithms used for signing
your zone. Zonetool has some support for changing algorithms using the
'rollalg' subcommand. In particular rolling from an NSEC (denial-of-existence)
to an NSEC3 (hashed denial-of-existence) zone is supported. The transition
should be seamless. However, transitioning from NSEC3 to NSEC is currently not
supported.

Bugs

  • Running zonetool for large zones is slow and inefficient. Performance could
    be significantly improved.
  • Transitions from NSEC3 to NSEC is not supported.
  • Zonetool does not currently comply with RFC 5011.

Please report bugs and feature requests to the Zonetool Web site.

Author

Zonetool was written by Casey Deccio (ctdecci - AT - sandia - DOT - gov).

Copyright and License

Copyright (2009) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software.

This program is free software, licensed under v2 of the GPL.