1rollmgr(3) User Contributed Perl Documentation rollmgr(3)
2
6 Net::DNS::SEC::Tools::rollmgr - Communicate with the DNSSEC-Tools
7 rollover manager.
8
10 use Net::DNS::SEC::Tools::rollmgr;
11 $dir = rollmgr_dir();
13 $idfile = rollmgr_idfile();
15 $id = rollmgr_getid();
17 rollmgr_dropid();
19 rollmgr_rmid();
21 rollmgr_cmdint();
23 $runflag = rollmgr_running();
25 rollmgr_halt();
27 rollmgr_phasemsg('long');
29 rollmgr_channel(1);
31 ($cmd,$data) = rollmgr_getcmd();
32 $ret = rollmgr_verifycmd($cmd);
33 rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZSK,"example.com");
35 rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZSK,"example.com");
37 ($retcode, $respmsg) = rollmgr_getresp();
38 $descr = rollmgr_get_phase('KSK', $phasecnt);
40
42 The Net::DNS::SEC::Tools::rollmgr module provides standard, platform-
43 independent methods for a program to communicate with DNSSEC-Tools'
44 rollerd rollover manager. There are two interface classes described
45 here: general interfaces and communications interfaces.
46
48 The interfaces to the Net::DNS::SEC::Tools::rollmgr module are given
49 below.
50 rollmgr_dir()
52 This routine returns rollerd's directory.
53 rollmgr_idfile()
55 This routine returns rollerd's id file.
56 rollmgr_getid()
58 This routine returns rollerd's process id. If a non-zero value is
59 passed as an argument, the id file will be left open and accessible
60 through the PIDFILE file handle. See the WARNINGS section below.
61 Return Values:
63 On success, the first portion of the file contents
65 (up to 80 characters) is returned.
66 -1 is returned if the id file does not exist.
67 rollmgr_dropid()
69 This interface ensures that another instance of rollerd is not
70 running and then creates a id file for future reference.
71 Return Values:
73 1 - the id file was successfully created for this process
75 0 - another process is already acting as rollerd
76 -1 - unable to create the id file
77 rollmgr_rmid()
79 This interface deletes rollerd's id file.
80 Return Values:
82 1 - the id file was successfully deleted
84 0 - no id file exists
85 -1 - the calling process is not rollerd
86 -2 - unable to delete the id file
87 rollmgr_cmdint()
89 This routine informs rollerd that a command has been sent via
90 rollmgr_sendcmd().
91 Return Values:
93 -1 - an invalid process id was found for rollerd
95 Anything else indicates the number of processes that were
96 signaled.
97 (This should only ever be 1.)
98 rollmgr_running()
100 This routine determines if rollerd is running and returns a value
101 indicating the status.
102 Return Values:
104 1 - rollerd is running.
106 0 - The process listed in the rollerd process id file
107 is not running.
108 -1 - Unable to get the rollerd process id.
109 rollmgr_halt()
111 This routine informs rollerd to shut down.
112 In the current implementation, the return code from the kill()
114 command is returned.
115 -1 - an invalid process id was found for rollerd
117 Anything else indicates the number of processes that were
118 signaled.
119 (This should only ever be 1.)
120 rollmgr_loadzone(ctlprog,opts,zone)
122 This routine informs a name server to reload a zone's zone file.
123 The $ctlprog argument is the command that will be run to control
124 the name server. If this is an empty string, then the default
125 value for DNSSEC-Tools will be used. The $opts argument is a set
126 of options to be passed to ctlprog. The $zone argument is the name
127 of the zone to be reloaded.
128 The command line to be run is built in this format:
130 <$zone> <$opts> reload <$zone>
132 This format assumes that the rndc command will be used for
134 signalling the name server.
135 The return value will be the return code from running $ctlprog.
137 rollmgr_phasemsg()
139 This routine sets the phase-message length. of phase-related log
140 messages used by rollerd. The valid levels are "long" and "short",
141 with "long" being the default value.
142 The long message length means that a phase description will be
144 included with some log messages. For example, the long form of a
145 message about ZSK rollover phase 3 will look like this: "ZSK phase
146 3 (Waiting for old zone data to expire from caches)".
147 The short message length means that a phase description will not be
149 included with some log messages. For example, the short form of a
150 message about ZSK rollover phase 3 will look like this: "ZSK phase
151 3".
152 Return Values:
154 1 - the phase-message length was set
156 0 - an invalid phase-message length was specified
157
159 rollmgr_channel(serverflag)
160 This interface sets up a persistent channel for communications with
161 rollerd. If serverflag is true, then the server's side of the
162 channel is created. If serverflag is false, then the client's side
163 of the channel is created.
164 Currently, the connection may only be made to the localhost. This
166 may be changed to allow remote connections, if this is found to be
167 needed.
168 Return Values:
170 1 - Communications channel successfully established.
172 0 - Unable to connect to the server.
173 -1 - Unable to create a Unix socket.
174 -2 - Unable to bind to the Unix socket. (server only)
175 -3 - Unable to change the permissions on the Unix socket. (server only)
176 -4 - Unable to listen on the Unix socket. (server only)
177 -5 - The socket name was longer than allowed for a Unix socket.
178 rollmgr_queuecmd(cmdname, value)
180 This interface internally remembers a command and it's optional
181 value for later processing. See the rollmgr_getcmd() next for
182 further details.
183 rollmgr_getcmd()
185 rollmgr_getcmd() processes commands that need to be dealt with. If
186 there are any internally stored commands queued via the
187 rollmgr_queuecmd() function, they are dealt with first. After that
188 it retrieves a command sent over rollerd's communications channel
189 by a client program. The command and the command's data are sent
190 in each message.
191 The command and the command's data are returned to the caller.
193 rollmgr_sendcmd(closeflag,cmd,data)
195 rollmgr_sendcmd() sends a command to rollerd. The command must be
196 one of the commands from the table below. This interface creates a
197 communications channel to rollerd and sends the message. The
198 channel is not closed, in case the caller wants to receive a
199 response from rollerd.
200 The available commands and their required data are:
202 command data purpose
204 ------- ---- -------
205 ROLLCMD_DISPLAY 1/0 start/stop rollerd's
206 graphical display
207 ROLLCMD_DSPUB zone-name a DS record has been
208 published
209 ROLLCMD_DSPUBALL none DS records published for all
210 zones in KSK rollover phase 5
211 ROLLCMD_GETSTATUS none currently unused
212 ROLLCMD_LOGFILE log filename change the log file
213 ROLLCMD_LOGLEVEL log level set a new logging level
214 ROLLCMD_LOGMSG log message add a message to the log
215 ROLLCMD_LOGTZ timezone set timezone for log messages
216 ROLLCMD_MERGERRFS rollrec files merge rollrec files with the
217 current rollrec file
218 ROLLCMD_PHASEMSG long/short set long or short phase
219 messages
220 ROLLCMD_QUEUELIST none returns the names and next
221 event time of zones in the
222 "soon queue
223 (experimental)
224 ROLLCMD_QUEUESTATUS none returns information about
225 the state of soon-queue
226 processing
227 (experimental)
228 ROLLCMD_ROLLALL none resume rollover for all
229 suspended zones
230 ROLLCMD_ROLLALLZSKS none force all zones to start
231 ZSK rollover
232 ROLLCMD_ROLLKSK zone-name force a zone to start
233 KSK rollover
234 ROLLCMD_ROLLREC rollrec-name change rollerd's rollrec file
235 ROLLCMD_ROLLZONE zone name restart rollover for a
236 suspended zone
237 ROLLCMD_ROLLZSK zone-name force a zone to start
238 ZSK rollover
239 ROLLCMD_RUNQUEUE none rollerd runs through
240 its queue
241 ROLLCMD_SHUTDOWN none stop rollerd
242 ROLLCMD_SIGNZONE zone sign a zone (no rollover)
243 ROLLCMD_SIGNZONEs all or active sign all or active zones
244 ROLLCMD_SKIPALL none suspend all rollovers
245 ROLLCMD_SKIPZONE zone name suspend rollover for a
246 rolling zone
247 ROLLCMD_SLEEPTIME seconds-count set rollerd's sleep time
248 ROLLCMD_SPLITRRF rollrec-name, move a set of zones from the
249 zone names current rollrec file into a
250 new rollrec file
251 ROLLCMD_STATUS none get status of rollerd
252 ROLLCMD_ZONEGROUP zonegroup name get info on all zonegroups
253 or a particular zonegroup
254 ROLLCMD_ZONELOG zone name set the logging level for
255 logging level a particular zone
256 ROLLCMD_ZONESTATUS none get status of the zones
257 ROLLCMD_ZSARGS zonesigner args add a (probably temporary)
258 zone list set of options to the signing
259 of a set of zones
260 The data aren't checked for validity by rollmgr_sendcmd(); validity
262 checking is a responsibility of rollerd.
263 If the caller does not need a response from rollerd, then closeflag
265 should be set to CHANNEL_CLOSE; if a response is required then
266 closeflag should be CHANNEL_WAIT. These values are boolean values,
267 and the constants aren't required.
268 On success, 1 is returned. If an invalid command is given, 0 is
270 returned.
271 rollmgr_getresp()
273 After executing a client command sent via rollmgr_sendcmd(),
274 rollerd will send a response to the client. rollmgr_getresp()
275 allows the client to retrieve the response.
276 A return code and a response string are returned, in that order.
278 Both are specific to the command sent.
279 rollmgr_verifycmd(cmd)
281 rollmgr_verifycmd() verifies that cmd is a valid command for
282 rollerd. 1 is returned for a valid command; 0 is returned for an
283 invalid command.
284 1 is returned for a valid command; 0 is returned for an invalid
286 command.
287 rollmgr_get_phase(phasetype, phasenum)
289 rollmgr_get_phase() returns a description of a particular phase for
290 a particular type of rollover. phasetype specifies the type of
291 rollover, and may be "KSK" or "ZSK". phasenum specifies the phase
292 number whose description is desired. This must be an integer
293 between 0 and 7 (KSK) or 0 and 4 (ZSK). If an invalid phase type
294 or phase number is specified, an empty string is returned.
295
297 1. rollmgr_getid() attempts to exclusively lock the id file. Set a
298 timer if this matters to you.
299 2. rollmgr_getid() has a nice little race condition. We should lock
301 the file prior to opening it, but we can't do so without it being open.
302
304 Copyright 2005-2014 SPARTA, Inc. All rights reserved. See the COPYING
305 file included with the DNSSEC-Tools package for details.
306
308 Wayne Morrison, tewok@tislabs.com
309
311 rollctl(1)
312 Net::DNS::SEC::Tools::keyrec.pm(3) Net::DNS::SEC::Tools::rolllog.pm(3)
314 Net::DNS::SEC::Tools::rollrec.pm(3)
315 rndc(8), rollerd(8)
317perl v5.38.0 2023-07-19 rollmgr(3)