--- name: "rollinit" section: "1p" platform: "linux" package: "dnssec-tools" version: "2.2.3-16" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/rollinit" --- # rollinit(1p) Create new rollrec records for a DNSSEC-Tools rollrec file. ## NAME rollinit - Create new rollrec records for a DNSSEC-Tools rollrec file. ## SYNOPSIS ``` rollinit [options] ... ``` ## 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 *rollrec*s 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 *rollrec*s. 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 *rollrec*s 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 *rollrec*s 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 *rollrec*s 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 *rollrec*s 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 *rollrec*s 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 *rollrec*s 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 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)**