1ROLLCTL(1) User Contributed Perl Documentation ROLLCTL(1)
2
6 rollctl - Send commands to the DNSSEC-Tools rollover daemon
7
9 rollctl [options]
10
12 The rollctl command sends commands to the DNSSEC-Tools rollover daemon,
13 rollerd. Only one option may be specified on a command line.
14 In most cases, rollerd will send a response to rollctl. rollctl will
16 print a success or failure message, as appropriate.
17 If rollctl is run as a PAR-packed command, it will use its own local
19 copy of the dnssec-tools.conf file. This file will be found in the
20 package directory.
21
23 The following options are handled by rollctl.
24 -display
26 Starts the rollover status GUI.
27 -dspub zone
29 Indicates that zone's parent has published a new DS record for
30 zone.
31 Multiple zones can be specified on the command line. For instance,
33 this command will send the dspub command to rollerd for three
34 zones.
35 $ rollctl -dspub example1.com example2.com example3.com
37 -dspuball
39 Indicates that DS records have been published for all zones in
40 phase 5 of KSK rollover.
41 -group
43 Indicates that the specified command should apply to a zone group
44 instead of a zone. Consequently, the specified zone must actually
45 be a zone group. This option must be used in conjunction with
46 another command.
47 This option only applies to the following commands: -dspub,
49 -rollksk, -rollzone, -rollzsk, and -skipzone. This command will
50 have no effect if it is given to other other commands.
51 -halt [now]
53 Cleanly halts rollerd execution. If the optional now parameter is
54 given, then rollerd will be halted immediately, rather than
55 allowing it to complete its currently queued operations.
56 -logfile logfile
58 Sets the rollerd log file to logfile. This must be a valid logging
59 file, meaning that if logfile already exists, it must be a regular
60 file. The only exceptions to this are if logfile is /dev/stdout or
61 /dev/tty.
62 -loglevel loglevel
64 Sets the rollerd logging level to loglevel. This must be one of
65 the valid logging levels defined in rollmgr.pm(3).
66 If a logging level is not specified, then the list of valid levels
68 will be printed and rollctl will exit. The list is given in both
69 text and numeric forms.
70 -logtz logtz
72 Sets the rollerd logging timezone to loglevel. This must be either
73 gmt (for Greenwich Mean Time or local (for the host's local time.)
74 -mergerrfs rollrec0 ... rollrecN
76 Tells rollerd to merge the specified rollrec files with its active
77 rollrec file. The names of the rollrec files must not contain
78 colons.
79 -nodisplay
81 Stops the rollover status GUI.
82 -phasemsg length
84 length is the default length of phase-related log messages used by
85 rollerd. The valid levels are "long" and "short", with "long"
86 being the default value.
87 The long message length means that a phase description will be
89 included with some log messages. For example, the long form of a
90 message about ZSK rollover phase 3 will look like this: "ZSK phase
91 3 (Waiting for old zone data to expire from caches)".
92 The short message length means that a phase description will not be
94 included with some log messages. For example, the short form of a
95 message about ZSK rollover phase 3 will look like this: "ZSK phase
96 3".
97 -rollall
99 Resumes rollover for all zones in the current rollrec file that
100 have been suspended. ("skip" zones are suspended.)
101 -rollallksks
103 Initiates KSK rollover for all the zones defined in the current
104 rollrec file that aren't currently in rollover.
105 -rollallzsks
107 Initiates ZSK rollover for all the zones defined in the current
108 rollrec file that aren't currently in rollover.
109 -rollksk zone
111 Initiates KSK rollover for the zone named by zone.
112 Multiple zones can be specified on the command line. For instance,
114 this command will send the rollksk command to rollerd for three
115 zones.
116 $ rollctl -rollksk example1.com example2.com example3.com
118 -rollrec rollrec_file
120 Sets the rollrec file to be processed by rollerd to rollrec_file.
121 -rollzone zone
123 Resumes rollover for the suspended zone named by zone.
124 Multiple zones can be specified on the command line. For instance,
126 this command will send the rollzone command to rollerd for three
127 zones.
128 $ rollctl -rollzone example1.com example2.com example3.com
130 -rollzsk zone
132 Initiates rollover for the zone named by zone.
133 Multiple zones can be specified on the command line. For instance,
135 this command will send the rollzsk command to rollerd for three
136 zones.
137 $ rollctl -rollzsk example1.com example2.com example3.com
139 -runqueue
141 Wakes up rollerd and has it run its queue of rollrec entries.
142 -shutdown
144 Synonym for -halt.
145 -signzone zone
147 Signs zone's zonefile without performing any rollover actions. The
148 zone is signed with the keys most recently used to sign the zone.
149 No new keys will be generated.
150 -signzones [all | active]
152 Signs the zonefiles of zones managed by rollerd, without performing
153 any rollover actions. If the all option is given, then all of
154 rollerd's zones will be signed. If the active option is given,
155 then only those zones which aren't in the skip stage will be
156 signed. The zones are signed with the keys most recently used to
157 sign each zone. No new keys will be generated.
158 -skipall
160 Suspends rollover for all zones in the current rollrec file.
161 -skipzone zone
163 Suspends rollover for the zone named by zone.
164 Multiple zones can be specified on the command line. For instance,
166 this command will send the skipzone command to rollerd for three
167 zones.
168 $ rollctl -skipzone example1.com example2.com example3.com
170 -sleeptime seconds
172 Sets rollerd's sleep time to seconds seconds. sleeptime must be an
173 integer at least as large as the $MIN_SLEEP value in rollerd.
174 -splitrrf new-rrf zone0 ... zoneN
176 Tells rollerd to move a set of rollrec entries from the current
177 rollrec file into a new file. The new file is named in the new-rrf
178 parameter. The rollrec entries whose names correspond to the zone0
179 to zoneN list are moved to the new file. The name of the new
180 rollrec file and the zone names must not contain colons.
181 -status
183 Has rollerd write several of its operational parameters to its log
184 file. The parameters are also reported to rollctl, which prints
185 them to the screen.
186 -zonegroup [zone-group]
188 Requests information about zone groups from rollerd. If the
189 optional zone-group argument is not given, then rollerd will return
190 a list of the defined zone groups and the number of zones in each.
191 If a zone-group is specified, then rollerd will return a list of
192 the zones in that group.
193 (While this is using the term "zone", it is actually referring to
195 the name of the rollrec entries. For a particular rollrec entry,
196 the rollrec name is usually the same as the zone name, but this is
197 not a requirement.)
198 -zonelog
200 Set the logging level for the specified zone. The new logging
201 level is only for the current execution of rollerd and is not saved
202 to the active rollrec file.
203 The arguments for this command must be in the format
205 "zone:loglevel". For example, this command will send the zonelog
206 command to rollerd for three zones.
207 $ rollctl -zonelog example1.com:info example2.com:6 example3.com:err
209 -zonestatus
211 Has rollerd write the status of zones in the current rollrec file
212 to the rollerd log file. The status is also reported to rollctl,
213 which prints it to the screen. rollctl prints it in columnar
214 fashion to enhance readability. The columns, in order, are:
215 rollrec name, zone name, roll/skip state, and rollover phase.
216 Example:
218 anothersub anothersub.example.com skip
219 KSK 1
220 example.com example.com roll
221 KSK 1
222 site1.in.subzone.example.com subzone.example.com roll
223 KSK 3
224 site1.subzone.example.com subzone.example.com roll
225 KSK 3
226 -zsargs arglist zones
228 Provides additional zonesigner arguments for a given set of zones.
229 These arguments will override the arguments in the DNSSEC-Tools
230 defaults file, the DNSSEC-Tools configuration file, and the zones'
231 keyrec files.
232 The zonesigner argument list is given in arglist. Given the
234 rollctl argument processing, the new arguments for zonesigner
235 cannot be specified as expected. Instead, the arguments should be
236 given in the following manner. The leading dash should be replaced
237 with an equals sign. If the option takes an argument, the space
238 that would separate the option from the option's argument should
239 also be replaced by an equals sign. rollerd translates these
240 arguments to the appropriate format for zonesigner. These examples
241 should clarify the modifications:
242 normal zonesigner option -zsargs options
244 ------------------------ ---------------
245 -nokrfile =nokrfile
246 -zskcount 5 =zskcount=5
247 The zones list is a space-separated list of zones. All the new
249 zonesigner arguments will be applied to all the listed zones.
250 The "=clear" argument is special. rollerd translates it to
252 "-clear", which is not a normal zonesigner option. Instead,
253 rollerd recognizes "-clear" as an indicator that it should remove
254 the zsargs field from the rollrec records for the specified zones.
255 The following are valid uses of -zsargs:
257 # rollctl -zsargs =ksklength=2048 example.com
259 # rollctl -zsargs =ksklen=2048 =zsklen=2048 example.com test.com
260 -Version
262 Displays the version information for rollctl and the DNSSEC-Tools
263 package.
264 -quiet
266 Prevents output from being given. Both error and non-error output
267 is stopped.
268 -help
270 Displays a usage message.
271
273 rollctl may give the following exit codes:
274 0 - Successful execution
276 1 - Error sending the command to rollerd.
277 2 - Missing argument.
278 3 - Too many commands specified.
279 200 - Rollerd is not running.
280 201 - Configuration file checks failed.
281
283 The following modifications may be made in the future:
284 command execution order
286 The commands will be executed in the order given on the command
287 line rather than in alphabetical order.
288
290 Copyright 2006-2014 SPARTA, Inc. All rights reserved. See the COPYING
291 file included with the DNSSEC-Tools package for details.
292
294 Wayne Morrison, tewok@tislabs.com
295
297 Net::DNS::SEC::Tools::rollmgr.pm(3),
298 Net::DNS::SEC::Tools::rollrec.pm(3)
299 rollerd(8)
301perl v5.38.0 2023-07-19 ROLLCTL(1)