.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ROLLINIT 1"
.TH ROLLINIT 1 2023-07-29 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
rollinit \- Create new rollrec records for a DNSSEC\-Tools rollrec file.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  rollinit [options] <zonename1> ... <zonenameN>
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBrollinit\fR creates new \fIrollrec\fR entries for a \fIrollrec\fR file.  This
\&\fIrollrec\fR file will be used by \fBrollerd\fR to manage key rollover for
the named zones.
.PP
The newly generated \fIrollrec\fR entries are written to standard output,
unless the \fB\-out\fR option is specified.
.PP
A \fIrollrec\fR entry has this format:
.PP
.Vb 10
\&    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"
.Ve
.PP
The keywords \fBroll\fR and \fBskip\fR indicate whether \fBrollerd\fR should process
or ignore a particular \fIrollrec\fR entry.  \fBroll\fR records are created by
default; \fBskip\fR entries are created if the \fB\-skip\fR option is specified.
.PP
The \fIroll\fR line has a name which is used to distinguish it from all other
\&\fIrollrec\fR entries in the file.  The \fIzonename\fR field is set to the name
of the zone.  These two data are often the same, but this is not required.
\&\fBrollinit\fR will set them to the same value, unless the \fI\-rollrec\fR option
is used.
.PP
The \fIzonefile\fR and \fIkeyrec\fR fields are set according to command-line options
and arguments.  The manner of generating the \fIrollrec\fR's actual values is a
little complex and is described in the ZONEFILE And KEYREC FIELDS section
below.
.PP
The \fIzonegroup\fR field is used to associate a set of \fIrollrec\fRs together,
so they can be controlled by a single \fBrollctl \-group\fR 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 \fBrollinit\fR only sets it if the \fI\-zonegroup\fR option is
specified.  (While this is using the term "zone", it is actually referring
to the name of the \fIrollrec\fR entries.)
.PP
The \fIadministrator\fR 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.
.PP
The \fIdirectory\fR 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 \fIkeyrec\fR file.
.PP
The \fIloglevel\fR field is set to the level of log messages that \fBrollerd\fR
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.
.PP
The \fIkskphase\fR and \fIzskphase\fR 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.
.PP
The \fIksk_rolldate\fR and \fIksk_rollsecs\fR fields indicate when KSK rollover
started.  If the values are a blank and zero, respectively, then the zone
is not in KSK rollover.
.PP
The \fIzsk_rolldate\fR and \fIzsk_rollsecs\fR fields indicate when ZSK rollover
started.  If the values are a blank and zero, respectively, then the zone
is not in ZSK rollover.
.PP
The Boolean \fIdisplay\fR field indicates if \fBblinkenlights\fR should display
information about this zone.
.PP
The \fImaxttl\fR field contains the maximum TTL value from the zone file.
.PP
The \fIphasestart\fR fields contains the date that the current rollover phase
was entered.
.PP
\&\fIrollrec\fR files also have the \fIzsargs\fR field that holds user-specified
options for \fBzonesigner\fR.  This field is set during \fBrollerd\fR execution
when the administrator determines that some zone fields should be modified.
It is not an initial \fIrollrec\fR field and consequently cannot be specified
by \fBrollinit\fR.
.PP
The \fBistrustanchor\fR 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 \fBholddowntime\fR field.
.SH "INFO ROLLRECS"
.IX Header "INFO ROLLRECS"
Starting with DNSSEC-Tools version 1.15, each \fIrollrec\fR file should have an
\&\fIinfo rollrec\fR.  This special \fIrollrec\fR entry contains information about
the \fIrollrec\fR file itself and does not contain any zone information.  Its
contents should not be modified by anything but the DNSSEC-Tools utilities.
.SH "ZONEFILE and KEYREC FIELDS"
.IX Header "ZONEFILE and KEYREC FIELDS"
The \fIzonefile\fR and \fIkeyrec\fR fields may be given by using the \fB\-zonefile\fR
and \fB\-keyrec\fR options, or default values may be used.
.PP
The default values use the \fIrollrec\fR's zone name, taken from the command
line, as a base.  \fB.signed\fR is appended to the zone name for the zone file;
\&\fB.krf\fR is appended to the zone name for the \fIkeyrec\fR file.
.PP
If \fB\-zonefile\fR or \fB\-keyrec\fR are specified, then the options values are
used in one of two ways:
.IP "1.  A single zone name is given on the command line." 4
.IX Item "1. A single zone name is given on the command line."
The option values for \fB\-zonefile\fR and/or \fB\-keyrec\fR are used for the actual
\&\fIrollrec\fR fields.
.IP "2.  Multiple zone names are given on the command line." 4
.IX Item "2. Multiple zone names are given on the command line."
The option values for \fB\-zonefile\fR and/or \fB\-keyrec\fR are used as templates
for the actual \fIrollrec\fR fields.  The option values must contain 
the string \fB=\fR.  This string is replaced by the zone whose \fIrollrec\fR
is being created.
.PP
See the EXAMPLES section for examples of how options are used by \fBrollinit\fR.
.SH OPTIONS
.IX Header "OPTIONS"
\&\fBrollinit\fR may be given the following options:
.IP "\fB\-rollrec rollrec-name\fR" 4
.IX Item "-rollrec rollrec-name"
This specifies the name of the \fIrollrec\fR record.  This value may contain
spaces.  If this option is not specified, it will be set to the same value as
the \fIzonename\fR field.
See the ZONEFILE And KEYREC FIELDS and EXAMPLES sections for more details.
.IP "\fB\-zonefile zonefile\fR" 4
.IX Item "-zonefile zonefile"
This specifies the value of the \fIzonefile\fR field.
See the ZONEFILE And KEYREC FIELDS and EXAMPLES sections for more details.
.IP "\fB\-keyrec keyrec-file\fR" 4
.IX Item "-keyrec keyrec-file"
This specifies the value of the \fIkeyrec\fR field.
See the ZONEFILE And KEYREC FIELDS and EXAMPLES sections for more details.
.IP "\fB\-zg zonegroup\fR" 4
.IX Item "-zg zonegroup"
.PD 0
.IP "\fB\-zonegroup zonegroup\fR" 4
.IX Item "-zonegroup zonegroup"
.PD
This specifies the value of the \fIzonegroup\fR field.  This field is optional.
.IP \fB\-admin\fR 4
.IX Item "-admin"
This specifies the value of the \fIadministrator\fR field.  If it is not given,
an \fIadministrator\fR field will not be included for the record.
.IP \fB\-directory\fR 4
.IX Item "-directory"
This specifies the value of the \fIdirectory\fR field.  If it is not given,
a \fIdirectory\fR field will not be included for the record.
.IP \fB\-loglevel\fR 4
.IX Item "-loglevel"
This specifies the value of the \fIloglevel\fR field.  If it is not given, a
\&\fIloglevel\fR field will not be included for the record.
.IP \fB\-skip\fR 4
.IX Item "-skip"
By default, \fBroll\fR records are generated.  If this option is given, then
\&\fBskip\fR records will be generated instead.
.IP "\fB\-out output-file\fR" 4
.IX Item "-out output-file"
The new \fIrollrec\fR entries will be appended to \fIoutput-file\fR.
The file will be created if it does not exist.
.Sp
If this option is not given, the new \fIrollrec\fR entries will be written
to standard output.
.IP \fB\-help\fR 4
.IX Item "-help"
Display a usage message.
.IP \fB\-Version\fR 4
.IX Item "-Version"
Display version information for \fBrollinit\fR and DNSSEC-Tools.
.SH EXAMPLES
.IX Header "EXAMPLES"
The following options should make clear how \fBrollinit\fR deals with options and
the new \fIrollrec\fRs.  Example 1 will show the complete new \fIrollrec\fR record.
For the sake of brevity, the remaining examples will only show the newly
created \fIzonefile\fR and \fIkeyrec\fR records.
.PP
An \fIinfo rollrec\fR is shown in the first example.  In the interests of space,
it is not included in the remaining examples.
.SS "Example 1.  One zone, no options"
.IX Subsection "Example 1. One zone, no options"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, without any options.
.PP
.Vb 1
\&    $ 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"
.Ve
.SS "Example 2.  One zone, \-zonefile option"
.IX Subsection "Example 2. One zone, -zonefile option"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fI\-zonefile\fR option.
.PP
.Vb 5
\&    $ rollinit \-zonefile signed\-example example.com
\&        roll    "example.com"
\&            zonename        "example.com"
\&            zonefile        "signed\-example"
\&            keyrec          "example.com.krf"
.Ve
.SS "Example 3.  One zone, \-keyrec option"
.IX Subsection "Example 3. One zone, -keyrec option"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fB\-keyrec\fR option.
.PP
.Vb 5
\&    $ rollinit \-keyrec x\-rrf example.com
\&        roll    "example.com"
\&            zonename        "example.com"
\&            zonefile        "example.com.signed"
\&            keyrec          "x\-rrf"
.Ve
.SS "Example 4.  One zone, \-zonefile and \-keyrec options"
.IX Subsection "Example 4. One zone, -zonefile and -keyrec options"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fB\-zonefile\fR and \fB\-keyrec\fR options.
.PP
.Vb 5
\&    $ rollinit \-zonefile signed\-example \-keyrec example.rrf example.com
\&        roll    "example.com"
\&            zonename        "example.com"
\&            zonefile        "signed\-example"
\&            keyrec          "example.rrf"
.Ve
.SS "Example 5.  One zone, \-skip option"
.IX Subsection "Example 5. One zone, -skip option"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fB\-zonefile\fR and \fB\-keyrec\fR options.
.PP
.Vb 5
\&    $ rollinit \-skip example.com
\&        skip    "example.com"
\&            zonename        "example.com"
\&            zonefile        "example.com.signed"
\&            keyrec          "example.com.krf"
.Ve
.SS "Example 6.  One zone, \-rollrec option"
.IX Subsection "Example 6. One zone, -rollrec option"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fB\-rollrec\fR option.
.PP
.Vb 5
\&    $ rollinit \-rollrec test example.com
\&        roll    "test"
\&            zonename        "example.com"
\&            zonefile        "example.com.signed"
\&            keyrec          "example.com.krf"
.Ve
.SS "Example 7.  Multiple zones, no options"
.IX Subsection "Example 7. Multiple zones, no options"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR several
zones, without any options.
.PP
.Vb 5
\&    $ 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"
.Ve
.SS "Example 8.  Multiple zones, \-zonefile option"
.IX Subsection "Example 8. Multiple zones, -zonefile option"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR several
zones, with the \fB\-zonefile\fR option.
.PP
.Vb 5
\&    $ 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"
.Ve
.SS "Example 9.  Multiple zones, \-keyrec option"
.IX Subsection "Example 9. Multiple zones, -keyrec option"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR several
zones, with the \fB\-keyrec\fR option.
.PP
.Vb 5
\&    $ 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"
.Ve
.SS "Example 10.  Multiple zones, \-zonefile and \-keyrec options"
.IX Subsection "Example 10. Multiple zones, -zonefile and -keyrec options"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR several
zones, with the \fB\-zonefile\fR and \fB\-keyrec\fR options.
.PP
.Vb 5
\&    $ 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"
.Ve
.SS "Example 11.  Single zone, \-zonefile and \-keyrec options with template"
.IX Subsection "Example 11. Single zone, -zonefile and -keyrec options with template"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a single
zone, with the \fB\-zonefile\fR and \fB\-keyrec\fR options.  The options use the
multi-zone \fB=\fR template.
.PP
.Vb 5
\&    $ rollinit \-zonefile Z\-= \-keyrec =.K example.com
\&        roll    "example.com"
\&            zonename        "example.com"
\&            zonefile        "Z\-="
\&            keyrec          "=.K"
.Ve
.PP
This is probably not what is wanted, since it results in the \fIzonefile\fR and
\&\fIkeyrec\fR field values containing the \fB=\fR.
.SS "Example 12.  Multiple zones, \-zonefile and \-keyrec options without template"
.IX Subsection "Example 12. Multiple zones, -zonefile and -keyrec options without template"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR
several zones, with the \fB\-zonefile\fR and \fB\-keyrec\fR options.  The
options do not use the multi-zone \fB=\fR template.
.PP
.Vb 5
\&    $ 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"
.Ve
.PP
This may not be what is wanted, since it results in the same \fIzonefile\fR
and \fIkeyrec\fR fields values for each \fIrollrec\fR.
.SS "Example 13.  Multiple zones, \-rollrec option"
.IX Subsection "Example 13. Multiple zones, -rollrec option"
This example shows the \fIrollrec\fRs generated by giving \fBrollinit\fR several
zones, with the \fB\-rollrec\fR option.  The \fIrollrec\fR names include a space.
.PP
.Vb 5
\&    $ 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"
.Ve
.SS "Example 14.  Multiple zones, \-zg option"
.IX Subsection "Example 14. Multiple zones, -zg option"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a set of
zones, with the \fB\-zg\fR option.
.PP
.Vb 6
\&    $ 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"
.Ve
.SS "Example 15.  One zone, Two zonegroups"
.IX Subsection "Example 15. One zone, Two zonegroups"
This example shows the \fIrollrec\fR generated by giving \fBrollinit\fR a set of
two zonegroups for a single zone.
.PP
.Vb 6
\&    $ 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"
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2006\-2014 SPARTA, Inc.  All rights reserved.
See the COPYING file included with the DNSSEC-Tools package for details.
.SH AUTHOR
.IX Header "AUTHOR"
Wayne Morrison, tewok@tislabs.com
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlsroll\|(1)\fR,
\&\fBrollerd\|(8)\fR,
\&\fBrollchk\|(8)\fR,
\&\fBzonesigner\|(8)\fR
.PP
\&\fBNet::DNS::SEC::Tools::keyrec.pm\|(3)\fR,
\&\fBNet::DNS::SEC::Tools::rollrec.pm\|(3)\fR
.PP
\&\fBfile\-keyrec.pm\|(5)\fR,
\&\fBfile\-rollrec.pm\|(5)\fR