1ROLLINIT(1)           User Contributed Perl Documentation          ROLLINIT(1)
2
3
4

NAME

6       rollinit - Create new rollrec records for a DNSSEC-Tools rollrec file.
7

SYNOPSIS

9         rollinit [options] <zonename1> ... <zonenameN>
10

DESCRIPTION

12       rollinit creates new rollrec entries for a rollrec file.  This rollrec
13       file will be used by rollerd to manage key rollover for the named
14       zones.
15
16       The newly generated rollrec entries are written to standard output,
17       unless the -out option is specified.
18
19       A rollrec entry has this format:
20
21           roll "example.com"
22               zonename        "example.com"
23               zonefile        "example.com.signed"
24               keyrec          "example.com.krf"
25               zonegroup       "example-zones"
26               kskphase        "0"
27               zskphase        "0"
28               administrator   "bob@bobhost.example.com"
29               directory       "/var/dns/zones/example.com"
30               loglevel        "phase"
31               ksk_rolldate    " "
32               ksk_rollsecs    "0"
33               zsk_rolldate    " "
34               zsk_rollsecs    "0"
35               maxttl          "604800"
36               display         "1"
37               phasestart      "Mon Jan 9 16:00:00 2006"
38               # optional records for RFC5011 rolling:
39               istrustanchor   "no"
40               holddowntime    "60D"
41
42       The keywords roll and skip indicate whether rollerd should process or
43       ignore a particular rollrec entry.  roll records are created by
44       default; skip entries are created if the -skip option is specified.
45
46       The roll line has a name which is used to distinguish it from all other
47       rollrec entries in the file.  The zonename field is set to the name of
48       the zone.  These two data are often the same, but this is not required.
49       rollinit will set them to the same value, unless the -rollrec option is
50       used.
51
52       The zonefile and keyrec fields are set according to command-line
53       options and arguments.  The manner of generating the rollrec's actual
54       values is a little complex and is described in the ZONEFILE And KEYREC
55       FIELDS section below.
56
57       The zonegroup field is used to associate a set of rollrecs together, so
58       they can be controlled by a single rollctl -group command.  Multiple
59       zonegroups may be specified in a comma-separated list.  Leading and
60       trailing whitespace will be deleted, but internal whitespace is
61       allowed.  This field is optional and rollinit only sets it if the
62       -zonegroup option is specified.  (While this is using the term "zone",
63       it is actually referring to the name of the rollrec entries.)
64
65       The administrator field is set to the email address of the person (or
66       person, if the address is actually a mailing list) considered to be the
67       responsible person for the zone.
68
69       The directory field is set to the directory that contains the the files
70       for the zone.  These files include the zone file, the signed zone file,
71       and the keyrec file.
72
73       The loglevel field is set to the level of log messages that rollerd
74       should produce for this zone.  The log level includes those messages at
75       a greater priority to the specified level, so a level of "phase" will
76       also include "err" and "fatal" messages.
77
78       The kskphase and zskphase fields indicate the rollover phase for the
79       zone's KSK and ZSK keys.  The value 0 indicates that the zone is in
80       normal operation (non-rollover) for that key type.  A non-zero phase
81       (1-7 for KSKs; 1-4 for ZSKs) indicates that the zone is in the process
82       of rolling the keys.  Only one of these fields should ever be non-zero
83       at a particular time.  If both are zero, then no rollover operations
84       are taking place.
85
86       The ksk_rolldate and ksk_rollsecs fields indicate when KSK rollover
87       started.  If the values are a blank and zero, respectively, then the
88       zone is not in KSK rollover.
89
90       The zsk_rolldate and zsk_rollsecs fields indicate when ZSK rollover
91       started.  If the values are a blank and zero, respectively, then the
92       zone is not in ZSK rollover.
93
94       The Boolean display field indicates if blinkenlights should display
95       information about this zone.
96
97       The maxttl field contains the maximum TTL value from the zone file.
98
99       The phasestart fields contains the date that the current rollover phase
100       was entered.
101
102       rollrec files also have the zsargs field that holds user-specified
103       options for zonesigner.  This field is set during rollerd execution
104       when the administrator determines that some zone fields should be
105       modified.  It is not an initial rollrec field and consequently cannot
106       be specified by rollinit.
107
108       The istrustanchor field specifies whether to roll the KSK keys in a
109       manner compliant with any remote validating resolver using the KSK as a
110       trust-anchor.  If set to "yes" then 60 days will be the minimum wait
111       time during phase 3 of KSK rolling to ensure remote validators can
112       properly follow the steps needed as specified by RFC5011.  The 60-day
113       default can be changed via the holddowntime field.
114

