Options with Running rollerd
This is a brief description of the options available for use with running rollerd, the DNSSEC-Tools Zone Rollover Manager.
rollerd is the zone rollover manager provided by DNSSEC-Tools. There have been a number of optional enhancements provided since it was first introduced, such as alternate queuing method and site-specific rollover commands. This is a brief description of the more complex rollerd options a zone administrator could find useful. In general, this is someone who wants to setup and maintain one or more signed DNS zones.
- 1 rollerd Queuing Options
- 2 rollerd Phase Commands
- 2.1 rollerd Standard Rollover Actions
- 2.2 Site-Specific Phase Commands
rollerd Queuing Options
rollerd has two options for managing its collection of zones. The first method, called the full list method, was the first queuing method implemented. This method works well when rollerd is managing relatively small sets of zones. It was found to be insufficient when the number of zones got into many hundreds or thousands. The soon queue method was developed to improve the handling of large sets of zones.
The queuing method is specified by a variable in the rollerd source code. If you want to change the queuing method, you must set the $eventmaster variable.
The full list method is selected by default and is given by this line:
my $eventmaster = $EVT_FULLLIST;
The soon queue method is not selected by default, and is chosen by this line:
my $eventmaster = $EVT_QUEUE_SOON;
Note: The soon queue method is still considered experimental. It works for the zone environments given in the DNSSEC-Tools demos collection. It might be good to test it before putting it into production use.
Full List Method
The "Full List" method queue processing is the classic rollerd method of handling its queue. rollerd adds all its managed zones to a single list of zones to be managed. Every N seconds, the entire queue of zones is scanned and rollover events are handled.
Soon Queue Method
The Soon Queue method is based on the time until the next rollover event. rollerd maintains a time-sorted list of when each zone's next rollover event will occur. It also keeps a sub-queue of the rollover events that must be handled "soon". Rather than processing the full queue of managed zones every N seconds, the "soon queue" is handled as the events occur.
The "soon" time limit is defined by the administrator. This time limit is defined by the $QUEUE_SOONLIMIT variable in rollerd. When building the soon queue, any zone with an event between current time and (current time + $QUEUE_SOONLIMIT) will be added to the soon queue.
Choosing an appropriate value for $QUEUE_SOONLIMIT is important. It will depend on the number of zones being managed and their lifespans. Short values of $QUEUE_SOONLIMIT will result in more frequent builds of the soon queue and (probably) smaller numbers of zones in the soon queue. Large values will result in less frequent rebuilds of the soon queue and (probably) larger numbers of zones in the soon queue.
rollerd Phase Commands
rollerd has a well-defined sequence of events it takes when performing a key rollover. A different sequence is used for KSK rollover than for ZSK rollover, but these sequences are followed for each rollover rollerd performs.
Some administrators may have additional requirements for their installation. For example, keys might be stored off-host and a special command is required to fetch the keys prior to running zonesigner, an alternate wait-time calculation may be used, or special notifications may be wanted when a zone changes rollover phase.
To allow these site-specific requirements, rollerd allows in administrator to define special phase commands to be executed in place of or in addition to normal phase operations. The phase command facility is described below, along with the standard rollover actions taken by rollerd.
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.
rollerd Standard Rollover Actions
rollerd uses different methods for key rollover. The Pre-Publish method is used for ZSK rollover and the Double-Signature method is used for KSK Rollover.
Both methods of key rollover are described in the Step-by-Step DNS Security Operator Guidance Document. See that document for more detailed information.
Pre-Publish Method of ZSK Rollover
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.
Double-Signature Method of KSK Rollover
The Double Signature Method has seven phases that are entered when it is time to perform KSK rollover:
1. Wait for old zone data to expire from caches. 2. Generate a new (published) KSK. 3. Wait for the old DNSKEY RRset to expire from caches. 4. Roll the KSKs. 5. Transfer new keyset to the parent. 6. Wait for parent to publish the new DS record. 7. Reload the zone.
rollerd uses the zonesigner command during KSK rollover phases 2 and 4. zonesigner will generate keys as required and sign the zone during these two phases.
Currently, step 6 is handled manually. In step 5, 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 6, 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.
Site-Specific Phase Commands
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.
See the Pre-Publish Method of ZSK Rollover and Double-Signature Method of KSK Rollover for descriptions of the default rollover actions.
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.
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.
Requirements for 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 given. 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.
A phase command should not execute very long. As currently written, rollerd serializes zone rollover. 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 prog_zsk1 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.