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_phasemsg()
122 This routine sets the phase-message length. of phase-related log
123 messages used by rollerd. The valid levels are "long" and "short",
124 with "long" being the default value.
125 The long message length means that a phase description will be
127 included with some log messages. For example, the long form of a
128 message about ZSK rollover phase 3 will look like this: "ZSK phase
129 3 (Waiting for old zone data to expire from caches)".
130 The short message length means that a phase description will not be
132 included with some log messages. For example, the short form of a
133 message about ZSK rollover phase 3 will look like this: "ZSK phase
134 3".
135 Return Values:
137 1 - the phase-message length was set
139 0 - an invalid phase-message length was specified
140
142 rollmgr_channel(serverflag)
143 This interface sets up a persistent channel for communications with
144 rollerd. If serverflag is true, then the server's side of the
145 channel is created. If serverflag is false, then the client's side
146 of the channel is created.
147 Currently, the connection may only be made to the localhost. This
149 may be changed to allow remote connections, if this is found to be
150 needed.
151 rollmgr_queuecmd(cmdname, value)
153 This interface internally remembers a command and it's optional
154 value for later processing. See the rollmgr_getcmd() next for
155 further details.
156 rollmgr_getcmd()
158 rollmgr_getcmd() processes commands that need to be dealt with. If
159 there are any internally stored commands queued via the
160 rollmgr_queuecmd() function, they are dealt with first. After that
161 it retrieves a command sent over rollerd's communications channel
162 by a client program. The command and the command's data are sent
163 in each message.
164 The command and the command's data are returned to the caller.
166 rollmgr_sendcmd(closeflag,cmd,data)
168 rollmgr_sendcmd() sends a command to rollerd. The command must be
169 one of the commands from the table below. This interface creates a
170 communications channel to rollerd and sends the message. The
171 channel is not closed, in case the caller wants to receive a
172 response from rollerd.
173 The available commands and their required data are:
175 command data purpose
177 ------- ---- -------
178 ROLLCMD_DISPLAY 1/0 start/stop rollerd's
179 graphical display
180 ROLLCMD_DSPUB zone-name a DS record has been
181 published
182 ROLLCMD_DSPUBALL none DS records published for all
183 zones in KSK rollover phase 6
184 ROLLCMD_GETSTATUS none currently unused
185 ROLLCMD_LOGFILE log filename change the log file
186 ROLLCMD_LOGLEVEL log level set a new logging level
187 ROLLCMD_LOGMSG log message add a message to the log
188 ROLLCMD_LOGTZ timezone set timezone for log messages
189 ROLLCMD_MERGERRFS rollrec files merge rollrec files with the
190 current rollrec file
191 ROLLCMD_PHASEMSG long/short set long or short phase
192 messages
193 ROLLCMD_QUEUELIST none returns the names and next
194 event time of zones in the
195 "soon queue
196 (experimental)
197 ROLLCMD_QUEUESTATUS none returns information about
198 the state of soon-queue
199 processing
200 (experimental)
201 ROLLCMD_ROLLALL none resume rollover for all
202 suspended zones
203 ROLLCMD_ROLLALLZSKS none force all zones to start
204 ZSK rollover
205 ROLLCMD_ROLLKSK zone-name force a zone to start
206 KSK rollover
207 ROLLCMD_ROLLREC rollrec-name change rollerd's rollrec file
208 ROLLCMD_ROLLZONE zone name restart rollover for a
209 suspended zone
210 ROLLCMD_ROLLZSK zone-name force a zone to start
211 ZSK rollover
212 ROLLCMD_RUNQUEUE none rollerd runs through
213 its queue
214 ROLLCMD_SHUTDOWN none stop rollerd
215 ROLLCMD_SKIPALL none suspend all rollovers
216 ROLLCMD_SKIPZONE zone name suspend rollover for a
217 rolling zone
218 ROLLCMD_SLEEPTIME seconds-count set rollerd's sleep time
219 ROLLCMD_SPLITRRF rollrec-name, move a set of zones from the
220 zone names current rollrec file into a
221 new rollrec file
222 ROLLCMD_STATUS none get status of rollerd
223 ROLLCMD_ZONELOG zone name set the logging level for
224 logging level a particular zone
225 ROLLCMD_ZONESTATUS none get status of the zones
226 ROLLCMD_ZSARGS zonesigner args add a (probably temporary)
227 zone list set of options to the signing
228 of a set of zones
229 The data aren't checked for validity by rollmgr_sendcmd(); validity
231 checking is a responsibility of rollerd.
232 If the caller does not need a response from rollerd, then closeflag
234 should be set to CHANNEL_CLOSE; if a response is required then
235 closeflag should be CHANNEL_WAIT. These values are boolean values,
236 and the constants aren't required.
237 On success, 1 is returned. If an invalid command is given, 0 is
239 returned.
240 rollmgr_getresp()
242 After executing a client command sent via rollmgr_sendcmd(),
243 rollerd will send a response to the client. rollmgr_getresp()
244 allows the client to retrieve the response.
245 A return code and a response string are returned, in that order.
247 Both are specific to the command sent.
248 rollmgr_verifycmd(cmd)
250 rollmgr_verifycmd() verifies that cmd is a valid command for
251 rollerd. 1 is returned for a valid command; 0 is returned for an
252 invalid command.
253 1 is returned for a valid command; 0 is returned for an invalid
255 command.
256 rollmgr_get_phase(phasetype, phasenum)
258 rollmgr_get_phase() returns a description of a particular phase for
259 a particular type of rollover. phasetype specifies the type of
260 rollover, and may be "KSK" or "ZSK". phasenum specifies the phase
261 number whose description is desired. This must be an integer
262 between 0 and 7 (KSK) or 0 and 4 (ZSK). If an invalid phase type
263 or phase number is specified, an empty string is returned.
264
266 1. rollmgr_getid() attempts to exclusively lock the id file. Set a
267 timer if this matters to you.
268 2. rollmgr_getid() has a nice little race condition. We should lock
270 the file prior to opening it, but we can't do so without it being open.
271
273 Copyright 2005-2011 SPARTA, Inc. All rights reserved. See the COPYING
274 file included with the DNSSEC-Tools package for details.
275
277 Wayne Morrison, tewok@users.sourceforge.net
278
280 rollctl(1)
281 Net::DNS::SEC::Tools::keyrec.pm(3) Net::DNS::SEC::Tools::rolllog.pm(3)
283 Net::DNS::SEC::Tools::rollrec.pm(3)
284 rollerd(8)
286perl v5.12.4 2011-08-08 rollmgr(3)