INFO ROLLRECS

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

ZONEFILE and KEYREC FIELDS

123       The zonefile and keyrec fields may be given by using the -zonefile and
124       -keyrec options, or default values may be used.
125
126       The default values use the rollrec's zone name, taken from the command
127       line, as a base.  .signed is appended to the zone name for the zone
128       file; .krf is appended to the zone name for the keyrec file.
129
130       If -zonefile or -keyrec are specified, then the options values are used
131       in one of two ways:
132
133       1.  A single zone name is given on the command line.
134           The option values for -zonefile and/or -keyrec are used for the
135           actual rollrec fields.
136
137       2.  Multiple zone names are given on the command line.
138           The option values for -zonefile and/or -keyrec are used as
139           templates for the actual rollrec fields.  The option values must
140           contain the string =.  This string is replaced by the zone whose
141           rollrec is being created.
142
143       See the EXAMPLES section for examples of how options are used by
144       rollinit.
145

OPTIONS

147       rollinit may be given the following options:
148
149       -rollrec rollrec-name
150           This specifies the name of the rollrec record.  This value may
151           contain spaces.  If this option is not specified, it will be set to
152           the same value as the zonename field.  See the ZONEFILE And KEYREC
153           FIELDS and EXAMPLES sections for more details.
154
155       -zonefile zonefile
156           This specifies the value of the zonefile field.  See the ZONEFILE
157           And KEYREC FIELDS and EXAMPLES sections for more details.
158
159       -keyrec keyrec-file
160           This specifies the value of the keyrec field.  See the ZONEFILE And
161           KEYREC FIELDS and EXAMPLES sections for more details.
162
163       -zg zonegroup
164       -zonegroup zonegroup
165           This specifies the value of the zonegroup field.  This field is
166           optional.
167
168       -admin
169           This specifies the value of the administrator field.  If it is not
170           given, an administrator field will not be included for the record.
171
172       -directory
173           This specifies the value of the directory field.  If it is not
174           given, a directory field will not be included for the record.
175
176       -loglevel
177           This specifies the value of the loglevel field.  If it is not
178           given, a loglevel field will not be included for the record.
179
180       -skip
181           By default, roll records are generated.  If this option is given,
182           then skip records will be generated instead.
183
184       -out output-file
185           The new rollrec entries will be appended to output-file.  The file
186           will be created if it does not exist.
187
188           If this option is not given, the new rollrec entries will be
189           written to standard output.
190
191       -help
192           Display a usage message.
193
194       -Version
195           Display version information for rollinit and DNSSEC-Tools.
196

EXAMPLES

