1ROLLINIT(1) User Contributed Perl Documentation ROLLINIT(1)
2
6 rollinit - Create new rollrec records for a DNSSEC-Tools rollrec file.
7
9 rollinit [options] <zonename1> ... <zonenameN>
10
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 The newly generated rollrec entries are written to standard output,
17 unless the -out option is specified.
18 A rollrec entry has this format:
20 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 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 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 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 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 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 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 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 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 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 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 The Boolean display field indicates if blinkenlights should display
95 information about this zone.
96 The maxttl field contains the maximum TTL value from the zone file.
98 The phasestart fields contains the date that the current rollover phase
100 was entered.
101 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 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
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
123 The zonefile and keyrec fields may be given by using the -zonefile and
124 -keyrec options, or default values may be used.
125 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 If -zonefile or -keyrec are specified, then the options values are used
131 in one of two ways:
132 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 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 See the EXAMPLES section for examples of how options are used by
144 rollinit.
145
147 rollinit may be given the following options:
148 -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 -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 -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 -zg zonegroup
164 -zonegroup zonegroup
165 This specifies the value of the zonegroup field. This field is
166 optional.
167 -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 -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 -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 -skip
181 By default, roll records are generated. If this option is given,
182 then skip records will be generated instead.
183 -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 If this option is not given, the new rollrec entries will be
189 written to standard output.
190 -help
192 Display a usage message.
193 -Version
195 Display version information for rollinit and DNSSEC-Tools.
196
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 An info rollrec is shown in the first example. In the interests of
204 space, it is not included in the remaining examples.
205 Example 1. One zone, no options
207 This example shows the rollrec generated by giving rollinit a single
208 zone, without any options.
209 $ rollinit example.com
211 skip "info rollrec"
213 version "2"
214 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 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 $ rollinit -zonefile signed-example example.com
234 roll "example.com"
235 zonename "example.com"
236 zonefile "signed-example"
237 keyrec "example.com.krf"
238 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 $ rollinit -keyrec x-rrf example.com
244 roll "example.com"
245 zonename "example.com"
246 zonefile "example.com.signed"
247 keyrec "x-rrf"
248 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 $ 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 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 $ rollinit -skip example.com
264 skip "example.com"
265 zonename "example.com"
266 zonefile "example.com.signed"
267 keyrec "example.com.krf"
268 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 $ rollinit -rollrec test example.com
274 roll "test"
275 zonename "example.com"
276 zonefile "example.com.signed"
277 keyrec "example.com.krf"
278 Example 7. Multiple zones, no options
280 This example shows the rollrecs generated by giving rollinit several
281 zones, without any options.
282 $ rollinit example1.com example2.com
284 roll "example1.com"
285 zonename "example1.com"
286 zonefile "example1.com.signed"
287 keyrec "example1.com.krf"
288 roll "example2.com"
290 zonename "example2.com"
291 zonefile "example2.com.signed"
292 keyrec "example2.com.krf"
293 Example 8. Multiple zones, -zonefile option
295 This example shows the rollrecs generated by giving rollinit several
296 zones, with the -zonefile option.
297 $ 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 roll "example2.com"
305 zonename "example2.com"
306 zonefile "example2.com-signed"
307 keyrec "example2.com.krf"
308 Example 9. Multiple zones, -keyrec option
310 This example shows the rollrecs generated by giving rollinit several
311 zones, with the -keyrec option.
312 $ 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 roll "example2.com"
320 zonename "example2.com"
321 zonefile "example2.com.signed"
322 keyrec "zone-example2.com-keyrec"
323 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 $ 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 roll "example2.com"
335 zonename "example2.com"
336 zonefile "Z-example2.com"
337 keyrec "example2.comK"
338 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 $ rollinit -zonefile Z-= -keyrec =.K example.com
345 roll "example.com"
346 zonename "example.com"
347 zonefile "Z-="
348 keyrec "=.K"
349 This is probably not what is wanted, since it results in the zonefile
351 and keyrec field values containing the =.
352 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 $ 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 roll "example2.com"
365 zonename "example2.com"
366 zonefile "ex.zone"
367 keyrec "ex.krf"
368 This may not be what is wanted, since it results in the same zonefile
370 and keyrec fields values for each rollrec.
371 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 $ 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 roll "example2.com entry"
383 zonename "example2.com"
384 zonefile "example2.com.signed"
385 keyrec "example2.com.krf"
386 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 $ 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 roll "example2.com"
399 zonename "example2.com"
400 zonefile "example2.com.signed"
401 keyrec "example2.com.krf"
402 zonegroup "example zones"
403 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 $ 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
420 Wayne Morrison, tewok@tislabs.com
421
423 lsroll(1), rollerd(8), rollchk(8), zonesigner(8)
424 Net::DNS::SEC::Tools::keyrec.pm(3), Net::DNS::SEC::Tools::rollrec.pm(3)
426 file-keyrec.pm(5), file-rollrec.pm(5)
428perl v5.36.0 2023-01-19 ROLLINIT(1)