NAME¶
rollinit - Create new rollrec records for a DNSSEC-Tools rollrec file.
SYNOPSIS¶
rollinit [options] <zonename1> ... <zonenameN>
DESCRIPTION¶
rollinit creates new
rollrec entries for a
rollrec file.
This
rollrec file will be used by
rollerd to manage key rollover
for the named zones.
The newly generated
rollrec entries are written to standard output,
unless the
-out option is specified.
A
rollrec entry has this format:
roll "example.com"
zonename "example.com"
zonefile "example.com.signed"
keyrec "example.com.krf"
zonegroup "example-zones"
kskphase "0"
zskphase "0"
administrator "bob@bobhost.example.com"
directory "/var/dns/zones/example.com"
loglevel "phase"
ksk_rolldate " "
ksk_rollsecs "0"
zsk_rolldate " "
zsk_rollsecs "0"
maxttl "604800"
display "1"
phasestart "Mon Jan 9 16:00:00 2006"
# optional records for RFC5011 rolling:
istrustanchor "no"
holddowntime "60D"
The keywords
roll and
skip indicate whether
rollerd should
process or ignore a particular
rollrec entry.
roll records are
created by default;
skip entries are created if the
-skip option
is specified.
The
roll line has a name which is used to distinguish it from all other
rollrec entries in the file. The
zonename field is set to the
name of the zone. These two data are often the same, but this is not required.
rollinit will set them to the same value, unless the
-rollrec
option is used.
The
zonefile and
keyrec fields are set according to command-line
options and arguments. The manner of generating the
rollrec's actual
values is a little complex and is described in the ZONEFILE And KEYREC FIELDS
section below.
The
zonegroup field is used to associate a set of
rollrecs
together, so they can be controlled by a single
rollctl -group command.
This field is optional and
rollinit only sets it if the
-zonegroup option is specified. (While this is using the term
"zone", it is actually referring to the name of the
rollrec
entries.)
The
administrator field is set to the email address of the person (or
person, if the address is actually a mailing list) considered to be the
responsible person for the zone.
The
directory field is set to the directory that contains the the files
for the zone. These files include the zone file, the signed zone file, and the
keyrec file.
The
loglevel field is set to the level of log messages that
rollerd should produce for this zone. The log level includes those
messages at a greater priority to the specified level, so a level of
"phase" will also include "err" and "fatal"
messages.
The
kskphase and
zskphase fields indicate the rollover phase for
the zone's KSK and ZSK keys. The value 0 indicates that the zone is in normal
operation (non-rollover) for that key type. A non-zero phase (1-7 for KSKs;
1-4 for ZSKs) indicates that the zone is in the process of rolling the keys.
Only one of these fields should ever be non-zero at a particular time. If both
are zero, then no rollover operations are taking place.
The
ksk_rolldate and
ksk_rollsecs fields indicate when KSK
rollover started. If the values are a blank and zero, respectively, then the
zone is not in KSK rollover.
The
zsk_rolldate and
zsk_rollsecs fields indicate when ZSK
rollover started. If the values are a blank and zero, respectively, then the
zone is not in ZSK rollover.
The Boolean
display field indicates if
blinkenlights should
display information about this zone.
The
maxttl field contains the maximum TTL value from the zone file.
The
phasestart fields contains the date that the current rollover phase
was entered.
rollrec files also have the
zsargs field that holds user-specified
options for
zonesigner. This field is set during
rollerd
execution when the administrator determines that some zone fields should be
modified. It is not an initial
rollrec field and consequently cannot be
specified by
rollinit.
The
istrustanchor field specifies whether to roll the KSK keys in a
manner compliant with any remote validating resolver using the KSK as a
trust-anchor. If set to "yes" then 60 days will be the minimum wait
time during phase 3 of KSK rolling to ensure remote validators can properly
follow the steps needed as specified by RFC5011. The 60-day default can be
changed via the
holddowntime field.
ZONEFILE and KEYREC FIELDS¶
The
zonefile and
keyrec fields may be given by using the
-zonefile and
-keyrec options, or default values may be used.
The default values use the
rollrec's zone name, taken from the command
line, as a base.
.signed is appended to the zone name for the zone
file;
.krf is appended to the zone name for the
keyrec file.
If
-zonefile or
-keyrec are specified, then the options values are
used in one of two ways:
- 1. A single zone name is given on the command line.
- The option values for -zonefile and/or
-keyrec are used for the actual rollrec fields.
- 2. Multiple zone names are given on the command line.
- The option values for -zonefile and/or
-keyrec are used as templates for the actual rollrec fields.
The option values must contain the string =. This string is
replaced by the zone whose rollrec is being created.
See the EXAMPLES section for examples of how options are used by
rollinit.
OPTIONS¶
rollinit may be given the following options:
- -rollrec rollrec-name
- This specifies the name of the rollrec record. This
value may contain spaces. If this option is not specified, it will be set
to the same value as the zonename field. See the ZONEFILE And
KEYREC FIELDS and EXAMPLES sections for more details.
- -zonefile zonefile
- This specifies the value of the zonefile field. See
the ZONEFILE And KEYREC FIELDS and EXAMPLES sections for more
details.
- -keyrec keyrec-file
- This specifies the value of the keyrec field. See
the ZONEFILE And KEYREC FIELDS and EXAMPLES sections for more
details.
- -zg zonegroup
- This specifies the value of the zonegroup field.
This field is optional.
- -admin
- This specifies the value of the administrator field.
If it is not given, an administrator field will not be included for
the record.
- -directory
- This specifies the value of the directory field. If
it is not given, a directory field will not be included for the
record.
- -loglevel
- This specifies the value of the loglevel field. If
it is not given, a loglevel field will not be included for the
record.
- -skip
- By default, roll records are generated. If this
option is given, then skip records will be generated instead.
- -out output-file
- The new rollrec entries will be appended to
output-file. The file will be created if it does not exist.
If this option is not given, the new rollrec entries will be written
to standard output.
- -help
- Display a usage message.
- -Version
- Display version information for rollinit and
DNSSEC-Tools.
EXAMPLES¶
The following options should make clear how
rollinit deals with options
and the new
rollrecs. Example 1 will show the complete new
rollrec record. For the sake of brevity, the remaining examples will
only show the newly created
zonefile and
keyrec records.
Example 1. One zone, no options¶
This example shows the
rollrec generated by giving
rollinit a
single zone, without any options.
$ rollinit example.com
roll "example.com"
zonename "example.com"
zonefile "example.com.signed"
keyrec "example.com.krf"
kskphase "0"
zskphase "0"
ksk_rolldate " "
ksk_rollsecs "0"
zsk_rolldate " "
zsk_rollsecs "0"
maxttl "0"
display "1"
phasestart "new"
Example 2. One zone, -zonefile option¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-zonefile option.
$ rollinit -zonefile signed-example example.com
roll "example.com"
zonename "example.com"
zonefile "signed-example"
keyrec "example.com.krf"
Example 3. One zone, -keyrec option¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-keyrec option.
$ rollinit -keyrec x-rrf example.com
roll "example.com"
zonename "example.com"
zonefile "example.com.signed"
keyrec "x-rrf"
Example 4. One zone, -zonefile and -keyrec options¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-zonefile and
-keyrec options.
$ rollinit -zonefile signed-example -keyrec example.rrf example.com
roll "example.com"
zonename "example.com"
zonefile "signed-example"
keyrec "example.rrf"
Example 5. One zone, -skip option¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-zonefile and
-keyrec options.
$ rollinit -skip example.com
skip "example.com"
zonename "example.com"
zonefile "example.com.signed"
keyrec "example.com.krf"
Example 6. One zone, -rollrec option¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-rollrec option.
$ rollinit -rollrec test example.com
roll "test"
zonename "example.com"
zonefile "example.com.signed"
keyrec "example.com.krf"
Example 7. Multiple zones, no options¶
This example shows the
rollrecs generated by giving
rollinit
several zones, without any options.
$ rollinit example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "example1.com.signed"
keyrec "example1.com.krf"
roll "example2.com"
zonename "example2.com"
zonefile "example2.com.signed"
keyrec "example2.com.krf"
Example 8. Multiple zones, -zonefile option¶
This example shows the
rollrecs generated by giving
rollinit
several zones, with the
-zonefile option.
$ rollinit -zonefile =-signed example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "example1.com-signed"
keyrec "example1.com.krf"
roll "example2.com"
zonename "example2.com"
zonefile "example2.com-signed"
keyrec "example2.com.krf"
Example 9. Multiple zones, -keyrec option¶
This example shows the
rollrecs generated by giving
rollinit
several zones, with the
-keyrec option.
$ rollinit -keyrec zone-=-keyrec example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "example1.com.signed"
keyrec "zone-example1.com-keyrec"
roll "example2.com"
zonename "example2.com"
zonefile "example2.com.signed"
keyrec "zone-example2.com-keyrec"
Example 10. Multiple zones, -zonefile and -keyrec options¶
This example shows the
rollrecs generated by giving
rollinit
several zones, with the
-zonefile and
-keyrec options.
$ rollinit -zonefile Z-= -keyrec =K example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "Z-example1.com"
keyrec "example1.comK"
roll "example2.com"
zonename "example2.com"
zonefile "Z-example2.com"
keyrec "example2.comK"
Example 11. Single zone, -zonefile and -keyrec options with
template¶
This example shows the
rollrec generated by giving
rollinit a
single zone, with the
-zonefile and
-keyrec options. The options
use the multi-zone
= template.
$ rollinit -zonefile Z-= -keyrec =.K example.com
roll "example.com"
zonename "example.com"
zonefile "Z-="
keyrec "=.K"
This is probably not what is wanted, since it results in the
zonefile and
keyrec field values containing the
=.
Example 12. Multiple zones, -zonefile and -keyrec options without
template¶
This example shows the
rollrecs generated by giving
rollinit
several zones, with the
-zonefile and
-keyrec options. The
options do not use the multi-zone
= template.
$ rollinit -zonefile ex.zone -keyrec ex.krf example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "ex.zone"
keyrec "ex.krf"
roll "example2.com"
zonename "example2.com"
zonefile "ex.zone"
keyrec "ex.krf"
This may not be what is wanted, since it results in the same
zonefile and
keyrec fields values for each
rollrec.
Example 13. Multiple zones, -rollrec option¶
This example shows the
rollrecs generated by giving
rollinit
several zones, with the
-rollrec option. The
rollrec names
include a space.
$ rollinit -rollrec "= entry" example1.com example2.com
roll "example1.com entry"
zonename "example1.com"
zonefile "example1.com.signed"
keyrec "example1.com.krf"
roll "example2.com entry"
zonename "example2.com"
zonefile "example2.com.signed"
keyrec "example2.com.krf"
Example 14. Multiple zones, -zg option¶
This example shows the
rollrec generated by giving
rollinit a set
of zones, with the
-zg option.
$ rollinit -zg "example zones" example1.com example2.com
roll "example1.com"
zonename "example1.com"
zonefile "example1.com.signed"
keyrec "example1.com.krf"
zonegroup "example zones"
roll "example2.com"
zonename "example2.com"
zonefile "example2.com.signed"
keyrec "example2.com.krf"
zonegroup "example zones"
COPYRIGHT¶
Copyright 2006-2012 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),
rollerd(8),
rollchk(8),
zonesigner(8)
Net::DNS::SEC::Tools::keyrec.pm(3),
Net::DNS::SEC::Tools::rollrec.pm (3)
file-keyrec.pm(5),
file-rollrec.pm (5)