1ROLLERD(1) User Contributed Perl Documentation ROLLERD(1)
2
6 rollerd - DNSSEC-Tools daemon to manage DNSSEC key rollover
7
9 rollerd [-options] -rrfile <rollrec_file>
10
12 The rollerd daemon manages key rollover for zones. rollerd is just a
13 scheduler for zone rollover; it uses zonesigner to perform the actual
14 key generation, zone signing, and key manipulation.
15 rollerd manages both KSK and ZSK rollover, though only one rollover
17 type per zone may take place at a time. Initiation of KSK rollovers
18 takes precedence over the initiation of ZSK rollovers.
19 rollerd uses two methods of key rollover. The Pre-Publish Method of
21 key rollover is used for ZSK key rollovers. The Double Signature
22 Method of key rollover is used for KSK rollovers. These methods are
23 described more fully below.
24 rollerd maintains zone rollover state in files called rollrec files;
26 zone/key mappings are stored in keyrec files. rollerd only modifies
27 rollrec files. For the most part, rollerd does not modify keyrec
28 directly, but relies on zonesigner to update those files as needed.
29 (The exceptions where rollerd modifies keyrec files. At start-up, it
30 will mark each managed zone's keyrec file to indicate the zone is under
31 rollerd's control. During the course of rollover, rollerd will also
32 update a zone's rollover times in its keyrec file.)
33 The administrator may control rollerd with the rollctl command. A
35 large number of commands are available to control and modify rollerd's
36 operation, as well as to retrieve information about rollover and daemon
37 status.
38 The zone administrator will need to update their zone files
40 periodically. If rollerd is managing zones, then problems could arise
41 if modified zones were signed without rollerd's knowledge. To prevent
42 such problems, rollerd can be configured to automatically re-sign a
43 zone when its zonefile is found to be newer than its corresponding
44 signed zonefile. (The files' "last modification" timestamps are
45 compared.) The zone will be re-signed without any other rollover
46 actions taking place, so no new keys will be generated, no key
47 rollovers will occur, and the various rollover timers will be
48 unaffected.
49 rollerd will perform these re-signs by default, but this can be further
51 controlled by the autosign configuration parameter and rollerd's
52 -autosign/-noautosign command line options. If rollerd is configured
53 to not perform automatic re-signing, the administrator can still get
54 this controlled behavior by use of the zonesigner or rollctl commands.
55 If the rollrec file does not exist or is of zero length, rollerd will
57 give an error message and continue running. It will periodically wake
58 up and check for a usable rollrec file. Once it finds the specified
59 rollrec file exists and isn't empty, then it will proceed with normal
60 rollover management.
61 ZSK Rollover Using the Pre-Publish Method
63 The Pre-Publish Method has four phases that are entered when it is time
64 to perform ZSK rollover:
65 1. wait for old zone data to expire from caches
67 2. sign the zone with the KSK and Published ZSK
68 3. wait for old zone data to expire from caches
69 4. adjust keys in keyrec and sign the zone with new Current ZSK
70 rollerd uses the zonesigner command during ZSK rollover phases 2 and 4.
72 zonesigner will generate keys as required and sign the zone during
73 these two phases.
74 The Pre-Publish Method of key rollover is defined in the Step-by-Step
76 DNS Security Operator Guidance Document. See that document for more
77 detailed information.
78 KSK Rollover Using the Double Signature Method
80 The Double Signature Method has seven phases that are entered when it
81 is time to perform KSK rollover:
82 1 - wait for cache data to expire
84 2 - generate a new (published) KSK and load zone
85 3 - wait for the old DNSKEY RRset to expire from caches
86 4 - transfer new keyset to the parent
87 5 - wait for parent to publish DS record
88 6 - wait for cache data to expire
89 7 - roll the KSKs and load the zone
90 This is a modification of the original Double Signature Method. In the
92 original method, the KSK keys were rolled before the new keyset was
93 transferred to the parent. The new method rolls the KSK keys after the
94 parent has published the new DS records and old data has expired for
95 caches. This addresses a potential problem with signing zones during
96 key rollovers.
97 rollerd uses the zonesigner command during KSK rollover phases 2 and 7.
99 zonesigner will generate keys as required and sign the zone during
100 these two phases.
101 Currently, leaving the waiting period in step 5 is handled manually.
103 In step 4, rollerd informs the administrator via email that the zone's
104 keyset must be transferred to its parent in order for rollover to
105 continue. In step 5, after the keyset has been transferred to the
106 parent and the parent has published a new DS record, the administrator
107 uses rollctl to inform rollerd that the DS record has been published
108 and rollover may continue.
109 The Double Signature Method of key rollover is defined in the Step-by-
111 Step DNS Security Operator Guidance Document. See that document for
112 more detailed information.
113 KSK Rollover Using the Double Signature Method and RFC5011
115 RFC5011 describes how remote-validating resolvers must track KSK
116 changes within a zone. If configured for RFC5011 behavior, rollerd and
117 zonesigner add an extra-long period of time between the point a new KSK
118 is created and published and the point where the actual switch to using
119 it takes place. RFC5011 specifies that remote validators should add a
120 "hold-down timer" to the rollover process, such that the new key is not
121 added as a trust-anchor until 30 days have past. Thus, rollerd will
122 wait for 60 days (by default) during phase 3 of the KSK rollover
123 process if the "istrustanchor" field of the rollrec definition has been
124 set to either 1 or "yes". To wait for a different length of time other
125 than 60 days, use the holddowntime field.
126 At this time, the other conventions of RFC5011 are not being followed.
128 Specifically, it's not waiting for a while before removing the old key
129 and it's not adding the revoke bit to the old key after switching.
130 Site-Specific Rollover Actions
132 An administrator can specify site-specific commands to be run during
133 the various rollover phases. The commands can be run in place of the
134 default rollerd rollover actions, or in addition to them. This
135 subsection describes how to make use of site-specific rollover actions.
136 This capability is provided to allow different installations to handle
138 rollover according to their specific needs. For example, it is
139 anticipated that this might be helpful to sites using HSM hardware, or
140 to allow for enhanced reporting to administrators. This has been used
141 with simple test programs to ensure that it actually works. However,
142 it has not yet been used in actual HSM environment or with other
143 production-level software replacements.
144 See the ZSK Rollover Using the Pre-Publish Method and KSK Rollover
146 Using the Double Signature Method sections for descriptions of the
147 default rollover actions.
148 WARNING: This has the potential of being a dangerous capability. Be
150 very careful when setting up and using it. Take care with the site-
151 specific commands to be executed and the permissions and ownership of
152 rollerd and its data files.
153 DNSSEC-Tools Configuration File Changes
155 The DNSSEC-Tools configuration file must be modified to tell rollerd
157 what must be run for the non-default rollover phase actions. Key/value
158 pairs may be set for each rollover phase to control how that phase
159 differs from the default.
160 The value portion of the configuration entry contains the path to the
162 site-specific phase command, along with any arguments it might need.
163 Multiple commands are separated by bangs.
164 The reserved default command tells rollerd to use its normal rollover
166 action for a particular phase. This may be combined with other
167 commands to provide things such as specialized logging or
168 notifications.
169 rollerd will only alter the behavior of a rollover phase if the
171 configuration file contains an entry for that phase. If not, the
172 default action will be taken.
173 For example, this configuration line tells rollerd that for ZSK
175 rollover phase 2, instead of using its normal zonesigner executions it
176 should run the hsm-signer command.
177 prog-zsk2 hsm-signer
179 In this example, this configuration line informs rollerd that when
181 entering KSK rollover phase 1 and ZSK rollover phase 1, it should
182 execute the log-and-mail command, then use the normal rollover action
183 for those phases.
184 prog-ksk1 /usr/local/sbin/log-and-mail mary ! default
186 prog-zsk1 /usr/local/sbin/log-and-mail bob!default
187 The following configuration keys are used for controlling KSK rollover
189 phases: prog-ksk1, prog-ksk2, prog-ksk3, prog-ksk4, prog-ksk5,
190 prog-ksk6, and prog-ksk7,
191 The following configuration keys are used for controlling ZSK rollover
193 phases: prog-zsk1, prog-zsk2, prog-zsk3, and prog-zsk4.
194 The prog-normal configuration key controls the normal, non-rollover
196 state.
197 Site-Specific Commands
199 To be generally useful, the site-specific commands executed by rollerd
201 will be given a standard set of arguments, and a standard set of exit
202 values will be recognized.
203 The standard arguments from rollerd are:
205 1. zonename - Zone to be handled.
206 2. phase - Zone's current rollover phase (e.g., zsk1, ksk6,
207 normal.)
208 3. rollrec name - Zone's entry key in the rollrec file.
209 4. rollrec file - The path to the rollrec file.
210 5. keyrec file - The path to the zone's keyrec file.
211 The prog-phase entry in the configuration file may specify additional
213 options and arguments for a command. These will be included on the
214 execution command line prior to the standard arguments.
215 The standard exit values expected by rollerd are:
217 0. The zone can move to the next rollover phase.
218 This is only applicable to the current command; other
219 commands in this phase's command list must still be run.
220 1. The zone should stay in the current rollover phase.
221 This is not necessarily the result of an error.
222 2. An error was found in the arguments given to the command.
223 3. An error was encountered during execution.
224 If a rollover phase's configuration entry lists multiple commands, they
226 will be executed in the order listed. If any command in that command
227 list fails, processing stops there.
228 The rp-wrapper command shows how a site-specific command may be
230 written. rp-wrapper may be used as a skeleton on which to build a more
231 useful rollover-phase command.
232 Considerations for Site-Specific Commands
234 The following should be taken into consideration when writing a site-
236 specific command for a rollover phase.
237 execution length
239 A phase command should not execute very long. As currently
240 written, rollerd serializes zone rollover. So the longer a phase
241 command takes to execute, the longer it will take to get to the
242 next zone. If a phase command sleeps or actively waits, so to
243 speak, for the next phase timeout, then every zone rollerd manages
244 will be left waiting.
245 follow interface guidelines
247 Follow the standards for arguments and exit values. Not following
248 the standards is likely to negatively affect zone rollover.
249 frequency of command execution
251 If rollerd is operating in its traditional "full list" processing
252 mode, a phase command list will be executed every time rollerd
253 cycles through its zone list and a zone is in that particular
254 command's phase. For example, if <i>prog_zsk1</i> is defined for
255 example.com, that command list will be executed for example.com
256 every time rollerd runs its zone list and finds example.com is in
257 the ZSK phase 1 rollover state. A phase command must take this
258 into account so it doesn't perform its actions more frequently than
259 necessary. This is most likely an issue for the various rollover
260 wait states, and possibly the normal state.
261 If rollerd is operating in the experimental "soon queue" processing
263 mode, a phase command list will be executed for a zone only when a
264 phase change occurs. Since phase changes are time queued, this
265 should not happen more than once per phase. A phase command should
266 take this into account, in case the soon queue is reordered before
267 the zone leaves the queue, or queue timing is relatively swift.
268 This is most likely an issue for the various rollover wait states.
269 WARNING: "soon queue" processing is experimental. Care should be
271 taken when using this processing method, as it may still have some
272 lingering bugs.
273 Zone Reloading
275 rollerd has the opportunity to inform the DNS daemon to reload a zone
276 in KSK phase 2, KSK phase 7, ZSK phase 2, and ZSK phase 4. This is the
277 rollerd's default behavior. However, there are situations where this
278 shouldn't be done, such as for off-line signing.
279 The roll_loadzone field of the DNSSEC-Tools configuration file is a
281 boolean field that overrides the default to force the zone-reload
282 behavior either on or off. This field takes precedence over the
283 default.
284 Similarly, the -noreload option prevents rollerd from requesting a zone
286 reload, and it takes precedence over the roll_loadzone configuration
287 field and the default.
288 rollrec Files
290 The zones to be managed by rollerd are described in a rollrec file.
291 Generally speaking most people will want to use the rollinit command to
292 create an initial rollrec file instead of typing their own from
293 scratch. See the INITIALIZATION AND USAGE section below and the
294 rollinit manual page for details. Each zone's entry contains data
295 needed by rollerd and some data useful to a user. Below is a sample
296 rollrec entry:
297 roll "example.com"
299 zonename "example.com"
300 zonefile "example.com.signed"
301 keyrec "example.com.krf"
302 zonegroup "demo-zones"
303 directory "dir-example.com"
304 kskphase "0"
305 zskphase "3"
306 ksk_rollsecs "1172614842"
307 ksk_rolldate "Tue Feb 27 22:20:42 2007"
308 zsk_rollsecs "1172615087"
309 zsk_rolldate "Tue Feb 27 22:24:47 2007"
310 maxttl "60"
311 display "1"
312 phasestart "Tue Feb 27 22:25:07 2007"
313 # optional records for RFC5011 rolling:
314 istrustanchor "no"
315 holddowntime "60D"
316 The first line gives the rollrec entry's name. The name distinguishes
318 it from other rollrec entries and must be unique. This may be the
319 zone's name, but this is not a requirement. The following lines give
320 the zone's name, the zone's signed zone file, keyrec file, the current
321 rollover phases, the rollover timestamps, and other information. The
322 zone group is optional and allows a set of related zones to be
323 controlled with a single rollctl execution, rather than one execution
324 per zone.
325 If either of the zonefile or keyrec files do not exist, then a "roll"
327 rollrec will be changed into a "skip" rollrec. That record will not be
328 processed.
329 A more detailed explanation may be found in rollrec(5).
331 Directories
333 rollerd's execution directory is either the directory in which it is
334 executed or the directory passed in the -directory command-line option.
335 Any files used by rollerd that were not specified with absolute paths
336 use this directory as their base.
337 A rollrec file's directory field informs rollerd where the zone's files
339 may be found. For that zone, rollerd will move into that directory,
340 then return to its execution directory when it finishes rollover
341 operations for that zone. If the directory value is a relative path,
342 it will be appended to rollerd's execution directory. If the directory
343 value is an absolute path, it will be used as is.
344 Controlling rollerd with rollctl
346 The rollctl command is used to control the behavior of rollerd. A
347 number of commands are available, such as starting or stopping rollover
348 for a selected zone or all zones, turning on or off a GUI rollover
349 display, and halting rollerd execution. The communications path
350 between rollerd and rollctl is operating system-dependent. On Unix-
351 like systems, it is a Unix pipe that should only be writable by the
352 user which runs rollerd. A more detailed explanation of rollctl may be
353 found in rollctl(8).
354 A Note About Files and Filenames
356 There are a number of files and filenames used by rollerd and
357 zonesigner. The user must be aware of the files used by these
358 programs, where the files are located, and where the programs are
359 executed.
360 By default, rollerd will change directory to the DNSSEC-Tools
362 directory, though this may be changed by the -directory option. Any
363 programs started by rollerd, most importantly zonesigner, will run in
364 this same directory. If files and directories referenced by these
365 programs are named with relative paths, those paths must be relative to
366 this directory.
367 The rollrec entry name is used as a key to the rollrec file and to the
369 zone's keyrec file. This entry does not have to be the name of the
370 entry's domain, but it is a very good idea to make it so. Whatever is
371 used for this entry name, the same name must be used for the zone
372 keyrec in that zone's keyrec file.
373 It is probably easiest to store rollrec files, keyrec files, zone
375 files, and key files in a single directory.
376
378 The following steps must be taken to initialize and use rollerd. This
379 assumes that zone files have been created, and that BIND and DNSSEC-
380 Tools have been installed.
381 0. sign zones
383 The zones to be managed by rollerd must be signed. Use zonesigner
384 to create the signed zone files and the keyrec files needed by
385 rollerd. The rollrec file created in the next step must use the
386 keyrec file names and the signed zone file names created here.
387 This step is optional. If it is bypassed, then (in step 4 and
389 later) rollerd will perform the initial key creation and zone
390 signing of your zones using the defaults found in the DNSSEC-Tools
391 configuration file. rollerd determines if it must perform these
392 initial operations by whether it can find the keyrec file for a
393 zone (as specified in the rollrec file. If it can't, it performs
394 the initial operations; if it can, it assumes the zone's initial
395 operations have been performed.
396 1. create rollrec file
398 Before rollerd may be used, a rollrec file must first be created.
399 While this file may be built by hand, the rollinit command was
400 written specifically to build the file.
401 2. select operational parameters
403 A number of rollerd's operational parameters are taken from the
404 DNSSEC-Tools configuration file. However, these may be overridden
405 by command-line options. See the OPTIONS section below for more
406 details. If non-standard parameters are desired to always be used,
407 the appropriate fields in the DNSSEC-Tools configuration file may
408 be modified to use these values.
409 3. install the rollover configuration
411 The complete rollover configuration -- rollerd, rollrec file,
412 DNSSEC-Tools configuration file values, zone files -- should be
413 installed. The appropriate places for these locations are both
414 installation-dependent and operating system-dependent.
415 4. test the rollover configuration
417 The complete rollover configuration should be tested.
418 Edit the zone files so that their zones have short TTL values. A
420 minute TTL should be sufficient. Test rollovers of this speed
421 should only be done in a test environment without the real signed
422 zone.
423 Run the following command:
425 rollerd -rrfile test.rollrec -logfile - -loglevel info -sleep 60
427 This command assumes the test rollrec file is test.rollrec. It
429 writes a fair amount of log messages to the terminal, and checks
430 its queue every 60 seconds. Follow the messages to ensure that the
431 appropriate actions, as required by the Pre-Publish Method, are
432 taking place.
433 5. set rollerd to start at boot
435 Once the configuration is found to work, rollerd should be set to
436 start at system boot. The actual operations required for this step
437 are operating system-dependent.
438 6. reboot and verify
440 The system should be rebooted and the rollerd logfile checked to
441 ensure that rollerd is operating properly.
442
444 There are a number of operational parameters that define how rollerd
445 works. These parameters define things such as the rollrec file, the
446 logging level, and the log file. These parameters can be set in the
447 DNSSEC-Tools configuration file or given as options on the rollerd
448 command line. The command line options override values in the
449 configuration file.
450 The following options are recognized:
452 -alwayssign
454 Tells rollerd to sign the zones that aren't in the middle of being
455 rolled. This allows rollerd to refresh signed zone signatures and
456 allows complete management of zone signing to be taken over by
457 rollerd.
458 The downside to using this option is that all the non-rolling zones
460 will be signed after every sleep, which may be expensive
461 computationally.
462 Note: The zone files are not updated or installed at this time.
464 Manual copying and installation are still needed.
465 -autosign | -noautosign
467 Automatic zone-signing flag. If this is set, then a zone's
468 zonefile will be re-signed (and only re-signed) if it is found to
469 be newer than the corresponding signed zonefile.
470 -directory dir
472 Sets the rollerd execution directory. This must be a valid
473 directory.
474 -display
476 Starts the blinkenlights graphical display program to show the
477 status of zones managed by rollerd.
478 -dtconfig config_file
480 Name of an alternate DNSSEC-Tools configuration file to be
481 processed. If specified, this configuration file is used in place
482 of the normal DNSSEC-Tools configuration file not in addition to
483 it. Also, it will be handled prior to keyrec files, rollrec files,
484 and command-line options.
485 -foreground
487 Run in the foreground and do not fork into a daemon.
488 -logfile log_file
490 Sets the rollerd log file to log_file. This must be a valid
491 logging file, meaning that if log_file already exists, it must be a
492 regular file. The only exceptions to this are if logfile is
493 /dev/stdout, /dev/tty, -. Of these three, using a log_file of - is
494 preferable since Perl will properly convert the - to the process'
495 standard output.
496 -loglevel level
498 Sets rollerd's logging level to level. rollmgr.pm(3) contains a
499 list of the valid logging levels.
500 -noreload
502 Prevents rollerd from telling the DNS daemon to reload zones.
503 -parameters
505 Prints a set of rollerd parameters and then exits. This shows the
506 parameters with which rollerd will execute, but very little
507 parameter validation is performed.
508 -pidfile pid_file
510 Stores the running process PID into pid_file. This defaults to
511 /var/run/rollerd.pid on most systems.
512 -rrfile rollrec_file
514 Name of the rollrec file to be processed. This is the only
515 required "option".
516 -realm realm_name
518 Name of the realm in which rollerd is running. This is for use
519 with the DNSSEC-Tools realms facility as a means of easily
520 identifying different instantiations of rollerd. It is
521 informational only (e.g., ps output and log files) and is not used
522 for anything else.
523 -singlerun
525 Processes all needed steps once and exits. This is not the ideal
526 way to run rollerd, but it is potentially useful for environments
527 where keying material is only available when specific hardware
528 tokens have been made available.
529 The timing between the steps will be potentially longer since the
531 time between rollerd runs is dependent on when rollerd is executed.
532 "cmd" lines must be added to the rollrec file to do particular
533 actions.
534 The following lines should serve as examples:
536 cmd "rollzsk example.com"
538 cmd "rollksk example.com"
539 cmd "dspub example.com" # (for when the parent publishes
540 # the new ksk)
541 The -singlerun option implicitly implies -foreground as well.
543 -sleep sleeptime
545 Sets rollerd's sleep time to sleeptime. The sleep time is the
546 amount of time (in seconds) rollerd waits between processing its
547 rollrec-based queue.
548 -username username
550 username is the user for which the rollerd daemon will be executed.
551 The rollerd process' effective uid will be set to the uid
552 corresponding to username.
553 If username is a username, it must correspond to a valid uid; if it
555 is a uid, it must correspond to a valid username.
556 If rollerd does not have the appropriate O/S magic (e.g., for Unix,
558 installed as setuid program and owned by root) then it will only be
559 able to switch to those users to which the executing user has
560 privilege to switch. This restriction is dependent on the
561 operating system and the manner by which rollerd is installed.
562 When using this option, the target user must have access to the
564 various directories, logs, and data files that rollerd requires to
565 execute. Without this access, proper execution cannot occur.
566 -zsargs arglist
568 Additional zonesigner arguments that will be passed to all
569 zonesigner executions. These arguments will override the
570 corresponding arguments in the DNSSEC-Tools configuration file, and
571 the zones' keyrec files. If a zone's rollrec entry contains a
572 zsargs field, then it will be used instead of those specified by
573 this argument.
574 Given the rollerd argument processing, the new arguments for
576 zonesigner cannot be specified as expected. Instead, the arguments
577 should be given in the following manner. The leading dash should
578 be replaced with an equals sign. If the option takes an argument,
579 the space that would separate the option from the option's argument
580 should also be replaced by an equals sign. If multiple arguments
581 will be passed via -zsargs, quotes must be used to group them into
582 a single argument.
583 rollerd translates these arguments to the appropriate format for
585 zonesigner. These examples should clarify the modifications:
586 normal zonesigner option rollerd -zsargs option
588 ------------------------ ----------------------
589 -nokrfile -zsargs =nokrfile
590 -zskcount 5 -kskcount 3 -zsargs "=zskcount=5 =kskcount=3"
591 -Version
593 Displays the version information for rollerd and the DNSSEC-Tools
594 package.
595 -help
597 Display a usage message.
598 -verbose
600 Verbose output will be given.
601
603 rollerd uses the rndc command to communicate with the BIND named
604 daemon. Therefore, it assumes that appropriate measures have been
605 taken so that this communication is possible.
606
608 The following problems (or potential problems) are known:
609 - Any process that can write to the rollover socket can send commands
611 to rollerd. This is probably not a Good Thing.
612
614 Copyright 2005-2014 SPARTA, Inc. All rights reserved. See the COPYING
615 file included with the DNSSEC-Tools package for details.
616
618 Wayne Morrison, tewok@tislabs.com
619
621 blinkenlights(8), dtrealms(8), named(8), rndc(8), rp-wrapper(8),
622 rollchk(8), rollctl(8), rollinit(8), zonesigner(8)
623 Net::DNS::SEC::Tools::conf.pm(3), Net::DNS::SEC::Tools::defaults.pm(3),
625 Net::DNS::SEC::Tools::keyrec.pm(3),
626 Net::DNS::SEC::Tools::rolllog.pm(3),
627 Net::DNS::SEC::Tools::rollmgr.pm(3),
628 Net::DNS::SEC::Tools::rollrec.pm(3)
629 rollrec(5)
631perl v5.36.0 2023-01-19 ROLLERD(1)