1rollmgr(3) User Contributed Perl Documentation rollmgr(3)
2
3
4
6 Net::DNS::SEC::Tools::rollmgr - Communicate with the DNSSEC-Tools
7 rollover manager.
8
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 rollmgr_halt();
25
26 rollmgr_channel(1);
27 ($cmd,$data) = rollmgr_getcmd();
28 $ret = rollmgr_verifycmd($cmd);
29
30 rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZONE,"example.com");
31
32 rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZONE,"example.com");
33 ($retcode, $respmsg) = rollmgr_getresp();
34
36 The Net::DNS::SEC::Tools::rollmgr module provides standard, platform-
37 independent methods for a program to communicate with DNSSEC-Tools'
38 rollerd rollover manager. There are two interface classes described
39 here: general interfaces and communications interfaces.
40
42 The interfaces to the Net::DNS::SEC::Tools::rollmgr module are given
43 below.
44
45 rollmgr_dir()
46 This routine returns rollerd's directory.
47
48 rollmgr_idfile()
49 This routine returns rollerd's id file.
50
51 rollmgr_getid()
52 This routine returns rollerd's process id. If a non-zero value is
53 passed as an argument, the id file will be left open and accessible
54 through the PIDFILE file handle. See the WARNINGS section below.
55
56 Return Values:
57
58 On success, the first portion of the file contents
59 (up to 80 characters) is returned.
60 -1 is returned if the id file does not exist.
61
62 rollmgr_dropid()
63 This interface ensures that another instance of rollerd is not run‐
64 ning and then creates a id file for future reference.
65
66 Return Values:
67
68 1 - the id file was successfully created for this process
69 0 - another process is already acting as rollerd
70
71 rollmgr_rmid()
72 This interface deletes rollerd's id file.
73
74 Return Values:
75
76 1 - the id file was successfully deleted
77 0 - no id file exists
78 -1 - the calling process is not rollerd
79 -2 - unable to delete the id file
80
81 rollmgr_cmdint()
82 This routine informs rollerd that a command has been sent via
83 rollmgr_sendcmd().
84
85 Return Values:
86
87 -1 - an invalid process id was found for rollerd
88 Anything else indicates the number of processes that were
89 signaled.
90 (This should only ever be 1.)
91
92 rollmgr_halt()
93 This routine informs rollerd to shut down.
94
95 In the current implementation, the return code from the kill() com‐
96 mand is returned.
97
98 -1 - an invalid process id was found for rollerd
99 Anything else indicates the number of processes that were
100 signaled.
101 (This should only ever be 1.)
102
104 rollmgr_channel(serverflag)
105 This interface sets up a persistent channel for communications with
106 rollerd. If serverflag is true, then the server's side of the
107 channel is created. If serverflag is false, then the client's side
108 of the channel is created.
109
110 Currently, the connection may only be made to the localhost. This
111 may be changed to allow remote connections, if this is found to be
112 needed.
113
114 rollmgr_getcmd()
115 rollmgr_getcmd() retrieves a command sent over rollerd's communica‐
116 tions channel by a client program. The command and the command's
117 data are sent in each message.
118
119 The command and the command's data are returned to the caller.
120
121 rollmgr_sendcmd(closeflag,cmd,data)
122 rollmgr_sendcmd() sends a command to rollerd. The command must be
123 one of the commands from the table below. This interface creates a
124 communications channel to rollerd and sends the message. The chan‐
125 nel is not closed, in case the caller wants to receive a response
126 from rollerd.
127
128 The available commands and their required data are:
129
130 command data purpose
131 ------- ---- -------
132 ROLLCMD_DISPLAY 1/0 start/stop rollerd's
133 graphical display
134 ROLLCMD_DSPUB zone-name a DS record has been
135 published
136 ROLLCMD_DSPUBALL none DS records published for all
137 zones in KSK rollover phase 6
138 ROLLCMD_ROLLALL none force all zones to start
139 ZSK rollover
140 ROLLCMD_ROLLKSK zone-name force a zone to start
141 KSK rollover
142 ROLLCMD_ROLLREC rollrec-name change rollerd's rollrec file
143 ROLLCMD_ROLLZONE zone-name force a zone to start
144 ZSK rollover
145 ROLLCMD_RUNQUEUE none rollerd runs through
146 its queue
147 ROLLCMD_SHUTDOWN none stop rollerd
148 ROLLCMD_SLEEPTIME seconds-count set rollerd's sleep time
149 ROLLCMD_STATUS none get rollerd's status
150
151 The data aren't checked for validity by rollmgr_sendcmd(); validity
152 checking is a responsibility of rollerd.
153
154 If the caller does not need a response from rollerd, then closeflag
155 should be set to CHANNEL_CLOSE; if a response is required then
156 closeflag should be CHANNEL_WAIT. These values are boolean values,
157 and the constants aren't required.
158
159 On success, 1 is returned. If an invalid command is given, 0 is
160 returned.
161
162 rollmgr_getresp()
163 After executing a client command sent via rollmgr_sendcmd(),
164 rollerd will send a response to the client. rollmgr_getresp()
165 allows the client to retrieve the response.
166
167 A return code and a response string are returned, in that order.
168 Both are specific to the command sent.
169
170 rollmgr_verifycmd(cmd)
171 rollmgr_verifycmd() verifies that cmd is a valid command for
172 rollerd. 1 is returned for a valid command; 0 is returned for an
173 invalid command.
174
176 1. rollmgr_getid() attempts to exclusively lock the id file. Set a
177 timer if this matters to you.
178
179 2. rollmgr_getid() has a nice little race condition. We should lock
180 the file prior to opening it, but we can't do so without it being open.
181
183 Copyright 2005-2007 SPARTA, Inc. All rights reserved. See the COPYING
184 file included with the DNSSEC-Tools package for details.
185
187 Wayne Morrison, tewok@users.sourceforge.net
188
190 rollctl(1)
191
192 Net::DNS::SEC::Tools::keyrec.pm(3) Net::DNS::SEC::Tools::rolllog.pm(3)
193 Net::DNS::SEC::Tools::rollrec.pm(3)
194
195 rollerd(8)
196
197
198
199perl v5.8.8 2008-02-15 rollmgr(3)