rollerd - Man Page

The Pre-Publish Method has four phases that are entered when it is time to perform ZSK rollover:

    1. wait for old zone data to expire from caches
    2. sign the zone with the KSK and Published ZSK
    3. wait for old zone data to expire from caches
    4. adjust keys in keyrec and sign the zone with new Current ZSK

rollerd uses the zonesigner command during ZSK rollover phases 2 and 4. zonesigner will generate keys as required and sign the zone during these two phases.

The Pre-Publish Method of key rollover is defined in the Step-by-Step DNS Security Operator Guidance Document.  See that document for more detailed information.

The Double Signature Method has seven phases that are entered when it is time to perform KSK rollover:

    1 - wait for cache data to expire
    2 - generate a new (published) KSK and load zone
    3 - wait for the old DNSKEY RRset to expire from caches
    4 - transfer new keyset to the parent
    5 - wait for parent to publish DS record
    6 - wait for cache data to expire
    7 - roll the KSKs and load the zone

This is a modification of the original Double Signature Method.  In the original method, the KSK keys were rolled before the new keyset was transferred to the parent.  The new method rolls the KSK keys after the parent has published the new DS records and old data has expired for caches. This addresses a potential problem with signing zones during key rollovers.

rollerd uses the zonesigner command during KSK rollover phases 2 and 7. zonesigner will generate keys as required and sign the zone during these two phases.

Currently, leaving the waiting period in step 5 is handled manually.  In step 4, rollerd informs the administrator via email that the zone's keyset must be transferred to its parent in order for rollover to continue.  In step 5, after the keyset has been transferred to the parent and the parent has published a new DS record, the administrator uses rollctl to inform rollerd that the DS record has been published and rollover may continue.

The Double Signature Method of key rollover is defined in the Step-by-Step DNS Security Operator Guidance Document.  See that document for more detailed information.

RFC5011 describes how remote-validating resolvers must track KSK changes within a zone.  If configured for RFC5011 behavior, rollerd and zonesigner add an extra-long period of time between the point a new KSK is created and published and the point where the actual switch to using it takes place.  RFC5011 specifies that remote validators should add a "hold-down timer" to the rollover process, such that the new key is not added as a trust-anchor until 30 days have past.  Thus, rollerd will wait for 60 days (by default) during phase 3 of the KSK rollover process if the "istrustanchor" field of the rollrec definition has been set to either 1 or "yes".  To wait for a different length of time other than 60 days, use the holddowntime field.

At this time, the other conventions of RFC5011 are not being followed. Specifically, it's not waiting for a while before removing the old key and it's not adding the revoke bit to the old key after switching.

An administrator can specify site-specific commands to be run during the various rollover phases.  The commands can be run in place of the default rollerd rollover actions, or in addition to them.  This subsection describes how to make use of site-specific rollover actions.

This capability is provided to allow different installations to handle rollover according to their specific needs.  For example, it is anticipated that this might be helpful to sites using HSM hardware, or to allow for enhanced reporting to administrators.  This has been used with simple test programs to ensure that it actually works.  However, it has not yet been used in actual HSM environment or with other production-level software replacements.

See the ZSK Rollover Using the Pre-Publish Method and KSK Rollover Using the Double Signature Method sections for descriptions of the default rollover actions.

WARNING: This has the potential of being a dangerous capability.  Be very careful when setting up and using it.  Take care with the site-specific commands to be executed and the permissions and ownership of rollerd and its data files.

DNSSEC-Tools Configuration File Changes

The DNSSEC-Tools configuration file must be modified to tell rollerd what must be run for the non-default rollover phase actions.  Key/value pairs may be set for each rollover phase to control how that phase differs from the default.

The value portion of the configuration entry contains the path to the site-specific phase command, along with any arguments it might need. Multiple commands are separated by bangs.

The reserved default command tells rollerd to use its normal rollover action for a particular phase.  This may be combined with other commands to provide things such as specialized logging or notifications.

rollerd will only alter the behavior of a rollover phase if the configuration file contains an entry for that phase.  If not, the default action will be taken.

For example, this configuration line tells rollerd that for ZSK rollover phase 2, instead of using its normal zonesigner executions it should run the hsm-signer command.

    prog-zsk2        hsm-signer

In this example, this configuration line informs rollerd that when entering KSK rollover phase 1 and ZSK rollover phase 1, it should execute the log-and-mail command, then use the normal rollover action for those phases.

    prog-ksk1        /usr/local/sbin/log-and-mail mary ! default
    prog-zsk1        /usr/local/sbin/log-and-mail bob!default

The following configuration keys are used for controlling KSK rollover phases: prog-ksk1, prog-ksk2, prog-ksk3, prog-ksk4, prog-ksk5, prog-ksk6, and prog-ksk7,

The following configuration keys are used for controlling ZSK rollover phases: prog-zsk1, prog-zsk2, prog-zsk3, and prog-zsk4.

The prog-normal configuration key controls the normal, non-rollover state.

Site-Specific Commands

To be generally useful, the site-specific commands executed by rollerd will be given a standard set of arguments, and a standard set of exit values will be recognized.

The standard arguments from rollerd are:
   1. zonename - Zone to be handled.
   2. phase - Zone's current rollover phase (e.g., zsk1, ksk6, normal.)
   3. rollrec name - Zone's entry key in the rollrec file.
   4. rollrec file - The path to the rollrec file.
   5. keyrec file - The path to the zone's keyrec file.

The prog-phase entry in the configuration file may specify additional options and arguments for a command.  These will be included on the execution command line prior to the standard arguments.

