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 handles
13 both KSK and ZSK rollover, though only one rollover may take place at a
14 time. Initiation of KSK rollovers takes precedence over the initiation
15 of ZSK rollovers. The Pre-Publish Method of key rollover is used for
16 ZSK key rollovers. The Double Signature Method of key rollover is used
17 for KSK rollovers. rollerd maintains zone rollover state in files
18 called rollrec files. The administrator may control rollerd with the
19 rollctl command. These are described in their own sections below.
20 ZSK Rollover Using the Pre-Publish Method
22 The Pre-Publish Method has four phases that are entered when it is time
23 to perform ZSK rollover:
24 1. wait for old zone data to expire from caches
26 2. sign the zone with the KSK and Published ZSK
27 3. wait for old zone data to expire from caches
28 4. adjust keys in keyrec and sign the zone with new Current ZSK
29 rollerd uses the zonesigner command during ZSK rollover phases 2 and 4.
31 zonesigner will generate keys as required and sign the zone during
32 these two phases.
33 The Pre-Publish Method of key rollover is defined in the Step-by-Step
35 DNS Security Operator Guidance Document. See that document for more
36 detailed information.
37 KSK Rollover Using the Double Signature Method
39 The Double Signature Method has seven phases that are entered when it
40 is time to perform KSK rollover:
41 1. wait for old zone data to expire from caches
43 2. generate a new (published) KSK
44 3. wait for the old DNSKEY RRset to expire from caches
45 4. roll the KSKs
46 5. transfer new keyset to the parent
47 6. wait for parent to publish the new DS record
48 7. reload the zone
49 rollerd uses the zonesigner command during KSK rollover phases 2 and 4.
51 zonesigner will generate keys as required and sign the zone during
52 these two phases.
53 Currently, step 6 is handled manually. In step 5, rollerd informs the
55 administrator via email that the zone's keyset must be transferred to
56 its parent in order for rollover to continue. In step 6, after the
57 keyset has been transferred to the parent and the parent has published
58 a new DS record, the administrator uses rollctl to inform rollerd that
59 the DS record has been published and rollover may continue.
60 The Double Signature Method of key rollover is defined in the Step-by-
62 Step DNS Security Operator Guidance Document. See that document for
63 more detailed information.
64 KSK Rollover Using the Double Signature Method and RFC5011
66 RFC5011 describes how remote-validating resolvers must track KSK
67 changes within a zone. If configured for RFC5011 behavior, rollerd and
68 zonesigner add an extra-long period of time between the point a new KSK
69 is created and published and the point where the actual switch to using
70 it takes place. RFC5011 specifies that remote validators should add a
71 "hold-down timer" to the rollover process, such that the new key is not
72 added as a trust-anchor until 30 days have past. Thus, rollerd will
73 wait for 60 days (by default) during phase 3 of the KSK rollover
74 process if the "istrustanchor" field of the rollrec definition has been
75 set to either 1 or "yes". To wait for a different length of time other
76 than 60 days, use the holddowntime field.
77 At this time, the other conventions of RFC5011 are not being followed.
79 Specifically, it's not waiting for a while before removing the old key
80 and it's not adding the revoke bit to the old key after switching.
81 Zone Reloading
83 rollerd has the opportunity to inform the DNS daemon to reload a zone
84 in KSK phase 2, KSK phase 7, ZSK phase 2, and ZSK phase 4. This is the
85 rollerd's default behavior. However, there are situations where this
86 shouldn't be done, such as for off-line signing.
87 The roll_loadzone field of the DNSSEC-Tools configuration file is a
89 boolean field that overrides the default to force the zone-reload
90 behavior either on or off. This field takes precedence over the
91 default.
92 Similarly, the -noreload option prevents rollerd from requesting a zone
94 reload, and it takes precedence over the roll_loadzone configuration
95 field and the default.
96 rollrec Files
98 The zones to be managed by rollerd are described in a rollrec file.
99 Generally speaking most people will want to use the rollinit command to
100 create an initial rollrec file instead of typing their own from
101 scratch. See the INITIALIZATION AND USAGE section below and the
102 rollinit manual page for details. Each zone's entry contains data
103 needed by rollerd and some data useful to a user. Below is a sample
104 rollrec entry:
105 roll "example.com"
107 zonename "example.com"
108 zonefile "example.com.signed"
109 keyrec "example.com.krf"
110 directory "dir-example.com"
111 kskphase "0"
112 zskphase "3"
113 ksk_rollsecs "1172614842"
114 ksk_rolldate "Tue Feb 27 22:20:42 2007"
115 zsk_rollsecs "1172615087"
116 zsk_rolldate "Tue Feb 27 22:24:47 2007"
117 maxttl "60"
118 display "1"
119 phasestart "Tue Feb 27 22:25:07 2007"
120 # optional records for RFC5011 rolling:
121 istrustanchor "no"
122 holddowntime "60D"
123 The first line gives the rollrec entry's name. The name distinguishes
125 it from other rollrec entries and must be unique. This may be the
126 zone's name, but this is not a requirement. The following lines give
127 the zone's name, the zone's signed zone file, keyrec file, the current
128 rollover phases, the rollover timestamps, and other information.
129 If either of the zonefile or keyrec files do not exist, then a "roll"
131 rollrec will be changed into a "skip" rollrec. That record will not be
132 processed.
133 A more detailed explanation may be found in rollrec(5).
135 Directories
137 rollerd's execution directory is either the directory in which it is
138 executed or the directory passed in the -directory command-line option.
139 Any files used by rollerd that were not specified with absolute paths
140 use this directory as their base.
141 A rollrec file's directory field informs rollerd where the zone's files
143 may be found. For that zone, rollerd will move into that directory,
144 then return to its execution directory when it finishes rollover
145 operations for that zone. If the directory value is a relative path,
146 it will be appended to rollerd's execution directory. If the directory
147 value is an absolute path, it will be used as is.
148 Controlling rollerd with rollctl
150 The rollctl command is used to control the behavior of rollerd. A
151 number of commands are available, such as starting or stopping rollover
152 for a selected zone or all zones, turning on or off a GUI rollover
153 display, and halting rollerd execution. The communications path
154 between rollerd and rollctl is operating system-dependent. On Unix-
155 like systems, it is a Unix pipe that should only be writable by the
156 user which runs rollerd. A more detailed explanation of rollctl may be
157 found in rollctl(8).
158 A Note About Files and Filenames
160 There are a number of files and filenames used by rollerd and
161 zonesigner. The user must be aware of the files used by these
162 programs, where the files are located, and where the programs are
163 executed.
164 By default, rollerd will change directory to the DNSSEC-Tools
166 directory, though this may be changed by the -directory option. Any
167 programs started by rollerd, most importantly zonesigner, will run in
168 this same directory. If files and directories referenced by these
169 programs are named with relative paths, those paths must be relative to
170 this directory.
171 The rollrec entry name is used as a key to the rollrec file and to the
173 zone's keyrec file. This entry does not have to be the name of the
174 entry's domain, but it is a very good idea to make it so. Whatever is
175 used for this entry name, the same name must be used for the zone
176 keyrec in that zone's keyrec file.
177 It is probably easiest to store rollrec files, keyrec files, zone
179 files, and key files in a single directory.
180
182 The following steps must be taken to initialize and use rollerd. This
183 assumes that zone files have been created, and that BIND and DNSSEC-
184 Tools have been installed.
185 0. sign zones
187 The zones to be managed by rollerd must be signed. Use zonesigner
188 to create the signed zone files and the keyrec files needed by
189 rollerd. The rollrec file created in the next step must use the
190 keyrec file names and the signed zone file names created here.
191 This step is optional. If it is bypassed, then (in step 4 and
193 later) rollerd will perform the initial key creation and zone
194 signing of your zones using the defaults found in the DNSSEC-Tools
195 configuration file. rollerd determines if it must perform these
196 initial operations by whether it can find the keyrec file for a
197 zone (as specified in the rollrec file. If it can't, it performs
198 the initial operations; if it can, it assumes the zone's initial
199 operations have been performed.
200 1. create rollrec file
202 Before rollerd may be used, a rollrec file must first be created.
203 While this file may be built by hand, the rollinit command was
204 written specifically to build the file.
205 2. select operational parameters
207 A number of rollerd's operational parameters are taken from the
208 DNSSEC-Tools configuration file. However, these may be overridden
209 by command-line options. See the OPTIONS section below for more
210 details. If non-standard parameters are desired to always be used,
211 the appropriate fields in the DNSSEC-Tools configuration file may
212 be modified to use these values.
213 3. install the rollover configuration
215 The complete rollover configuration -- rollerd, rollrec file,
216 DNSSEC-Tools configuration file values, zone files -- should be
217 installed. The appropriate places for these locations are both
218 installation-dependent and operating system-dependent.
219 4. test the rollover configuration
221 The complete rollover configuration should be tested.
222 Edit the zone files so that their zones have short TTL values. A
224 minute TTL should be sufficient. Test rollovers of this speed
225 should only be done in a test environment without the real signed
226 zone.
227 Run the following command:
229 rollerd -rrfile test.rollrec -logfile - -loglevel info -sleep 60
231 This command assumes the test rollrec file is test.rollrec. It
233 writes a fair amount of log messages to the terminal, and checks
234 its queue every 60 seconds. Follow the messages to ensure that the
235 appropriate actions, as required by the Pre-Publish Method, are
236 taking place.
237 5. set rollerd to start at boot
239 Once the configuration is found to work, rollerd should be set to
240 start at system boot. The actual operations required for this step
241 are operating system-dependent.
242 6. reboot and verify
244 The system should be rebooted and the rollerd logfile checked to
245 ensure that rollerd is operating properly.
246
248 There are a number of operational parameters that define how rollerd
249 works. These parameters define things such as the rollrec file, the
250 logging level, and the log file. These parameters can be set in the
251 DNSSEC-Tools configuration file or given as options on the rollerd
252 command line. The command line options override values in the
253 configuration file.
254 The following options are recognized:
256 -alwayssign
258 Tells rollerd to sign the zones that aren't in the middle of being
259 rolled. This allows rollerd to refresh signed zone signatures and
260 allows complete management of zone signing to be taken over by
261 rollerd.
262 The downside to using this option is that all the non-rolling zones
264 will be signed after every sleep, which may be expensive
265 computationally.
266 Note: The zone files are not updated or installed at this time.
268 Manual copying and installation is still needed.
269 Note: During ZSK and KSK rolling phases 1 and 3 the zone will not
271 be signed since it is critical to wait for cache timeouts during
272 this phase of rolling keys.
273 -directory dir
275 Sets the rollerd execution directory. This must be a valid
276 directory.
277 -display
279 Starts the blinkenlights graphical display program to show the
280 status of zones managed by rollerd.
281 -dtconfig config_file
283 Name of an alternate DNSSEC-Tools configuration file to be
284 processed. If specified, this configuration file is used in place
285 of the normal DNSSEC-Tools configuration file not in addition to
286 it. Also, it will be handled prior to keyrec files, rollrec files,
287 and command-line options.
288 -foreground
290 Run in the foreground and do not fork into a daemon.
291 -logfile log_file
293 Sets the rollerd log file to log_file. This must be a valid
294 logging file, meaning that if log_file already exists, it must be a
295 regular file. The only exceptions to this are if logfile is
296 /dev/stdout, /dev/tty, -. Of these three, using a log_file of - is
297 preferable since Perl will properly convert the - to the process'
298 standard output.
299 -loglevel level
301 Sets rollerd's logging level to level. rollmgr.pm(3) contains a
302 list of the valid logging levels.
303 -noreload
305 Prevents rollerd from telling the DNS daemon to reload zones.
306 -parameters
308 Prints a set of rollerd parameters and then exits. This shows the
309 parameters with which rollerd will execute, but very little
310 parameter validation is performed.
311 -pidfile pid_file
313 Stores the running process PID into pid_file. This defaults to
314 /var/run/rollerd.pid on most systems.
315 -rrfile rollrec_file
317 Name of the rollrec file to be processed. This is the only
318 required "option".
319 -singlerun
321 Processes all needed steps once and exits. This is not the ideal
322 way to run rollerd, but it is potentially useful for environments
323 where keying material is only available when specific hardware
324 tokens have been made available.
325 The timing between the steps will be potentially longer since the
327 time between rollerd runs is dependent on when rollerd is executed.
328 "cmd" lines must be added to the rollrec file to do particular
329 actions.
330 The following lines should serve as examples:
332 cmd "rollzsk example.com"
334 cmd "rollksk example.com"
335 cmd "dspub example.com" # (for when the parent publishes
336 # the new ksk)
337 The -singlerun option implicitly implies -foreground as well.
339 -sleep sleeptime
341 Sets rollerd's sleep time to sleeptime. The sleep time is the
342 amount of time (in seconds) rollerd waits between processing its
343 rollrec-based queue.
344 -username username
346 username is the user for which the rollerd daemon will be executed.
347 The rollerd process' effective uid will be set to the uid
348 corresponding to username.
349 If username is a username, it must correspond to a valid uid; if it
351 is a uid, it must correspond to a valid username.
352 If rollerd does not have the appropriate O/S magic (e.g., for Unix,
354 installed as setuid program and owned by root) then it will only be
355 able to switch to those users to which the executing user has
356 privilege to switch. This restriction is dependent on the
357 operating system and the manner by which rollerd is installed.
358 When using this option, the target user must have access to the
360 various directories, logs, and data files that rollerd requires to
361 execute. Without this access, proper execution cannot occur.
362 -Version
364 Displays the version information for rollerd and the DNSSEC-Tools
365 package.
366 -help
368 Display a usage message.
369 -verbose
371 Verbose output will be given.
372
374 rollerd uses the rndc command to communicate with the BIND named
375 daemon. Therefore, it assumes that appropriate measures have been
376 taken so that this communication is possible.
377
379 The following problems (or potential problems) are known:
380 - Any process that can write to the rollover socket can send commands
382 to rollerd. This is probably not a Good Thing.
383
385 The following potential enhancements may be made:
386 - It'd be good to base rollerd's sleep time on when the next
388 operation must take place, rather than a simple seconds count.
389
391 Copyright 2005-2011 SPARTA, Inc. All rights reserved. See the COPYING
392 file included with the DNSSEC-Tools package for details.
393
395 Wayne Morrison, tewok@users.sourceforge.net
396
398 blinkenlights(8), named(8), rndc(8), rollchk(8), rollctl(8),
399 rollinit(8), zonesigner(8)
400 Net::DNS::SEC::Tools::conf.pm(3), Net::DNS::SEC::Tools::defaults.pm(3),
402 Net::DNS::SEC::Tools::keyrec.pm(3),
403 Net::DNS::SEC::Tools::rolllog.pm(3),
404 Net::DNS::SEC::Tools::rollmgr.pm(3),
405 Net::DNS::SEC::Tools::rollrec.pm(3)
406 rollrec(5)
408perl v5.12.4 2011-10-12 ROLLERD(1)