xenial (1) rollinit.1p.gz

Provided by: dnssec-tools_2.2-2_all bug

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.  Multiple zonegroups may be specified in a comma-separated list.  Leading
       and trailing whitespace will be deleted, but internal whitespace is allowed.  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.

INFO ROLLRECS

       Starting with DNSSEC-Tools version 1.15, each rollrec file should have an info rollrec.  This special
       rollrec entry contains information about the rollrec file itself and does not contain any zone
       information.  Its contents should not be modified by anything but the DNSSEC-Tools utilities.

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
       -zonegroup 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.

       An info rollrec is shown in the first example.  In the interests of space, it is not included in the
       remaining examples.

   Example 1.  One zone, no options
       This example shows the rollrec generated by giving rollinit a single zone, without any options.

           $ rollinit example.com

               skip    "info rollrec"
                   version         "2"

               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"

   Example 15.  One zone, Two zonegroups
       This example shows the rollrec generated by giving rollinit a set of two zonegroups for a single zone.

           $ rollinit -zg "customers, paid up" example.com
               roll    "example1.com"
                   zonename        "example.com"
                   zonefile        "example.com.signed"
                   keyrec          "example.com.krf"
                   zonegroup       "customers, paid up"

       Copyright 2006-2014 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)