The standard exit values expected by rollerd are:
   0. The zone can move to the next rollover phase.
      This is only applicable to the current command; other
      commands in this phase's command list must still be run.
   1. The zone should stay in the current rollover phase.
      This is not necessarily the result of an error.
   2. An error was found in the arguments given to the command.
   3. An error was encountered during execution.

If a rollover phase's configuration entry lists multiple commands, they will be executed in the order listed.  If any command in that command list fails, processing stops there.

The rp-wrapper command shows how a site-specific command may be written. rp-wrapper may be used as a skeleton on which to build a more useful rollover-phase command.

Considerations for Site-Specific Commands

The following should be taken into consideration when writing a site-specific command for a rollover phase.

execution length

A phase command should not execute very long.  As currently written, rollerd serializes zone rollover.  So the longer a phase command takes to execute, the longer it will take to get to the next zone.  If a phase command sleeps or actively waits, so to speak, for the next phase timeout, then every zone rollerd manages will be left waiting.

follow interface guidelines

Follow the standards for arguments and exit values.  Not following the standards is likely to negatively affect zone rollover.

frequency of command execution

If rollerd is operating in its traditional "full list" processing mode, a phase command list will be executed every time rollerd cycles through its zone list and a zone is in that particular command's phase.  For example, if <i>prog_zsk1</i> is defined for example.com, that command list will be executed for example.com every time rollerd runs its zone list and finds example.com is in the ZSK phase 1 rollover state.  A phase command must take this into account so it doesn't perform its actions more frequently than necessary.  This is most likely an issue for the various rollover wait states, and possibly the normal state.

If rollerd is operating in the experimental "soon queue" processing mode, a phase command list will be executed for a zone only when a phase change occurs.  Since phase changes are time queued, this should not happen more than once per phase.  A phase command should take this into account, in case the soon queue is reordered before the zone leaves the queue, or queue timing is relatively swift.  This is most likely an issue for the various rollover wait states.

WARNING:  "soon queue" processing is experimental.  Care should be taken when using this processing method, as it may still have some lingering bugs.

rollerd has the opportunity to inform the DNS daemon to reload a zone in KSK phase 2, KSK phase 7, ZSK phase 2, and ZSK phase 4.  This is the rollerd's default behavior.  However, there are situations where this shouldn't be done, such as for off-line signing.

The roll_loadzone field of the DNSSEC-Tools configuration file is a boolean field that overrides the default to force the zone-reload behavior either on or off.  This field takes precedence over the default.

Similarly, the -noreload option prevents rollerd from requesting a zone reload, and it takes precedence over the roll_loadzone configuration field and the default.

The zones to be managed by rollerd are described in a rollrec file.  Generally speaking most people will want to use the rollinit command to create an initial rollrec file instead of typing their own from scratch.  See the Initialization and Usage section below and the rollinit manual page for details. Each zone's entry contains data needed by rollerd and some data useful to a user.  Below is a sample rollrec entry:

        roll "example.com"
                zonename        "example.com"
                zonefile        "example.com.signed"
                keyrec          "example.com.krf"
                zonegroup       "demo-zones"
                directory       "dir-example.com"
                kskphase        "0"
                zskphase        "3"
                ksk_rollsecs    "1172614842"
                ksk_rolldate    "Tue Feb 27 22:20:42 2007"
                zsk_rollsecs    "1172615087"
                zsk_rolldate    "Tue Feb 27 22:24:47 2007"
                maxttl          "60"
                display         "1"
                phasestart      "Tue Feb 27 22:25:07 2007"
                # optional records for RFC5011 rolling:
                istrustanchor   "no"
                holddowntime    "60D"

The first line gives the rollrec entry's name.  The name distinguishes it from other rollrec entries and must be unique.  This may be the zone's name, but this is not a requirement.  The following lines give the zone's name, the zone's signed zone file, keyrec file, the current rollover phases, the rollover timestamps, and other information.  The zone group is optional and allows a set of related zones to be controlled with a single rollctl execution, rather than one execution per zone.

If either of the zonefile or keyrec files do not exist, then a "roll" rollrec will be changed into a "skip" rollrec.  That record will not be processed.

A more detailed explanation may be found in rollrec(5).

rollerd's execution directory is either the directory in which it is executed or the directory passed in the -directory command-line option. Any files used by rollerd that were not specified with absolute paths use this directory as their base.

A rollrec file's directory field informs rollerd where the zone's files may be found.  For that zone, rollerd will move into that directory, then return to its execution directory when it finishes rollover operations for that zone.  If the directory value is a relative path, it will be appended to rollerd's execution directory.  If the directory value is an absolute path, it will be used as is.

The rollctl command is used to control the behavior of rollerd.  A number of commands are available, such as starting or stopping rollover for a selected zone or all zones, turning on or off a GUI rollover display, and halting rollerd execution.  The communications path between rollerd and rollctl is operating system-dependent.  On Unix-like systems, it is a Unix pipe that should only be writable by the user which runs rollerd.  A more detailed explanation of rollctl may be found in rollctl(8).

There are a number of files and filenames used by rollerd and zonesigner.  The user must be aware of the files used by these programs, where the files are located, and where the programs are executed.

By default, rollerd will change directory to the DNSSEC-Tools directory, though this may be changed by the -directory option.  Any programs started by rollerd, most importantly zonesigner, will run in this same directory.  If files and directories referenced by these programs are named with relative paths, those paths must be relative to this directory.

The rollrec entry name is used as a key to the rollrec file and to the zone's keyrec file.  This entry does not have to be the name of the entry's domain, but it is a very good idea to make it so.  Whatever is used for this entry name, the same name must be used for the zone keyrec in that zone's keyrec file.

It is probably easiest to store rollrec files, keyrec files, zone files, and key files in a single directory.