1ROLLERD(1) User Contributed Perl Documentation ROLLERD(1)
2
3
4
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
21 ZSK Rollover Using the Pre-Publish Method
22
23 The Pre-Publish Method has four phases that are entered when it is time
24 to perform ZSK rollover:
25
26 1. wait for old zone data to expire from caches
27 2. sign the zone with the KSK and Published ZSK
28 3. wait for old zone data to expire from caches
29 4. adjust keys in keyrec and sign the zone with new Current ZSK
30
31 rollerd uses the zonesigner command during ZSK rollover phases 2 and 4.
32 zonesigner will generate keys as required and sign the zone during
33 these two phases.
34
35 The Pre-Publish Method of key rollover is defined in the Step-by-Step
36 DNS Security Operator Guidance Document. See that document for more
37 detailed information.
38
39 KSK Rollover Using the Double Signature Method
40
41 The Double Signature Method has seven phases that are entered when it
42 is time to perform ZSK rollover:
43
44 1. wait for old zone data to expire from caches
45 2. generate a new (published) KSK
46 3. wait for the old DNSKEY RRset to expire from caches
47 4. roll the KSKs
48 5. transfer new keyset to the parent
49 6. wait for parent to publish the new DS record
50 7. reload the zone
51
52 rollerd uses the zonesigner command during KSK rollover phases 2 and 4.
53 zonesigner will generate keys as required and sign the zone during
54 these two phases.
55
56 Currently, steps 5 and 6 are handled manually. In step 5, rollerd
57 informs the administrator that the zone's keyset must be transferred to
58 its parent in order for rollover to continue. In step 6, after the
59 parent has published a new DS record, the administrator uses rollctl to
60 inform rollerd that the DS record has been published and rollover may
61 continue.
62
63 The Double Signature Method of key rollover is defined in the Step-by-
64 Step DNS Security Operator Guidance Document. See that document for
65 more detailed information.
66
67 rollrec Files
68
69 The zones to be managed by rollerd are described in a rollrec file.
70 Each zone's entry contains data needed by rollerd and some data useful
71 to a user. Below is a sample rollrec entry:
72
73 roll "example.com"
74 zonefile "example.com.signed"
75 keyrec "example.com.krf"
76 directory "dir-example.com"
77 kskphase "0"
78 zskphase "3"
79 ksk_rollsecs "1172614842"
80 ksk_rolldate "Tue Feb 27 22:20:42 2007"
81 zsk_rollsecs "1172615087"
82 zsk_rolldate "Tue Feb 27 22:24:47 2007"
83 maxttl "60"
84 display "1"
85 phasestart "Tue Feb 27 22:25:07 2007"
86
87 The first line gives the rollrec entry's name. The following lines
88 give the zone's signed zone file, keyrec file, the current rollover
89 phases, the rollover timestamps, and other information.
90
91 If either of the zonefile or keyrec files do not exist, then a "roll"
92 rollrec will be changed into a "skip" rollrec. That record will not be
93 processed.
94
95 A more detailed explanation may be found in rollrec(5).
96
97 Directories
98
99 rollerd's execution directory is either the directory in which it is
100 executed or the directory passed in the -directory command-line option.
101 Any files used by rollerd that were not specified with absolute paths
102 use this directory as their base.
103
104 The directory field informs rollerd where the zone's files may be
105 found. For that zone, rollerd will move into that directory, then
106 return to its execution directory when it finishes rollover operations
107 for that zone. If the directory value is a relative path, it will be
108 appended to rollerd's execution directory. If the directory value is
109 an absolute path, it will be used as is.
110
111 Controlling rollerd with rollctl
112
113 The rollctl command is used to control the behavior of rollerd. A num‐
114 ber of commands are available, such as starting or stopping rollover
115 for a selected zone or all zones, turning on or off a GUI rollover dis‐
116 play, and halting rollerd execution. The communications path between
117 rollerd and rollctl is operating system-dependent. On Unix-like sys‐
118 tems, it is a Unix pipe that should only be writable by root. A more
119 detailed explanation of rollctl may be found in rollctl(8).
120
121 A Note About Files and Filenames
122
123 There are a number of files and filenames used by rollerd and zone‐
124 signer. The user must be aware of the files used by these programs,
125 where the files are located, and where the programs are executed.
126
127 By default, rollerd will change directory to the DNSSEC-Tools direc‐
128 tory, though this may be changed by the -directory option. Any pro‐
129 grams started by rollerd, most importantly zonesigner, will run in this
130 same directory. If files and directories referenced by these programs
131 are named with relative paths, those paths must be relative to this
132 directory.
133
134 The rollrec entry name is used as a key to the rollrec file and to the
135 zone's keyrec file. This entry does not have to be the name of the
136 entry's domain, but it is a very good idea to make it so. Whatever is
137 used for this entry name, the same name must be used for the zone
138 keyrec in that zone's keyrec file.
139
140 It is probably easiest to store rollrec files, keyrec files, zone
141 files, and key files in a single directory.
142
144 The following steps must be taken to initialize and use rollerd. This
145 assumes that zone files have been created, and that BIND and DNSSEC-
146 Tools have been installed.
147
148 0. sign zones
149 The zones to be managed by rollerd must be signed. Use zonesigner
150 to create the signed zone files and the keyrec files needed by
151 rollerd. The rollrec file created in the next step must use the
152 keyrec file names and the signed zone file names created here.
153
154 1. create rollrec file
155 Before rollerd may be used, a rollrec file must first be created.
156 While this file may be built by hand, the rollinit command was
157 written specifically to build the file.
158
159 2. select operational parameters
160 A number of rollerd's operational parameters are taken from the
161 DNSSEC-Tools configuration file. However, these may be overridden
162 by command-line options. See the OPTIONS section below for more
163 details. If non-standard parameters are desired to always be used,
164 the appropriate fields in the DNSSEC-Tools configuration file may
165 be modified to use these values.
166
167 3. install the rollover configuration
168 The complete rollover configuration -- rollerd, rollrec file,
169 DNSSEC-Tools configuration file values, zone files -- should be
170 installed. The appropriate places for these locations are both
171 installation-dependent and operating system-dependent.
172
173 4. test the rollover configuration
174 The complete rollover configuration should be tested.
175
176 Edit the zone files so that their zones have short TTL values. A
177 minute TTL should be sufficient. Test rollovers of this speed
178 should only be done in a test environment without the real signed
179 zone.
180
181 Run the following command:
182
183 rollerd -rrfile test.rollrec -logfile - -loglevel info -sleep 60
184
185 This command assumes the test rollrec file is test.rollrec. It
186 writes a fair amount of log messages to the terminal, and checks
187 its queue every 60 seconds. Follow the messages to ensure that the
188 appropriate actions, as required by the Pre-Publish Method, are
189 taking place.
190
191 5. set rollerd to start at boot
192 Once the configuration is found to work, rollerd should be set to
193 start at system boot. The actual operations required for this step
194 are operating system-dependent.
195
196 6. reboot and verify
197 The system should be rebooted and the rollerd logfile checked to
198 ensure that rollerd is operating properly.
199
201 The following options are recognized:
202
203 -rrfile rollrec_file
204 Name of the rollrec file to be processed. This is the only
205 required "option".
206
207 -directory dir
208 Sets the rollerd execution directory. This must be a valid direc‐
209 tory.
210
211 -logfile log_file
212 Sets the rollerd log file to log_file. This must be a valid log‐
213 ging file, meaning that if log_file already exists, it must be a
214 regular file. The only exceptions to this are if logfile is
215 /dev/stdout, /dev/tty, -. Of these three, using a log_file of - is
216 preferable since Perl will properly convert the - to the process'
217 standard output.
218
219 -loglevel level
220 Sets rollerd's logging level to level. rollmgr.pm(3) contains a
221 list of the valid logging levels.
222
223 -sleep sleeptime
224 Sets rollerd's sleep time to sleeptime. The sleep time is the
225 amount of time (in seconds) rollerd waits between processing its
226 rollrec-based queue.
227
228 -parameters
229 Prints a set of rollerd parameters and then exits.
230
231 -display
232 Starts the blinkenlights graphical display program to show the sta‐
233 tus of zones managed by rollerd.
234
235 -help
236 Display a usage message.
237
238 -verbose
239 Verbose output will be given.
240
242 rollerd uses the rndc command to communicate with the BIND named dae‐
243 mon. Therefore, it assumes that appropriate measures have been taken
244 so that this communication is possible.
245
247 The following problems (or potential problems) are known:
248
249 - Any process that can write to the rollover socket can send commands
250 to rollerd. This is probably not a Good Thing.
251
252 - Very little testing was done with zone files and key files not in
253 the process' directory.
254
256 The following potential enhancements may be made:
257
258 - It'd be good to base rollerd's sleep time on when the next opera‐
259 tion must take place, rather than a simple seconds count.
260
262 Copyright 2005-2007 SPARTA, Inc. All rights reserved. See the COPYING
263 file included with the DNSSEC-Tools package for details.
264
266 Wayne Morrison, tewok@users.sourceforge.net
267
269 blinkenlights(8), named(8), rndc(8), rollchk(8), rollctl(8),
270 rollinit(8), zonesigner(8)
271
272 Net::DNS::SEC::Tools::conf.pm(3), Net::DNS::SEC::Tools::defaults.pm(3),
273 Net::DNS::SEC::Tools::keyrec.pm(3), Net::DNS::SEC::Tools::roll‐
274 log.pm(3), Net::DNS::SEC::Tools::rollmgr.pm(3),
275 Net::DNS::SEC::Tools::rollrec.pm(3)
276
277 rollrec(5)
278
279
280
281perl v5.8.8 2007-09-14 ROLLERD(1)