198       The following options should make clear how rollinit deals with options
199       and the new rollrecs.  Example 1 will show the complete new rollrec
200       record.  For the sake of brevity, the remaining examples will only show
201       the newly created zonefile and keyrec records.
202
203       An info rollrec is shown in the first example.  In the interests of
204       space, it is not included in the remaining examples.
205
206   Example 1.  One zone, no options
207       This example shows the rollrec generated by giving rollinit a single
208       zone, without any options.
209
210           $ rollinit example.com
211
212               skip    "info rollrec"
213                   version         "2"
214
215               roll    "example.com"
216                   zonename        "example.com"
217                   zonefile        "example.com.signed"
218                   keyrec          "example.com.krf"
219                   kskphase        "0"
220                   zskphase        "0"
221                   ksk_rolldate    " "
222                   ksk_rollsecs    "0"
223                   zsk_rolldate    " "
224                   zsk_rollsecs    "0"
225                   maxttl          "0"
226                   display         "1"
227                   phasestart      "new"
228
229   Example 2.  One zone, -zonefile option
230       This example shows the rollrec generated by giving rollinit a single
231       zone, with the -zonefile option.
232
233           $ rollinit -zonefile signed-example example.com
234               roll    "example.com"
235                   zonename        "example.com"
236                   zonefile        "signed-example"
237                   keyrec          "example.com.krf"
238
239   Example 3.  One zone, -keyrec option
240       This example shows the rollrec generated by giving rollinit a single
241       zone, with the -keyrec option.
242
243           $ rollinit -keyrec x-rrf example.com
244               roll    "example.com"
245                   zonename        "example.com"
246                   zonefile        "example.com.signed"
247                   keyrec          "x-rrf"
248
249   Example 4.  One zone, -zonefile and -keyrec options
250       This example shows the rollrec generated by giving rollinit a single
251       zone, with the -zonefile and -keyrec options.
252
253           $ rollinit -zonefile signed-example -keyrec example.rrf example.com
254               roll    "example.com"
255                   zonename        "example.com"
256                   zonefile        "signed-example"
257                   keyrec          "example.rrf"
258
259   Example 5.  One zone, -skip option
260       This example shows the rollrec generated by giving rollinit a single
261       zone, with the -zonefile and -keyrec options.
262
263           $ rollinit -skip example.com
264               skip    "example.com"
265                   zonename        "example.com"
266                   zonefile        "example.com.signed"
267                   keyrec          "example.com.krf"
268
269   Example 6.  One zone, -rollrec option
270       This example shows the rollrec generated by giving rollinit a single
271       zone, with the -rollrec option.
272
273           $ rollinit -rollrec test example.com
274               roll    "test"
275                   zonename        "example.com"
276                   zonefile        "example.com.signed"
277                   keyrec          "example.com.krf"
278
279   Example 7.  Multiple zones, no options
280       This example shows the rollrecs generated by giving rollinit several
281       zones, without any options.
282
283           $ rollinit example1.com example2.com
284               roll    "example1.com"
285                   zonename        "example1.com"
286                   zonefile        "example1.com.signed"
287                   keyrec          "example1.com.krf"
288
289               roll    "example2.com"
290                   zonename        "example2.com"
291                   zonefile        "example2.com.signed"
292                   keyrec          "example2.com.krf"
293
294   Example 8.  Multiple zones, -zonefile option
295       This example shows the rollrecs generated by giving rollinit several
296       zones, with the -zonefile option.
297
298           $ rollinit -zonefile =-signed example1.com example2.com
299               roll    "example1.com"
300                   zonename        "example1.com"
301                   zonefile        "example1.com-signed"
302                   keyrec          "example1.com.krf"
303
304               roll    "example2.com"
305                   zonename        "example2.com"
306                   zonefile        "example2.com-signed"
307                   keyrec          "example2.com.krf"
308
309   Example 9.  Multiple zones, -keyrec option
310       This example shows the rollrecs generated by giving rollinit several
311       zones, with the -keyrec option.
312
313           $ rollinit -keyrec zone-=-keyrec example1.com example2.com
314               roll    "example1.com"
315                   zonename        "example1.com"
316                   zonefile        "example1.com.signed"
317                   keyrec          "zone-example1.com-keyrec"
318
319               roll    "example2.com"
320                   zonename        "example2.com"
321                   zonefile        "example2.com.signed"
322                   keyrec          "zone-example2.com-keyrec"
323
324   Example 10.  Multiple zones, -zonefile and -keyrec options
325       This example shows the rollrecs generated by giving rollinit several
326       zones, with the -zonefile and -keyrec options.
327
328           $ rollinit -zonefile Z-= -keyrec =K example1.com example2.com
329               roll    "example1.com"
330                   zonename        "example1.com"
331                   zonefile        "Z-example1.com"
332                   keyrec          "example1.comK"
333
334               roll    "example2.com"
335                   zonename        "example2.com"
336                   zonefile        "Z-example2.com"
337                   keyrec          "example2.comK"
338
339   Example 11.  Single zone, -zonefile and -keyrec options with template
340       This example shows the rollrec generated by giving rollinit a single
341       zone, with the -zonefile and -keyrec options.  The options use the
342       multi-zone = template.
343
344           $ rollinit -zonefile Z-= -keyrec =.K example.com
345               roll    "example.com"
346                   zonename        "example.com"
347                   zonefile        "Z-="
348                   keyrec          "=.K"
349
350       This is probably not what is wanted, since it results in the zonefile
351       and keyrec field values containing the =.
352
353   Example 12.  Multiple zones, -zonefile and -keyrec options without template
354       This example shows the rollrecs generated by giving rollinit several
355       zones, with the -zonefile and -keyrec options.  The options do not use
356       the multi-zone = template.
357
358           $ rollinit -zonefile ex.zone -keyrec ex.krf example1.com example2.com
359               roll    "example1.com"
360                   zonename        "example1.com"
361                   zonefile        "ex.zone"
362                   keyrec          "ex.krf"
363
364               roll    "example2.com"
365                   zonename        "example2.com"
366                   zonefile        "ex.zone"
367                   keyrec          "ex.krf"
368
369       This may not be what is wanted, since it results in the same zonefile
370       and keyrec fields values for each rollrec.
371
372   Example 13.  Multiple zones, -rollrec option
373       This example shows the rollrecs generated by giving rollinit several
374       zones, with the -rollrec option.  The rollrec names include a space.
375
376           $ rollinit -rollrec "= entry" example1.com example2.com
377               roll    "example1.com entry"
378                   zonename        "example1.com"
379                   zonefile        "example1.com.signed"
380                   keyrec          "example1.com.krf"
381
382               roll    "example2.com entry"
383                   zonename        "example2.com"
384                   zonefile        "example2.com.signed"
385                   keyrec          "example2.com.krf"
386
387   Example 14.  Multiple zones, -zg option
388       This example shows the rollrec generated by giving rollinit a set of
389       zones, with the -zg option.
390
391           $ rollinit -zg "example zones" example1.com example2.com
392               roll    "example1.com"
393                   zonename        "example1.com"
394                   zonefile        "example1.com.signed"
395                   keyrec          "example1.com.krf"
396                   zonegroup       "example zones"
397
398               roll    "example2.com"
399                   zonename        "example2.com"
400                   zonefile        "example2.com.signed"
401                   keyrec          "example2.com.krf"
402                   zonegroup       "example zones"
403
404   Example 15.  One zone, Two zonegroups
405       This example shows the rollrec generated by giving rollinit a set of
406       two zonegroups for a single zone.
407
408           $ rollinit -zg "customers, paid up" example.com
409               roll    "example1.com"
410                   zonename        "example.com"
411                   zonefile        "example.com.signed"
412                   keyrec          "example.com.krf"
413                   zonegroup       "customers, paid up"
414
416       Copyright 2006-2014 SPARTA, Inc.  All rights reserved.  See the COPYING
417       file included with the DNSSEC-Tools package for details.
418

AUTHOR

420       Wayne Morrison, tewok@tislabs.com
421

SEE ALSO

423       lsroll(1), rollerd(8), rollchk(8), zonesigner(8)
424
425       Net::DNS::SEC::Tools::keyrec.pm(3), Net::DNS::SEC::Tools::rollrec.pm(3)
426
427       file-keyrec.pm(5), file-rollrec.pm(5)
428
429
430
431perl v5.36.0                      2022-07-21                       ROLLINIT(1)
Impressum