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

NAME

6       Net::DNS::SEC::Tools::rollmgr - Communicate with the DNSSEC-Tools
7       rollover manager.
8

SYNOPSIS

10         use Net::DNS::SEC::Tools::rollmgr;
11
12         $dir = rollmgr_dir();
13
14         $idfile = rollmgr_idfile();
15
16         $id = rollmgr_getid();
17
18         rollmgr_dropid();
19
20         rollmgr_rmid();
21
22         rollmgr_cmdint();
23
24         $runflag = rollmgr_running();
25
26         rollmgr_halt();
27
28         rollmgr_phasemsg('long');
29
30         rollmgr_channel(1);
31         ($cmd,$data) = rollmgr_getcmd();
32         $ret = rollmgr_verifycmd($cmd);
33
34         rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZSK,"example.com");
35
36         rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZSK,"example.com");
37         ($retcode, $respmsg) = rollmgr_getresp();
38
39         $descr = rollmgr_get_phase('KSK', $phasecnt);
40

DESCRIPTION

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

GENERAL INTERFACES

48       The interfaces to the Net::DNS::SEC::Tools::rollmgr module are given
49       below.
50
51       rollmgr_dir()
52           This routine returns rollerd's directory.
53
54       rollmgr_idfile()
55           This routine returns rollerd's id file.
56
57       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
62           Return Values:
63
64               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
68       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
72           Return Values:
73
74               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
78       rollmgr_rmid()
79           This interface deletes rollerd's id file.
80
81           Return Values:
82
83                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
88       rollmgr_cmdint()
89           This routine informs rollerd that a command has been sent via
90           rollmgr_sendcmd().
91
92           Return Values:
93
94               -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
99       rollmgr_running()
100           This routine determines if rollerd is running and returns a value
101           indicating the status.
102
103           Return Values:
104
105                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
110       rollmgr_halt()
111           This routine informs rollerd to shut down.
112
113           In the current implementation, the return code from the kill()
114           command is returned.
115
116               -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
121       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
129           The command line to be run is built in this format:
130
131               <$zone> <$opts> reload <$zone>
132
133           This format assumes that the rndc command will be used for
134           signalling the name server.
135
136           The return value will be the return code from running $ctlprog.
137
138       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
143           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
148           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
153           Return Values:
154
155                1 - the phase-message length was set
156                0 - an invalid phase-message length was specified
157

ROLLERD COMMUNICATIONS INTERFACES

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
165           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
169           Return Values:
170
171                 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
179       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
184       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
192           The command and the command's data are returned to the caller.
193
194       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
201           The available commands and their required data are:
202
203              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
261           The data aren't checked for validity by rollmgr_sendcmd(); validity
262           checking is a responsibility of rollerd.
263
264           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
269           On success, 1 is returned.  If an invalid command is given, 0 is
270           returned.
271
272       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
277           A return code and a response string are returned, in that order.
278           Both are specific to the command sent.
279
280       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
285           1 is returned for a valid command; 0 is returned for an invalid
286           command.
287
288       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

WARNINGS

297       1.  rollmgr_getid() attempts to exclusively lock the id file.  Set a
298       timer if this matters to you.
299
300       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

AUTHOR

308       Wayne Morrison, tewok@tislabs.com
309

SEE ALSO

311       rollctl(1)
312
313       Net::DNS::SEC::Tools::keyrec.pm(3) Net::DNS::SEC::Tools::rolllog.pm(3)
314       Net::DNS::SEC::Tools::rollrec.pm(3)
315
316       rndc(8), rollerd(8)
317
318
319
320perl v5.36.0                      2023-01-19                        rollmgr(3)
Impressum