1ROLLCTL(1)            User Contributed Perl Documentation           ROLLCTL(1)
2
3
4

NAME

6       rollctl - Send commands to the DNSSEC-Tools rollover daemon
7

SYNOPSIS

9         rollctl [options]
10

DESCRIPTION

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
15       In most cases, rollerd will send a response to rollctl.  rollctl will
16       print a success or failure message, as appropriate.
17
18       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

OPTIONS

23       The following options are handled by rollctl.
24
25       -display
26           Starts the rollover status GUI.
27
28       -dspub zone
29           Indicates that zone's parent has published a new DS record for
30           zone.
31
32           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
36               $ rollctl -dspub example1.com example2.com example3.com
37
38       -dspuball
39           Indicates that DS records have been published for all zones in
40           phase 5 of KSK rollover.
41
42       -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
48           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
52       -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
57       -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
63       -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
67           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
71       -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
75       -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
80       -nodisplay
81           Stops the rollover status GUI.
82
83       -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
88           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
93           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
98       -rollall
99           Resumes rollover for all zones in the current rollrec file that
100           have been suspended.  ("skip" zones are suspended.)
101
102       -rollallksks
103           Initiates KSK rollover for all the zones defined in the current
104           rollrec file that aren't currently in rollover.
105
106       -rollallzsks
107           Initiates ZSK rollover for all the zones defined in the current
108           rollrec file that aren't currently in rollover.
109
110       -rollksk zone
111           Initiates KSK rollover for the zone named by zone.
112
113           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
117               $ rollctl -rollksk example1.com example2.com example3.com
118
119       -rollrec rollrec_file
120           Sets the rollrec file to be processed by rollerd to rollrec_file.
121
122       -rollzone zone
123           Resumes rollover for the suspended zone named by zone.
124
125           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
129               $ rollctl -rollzone example1.com example2.com example3.com
130
131       -rollzsk zone
132           Initiates rollover for the zone named by zone.
133
134           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
138               $ rollctl -rollzsk example1.com example2.com example3.com
139
140       -runqueue
141           Wakes up rollerd and has it run its queue of rollrec entries.
142
143       -shutdown
144           Synonym for -halt.
145
146       -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
151       -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
159       -skipall
160           Suspends rollover for all zones in the current rollrec file.
161
162       -skipzone zone
163           Suspends rollover for the zone named by zone.
164
165           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
169               $ rollctl -skipzone example1.com example2.com example3.com
170
171       -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
175       -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
182       -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
187       -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
194           (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
199       -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
204           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
208               $ rollctl -zonelog example1.com:info example2.com:6 example3.com:err
209
210       -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
217           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
227       -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
233           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
243               normal zonesigner option            -zsargs options
244               ------------------------            ---------------
245                   -nokrfile                          =nokrfile
246                   -zskcount 5                        =zskcount=5
247
248           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
251           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
256           The following are valid uses of -zsargs:
257
258               # rollctl -zsargs =ksklength=2048 example.com
259               # rollctl -zsargs =ksklen=2048 =zsklen=2048 example.com test.com
260
261       -Version
262           Displays the version information for rollctl and the DNSSEC-Tools
263           package.
264
265       -quiet
266           Prevents output from being given.  Both error and non-error output
267           is stopped.
268
269       -help
270           Displays a usage message.
271

EXIT CODES

273       rollctl may give the following exit codes:
274
275       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

FUTURE

283       The following modifications may be made in the future:
284
285       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

AUTHOR

294       Wayne Morrison, tewok@tislabs.com
295

SEE ALSO

297       Net::DNS::SEC::Tools::rollmgr.pm(3),
298       Net::DNS::SEC::Tools::rollrec.pm(3)
299
300       rollerd(8)
301
302
303
304perl v5.38.0                      2023-07-19                        ROLLCTL(1)
Impressum