.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "ROLLINIT 1p" .TH ROLLINIT 1p "2012-06-21" "perl v5.14.2" "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] ... .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 \s-1ZONEFILE\s0 And \s-1KEYREC\s0 \s-1FIELDS\s0 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. This field is optional and \fBrollinit\fR only sets it if the \fI\-zonegroup\fR option is specified. (While this is using the term \*(L"zone\*(R", 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 \*(L"phase\*(R" will also include \*(L"err\*(R" and \*(L"fatal\*(R" messages. .PP The \fIkskphase\fR and \fIzskphase\fR fields indicate the rollover phase for the zone's \s-1KSK\s0 and \s-1ZSK\s0 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 \s-1KSK\s0 rollover started. If the values are a blank and zero, respectively, then the zone is not in \s-1KSK\s0 rollover. .PP The \fIzsk_rolldate\fR and \fIzsk_rollsecs\fR fields indicate when \s-1ZSK\s0 rollover started. If the values are a blank and zero, respectively, then the zone is not in \s-1ZSK\s0 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 \s-1TTL\s0 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 \s-1KSK\s0 keys in a manner compliant with any remote validating resolver using the \s-1KSK\s0 as a trust-anchor. If set to \*(L"yes\*(R" then 60 days will be the minimum wait time during phase 3 of \s-1KSK\s0 rolling to ensure remote validators can properly follow the steps needed as specified by \s-1RFC5011\s0. The 60\-day default can be changed via the \fBholddowntime\fR field. .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 \s-1EXAMPLES\s0 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 \s-1ZONEFILE\s0 And \s-1KEYREC\s0 \s-1FIELDS\s0 and \s-1EXAMPLES\s0 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 \s-1ZONEFILE\s0 And \s-1KEYREC\s0 \s-1FIELDS\s0 and \s-1EXAMPLES\s0 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 \s-1ZONEFILE\s0 And \s-1KEYREC\s0 \s-1FIELDS\s0 and \s-1EXAMPLES\s0 sections for more details. .IP "\fB\-zg zonegroup\fR" 4 .IX Item "-zg zonegroup" 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. .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 10 \& $ 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" .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 .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2006\-2012 \s-1SPARTA\s0, Inc. All rights reserved. See the \s-1COPYING\s0 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" \&\fB\f(BIlsroll\fB\|(1)\fR, \&\fB\f(BIrollerd\fB\|(8)\fR, \&\fB\f(BIrollchk\fB\|(8)\fR, \&\fB\f(BIzonesigner\fB\|(8)\fR .PP \&\fB\f(BINet::DNS::SEC::Tools::keyrec.pm\fB\|(3)\fR, \&\fB\f(BINet::DNS::SEC::Tools::rollrec.pm\fB\|(3)\fR .PP \&\fB\f(BIfile\-keyrec.pm\fB\|(5)\fR, \&\fB\f(BIfile\-rollrec.pm\fB\|(5)\fR