rollrec(3)

NAME
rollrec - Rollover-related zone data used by DNSSEC-Tools programs.

DESCRIPTION
rollrec files contain data used by the DNSSEC-Tools to manage key rollover. A rollrec file is organized in sets of rollrec records. Each rollrec record describes the rollover state of a single zone and must be either of roll type or skip type. Roll rollrecs record information about currently rolling zones. Skip rollrecs record information about zones that are not being rolled. A rollrec consists of a set of keyword/value entries.

The DNSSEC-Tools rollrec.pm module manipulates the contents of a rollrec file. Module interfaces exist for looking up rollrec records, creating new records, and modifying existing records.

Comment lines and blank lines are ignored by the DNSSEC-Tools programs. Comment lines start with either a '#' character or a ';' character.

A rollrec's name may consist of alphabetic characters, numbers, and several special characters. The special characters are the minus sign, the plus sign, the underscore, the comma, the period, the colon, the forward-slash, the space, and the tab. This name is an identifier. It is commonly set to be the same as the name of the zone which the rollrec record describes, but this is not necessary. If the name is not given, then rollerd will create a new zonename field using the name of the rollrec record.

The values in a rollrec's entries may consist of alphabetic characters, numbers, and several special characters. The special characters are the minus sign, the plus sign, the underscore, the comma, the period, the colon, the forward-slash, the space, and the tab.

There is a special rollrec called the rollrec info rollrec. It contains information about the rollrec file, such as the version of rollrecs stored within the file. It is only accessible through the rollrec_info() interface, and the rollrec_current() interface will indicate if the file's version number is current. The name of this rollrec is "rollrec info", which is a reserved name. It has its own set of fields, with only one overlap with regular rollrecs.

FILE VERSIONS
The rollrec file format will evolve from time to time. The rollrec info rollrec was introduced specifically to account for changes between versions. You should not manually change a rollrec file's version, but let the DNSEC-Tools update the file for you. The version differences are summarized below.

Version 1: This was the original format of the rollrec file. At various times, additional fields were added to it, but the basic format of the file remained essentially the same.

Version 2: The rollrec info rollrec was added for this version. No other format changes were introduced. The rollrec.pm module was modified to recognize this rollrec and not allow calling programs to modify it. For this reason, versions 1 and 2 are considered functionally equivalent when it comes to whether or not a rollrec file is considered current. (DNSSEC-Tools version 1.15; February 2013)

FIELDS
The fields in a rollrec record are:

 * administrator

This is the email address for the zone's administrative user. If it is not set, the default from the DNSSEC-Tools configuration file will be used.

 * curerrors

The count of consecutive errors for the zone. This count is set to zero upon successful completion of a KSK or ZSK rollover.

 * directory

This field contains the name of the directory in which rollerd will execute for the rollrec's zone. If it is not specified, then the normal rollerd execution directory will be used.

 * display

This boolean field indicates whether or not the zone should be displayed by the blinkenlights program.

 * keyrec

The zone's keyrec file.

 * kskphase

The zone's current KSK rollover phase. A value of zero indicates that the zone is not in rollover, but is in normal operation. A numeric value of 1-7 indicates that the zone is in that phase of KSK rollover.

 * ksk_rolldate

The time at which the zone's last KSK rollover completed. This is only used to provide a human-readable format of the timestamp. It is derived from the ksk_rollsecs field.

 * ksk_rollsecs

The time at which the zone's last KSK rollover completed. This value is used to derive the ksk_rolldate field.

 * loglevel

The rollerd logging level for this zone.

 * maxerrors

The maximum number of consecutive errors for the zone. After this count has been exceeded, the zone will be changed to be a skip zone. If a zone doesn't have this field set, the zone_errors configuration value will be used instead.

 * maxttl

The maximum time-to-live for the zone. This is measured in seconds.

 * phasestart

The time-stamp of the beginning of the zone's current phase.

 * version

This is the format version of the rollrecs in the rollrec file. The value of this field is a numeric value, such as "1.3" or "2". It should only be modified by DNSSEC-Tools programs. This field is only available in the rollrec info rollrec.

 * zonefile

The zone's zone file.

 * zonegroup

The zone's zonegroup. This is used to associate related zones for group rollctl commands. This field is optional.

 * zonename

The zone's name. If this is not given, then rollerd will create a new zonename field using the name of the rollrec record.

 * zsargs

The user-specified arguments for zonesigner. This field is set by the rollctl -zsargs command to allow modification of a zone's rollover options without having to restart rollerd.

 * zskphase

The zone's current ZSK rollover phase. A value of zero indicates that the zone is not in rollover, but is in normal operation. A value of 1, 2, 3, 4 indicates that the zone is in that phase of ZSK rollover.

 * zsk_rolldate

The time at which the zone's last ZSK rollover completed. This is only used to provide a human-readable format of the timestamp. It is derived from the zsk_rollsecs field.

 * zsk_rollsecs

The time at which the zone's last ZSK rollover completed. This value is used to derive the zsk_rolldate field.

EXAMPLES
The following is an example of a roll rollrec:

    roll "example"
            zonename        "example.com"
            zonefile        "example.signed"
            keyrec          "example.krf"
            zonegroup       "example zones"
            kskphase        "1"
            zskphase        "0"
            administrator   "bob@bobbox.example.com"
            loglevel        "info"
            maxttl          "60"
            display         "1"
            zsargs          "-zsklength 2048"
            ksk_rollsecs    "1172614842"
            ksk_rolldate    "Tue Feb 27 22:20:42 2007"
            zsk_rollsecs    "1172615087"
            zsk_rolldate    "Tue Feb 27 22:24:47 2007"
            phasestart      "Mon Feb 20 12:34:56 2007"

The following is an example of a skip rollrec:

    skip "test.com"
            zonename        "test.com"
            zonefile        "test.com.signed"
            keyrec          "test.com.krf"
            kskphase        "0"
            zskphase        "2"
            administrator   "tess@test.com"
            loglevel        "info"
            maxttl          "60"
            display         "1"
            ksk_rollsecs    "1172614800"
            ksk_rolldate    "Tue Feb 27 22:20:00 2007"
            zsk_rollsecs    "1172615070"
            zsk_rolldate    "Tue Feb 27 22:24:30 2007"
            phasestart      "Mon Feb 20 12:34:56 2007"

The following is an example of a skip rollrec:

    roll "rollrec info"
            version         "2"

COPYRIGHT
Copyright 2006-2013 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details.

AUTHOR
Wayne Morrison, tewok@tislabs.com

SEE ALSO
lsroll(1)

blinkenlights(8), rollctl(8), rollerd(8), zonesigner(8)

Net::DNS::SEC::Tools::keyrec(3), Net::DNS::SEC::Tools::rollrec(3)

keyrec(5)