1realmmgr(3) User Contributed Perl Documentation realmmgr(3)
2
6 Net::DNS::SEC::Tools::realmmgr - Communicate with the DNSSEC-Tools
7 realms manager.
8
10 use Net::DNS::SEC::Tools::realmmgr;
11 $dir = realmmgr_dir();
13 $idfile = realmmgr_idfile();
15 $id = realmmgr_getid();
17 realmmgr_dropid();
19 realmmgr_rmid();
21 realmmgr_cmdint();
23 $runflag = realmmgr_running();
25 realmmgr_halt();
27 realmmgr_channel(1);
29 ($cmd,$data) = realmmgr_getcmd();
30 $ret = realmmgr_verifycmd($cmd);
31 realmmgr_sendcmd(CHANNEL_CLOSE,REALMCMD_STARTREALM,"example-realm");
33 realmmgr_sendcmd(CHANNEL_WAIT,REALMCMD_STARTREALM,"example-realm");
35 ($retcode, $respmsg) = realmmgr_getresp();
36
38 The Net::DNS::SEC::Tools::realmmgr module provides standard, platform-
39 independent methods for a program to communicate with DNSSEC-Tools'
40 dtrealms realms manager. There are two interface classes described
41 here: general interfaces and communications interfaces.
42
44 The interfaces to the Net::DNS::SEC::Tools::realmmgr module are given
45 below.
46 realmmgr_dir()
48 This routine returns dtrealms's directory.
49 realmmgr_idfile()
51 This routine returns dtrealms's id file.
52 realmmgr_getid()
54 This routine returns dtrealms's process id. If a non-zero value is
55 passed as an argument, the id file will be left open and accessible
56 through the PIDFILE file handle. See the WARNINGS section below.
57 Return Values:
59 On success, the first portion of the file contents
61 (up to 80 characters) is returned.
62 -1 is returned if the id file does not exist.
63 realmmgr_dropid()
65 This interface ensures that another instance of dtrealms is not
66 running and then creates a id file for future reference.
67 Return Values:
69 1 - the id file was successfully created for this process
71 0 - another process is already acting as dtrealms
72 -1 - unable to create the id file
73 realmmgr_rmid()
75 This interface deletes dtrealms's id file.
76 Return Values:
78 1 - the id file was successfully deleted
80 0 - no id file exists
81 -1 - the calling process is not dtrealms
82 -2 - unable to delete the id file
83 realmmgr_cmdint()
85 This routine informs dtrealms that a command has been sent via
86 realmmgr_sendcmd().
87 Return Values:
89 -1 - an invalid process id was found for dtrealms
91 Anything else indicates the number of processes that were
92 signaled.
93 (This should only ever be 1.)
94 realmmgr_running()
96 This routine determines if dtrealms is running and returns a value
97 indicating the status.
98 Return Values:
100 1 - dtrealms is running.
102 0 - The process listed in the dtrealms process id file
103 is not running.
104 -1 - Unable to get the dtrealms process id.
105 realmmgr_halt()
107 This routine informs dtrealms to shut down.
108 In the current implementation, the return code from the kill()
110 command is returned.
111 -1 - an invalid process id was found for dtrealms
113 Anything else indicates the number of processes that were
114 signaled.
115 (This should only ever be 1.)
116
118 realmmgr_channel(serverflag)
119 This interface sets up a persistent channel for communications with
120 dtrealms. If serverflag is true, then the server's side of the
121 channel is created. If serverflag is false, then the client's side
122 of the channel is created.
123 Currently, the connection may only be made to the localhost. This
125 may be changed to allow remote connections, if this is found to be
126 needed.
127 Return Values:
129 1 - Communications channel successfully established.
131 0 - Unable to connect to the server.
132 -1 - Unable to create a Unix socket.
133 -2 - Unable to bind to the Unix socket. (server only)
134 -3 - Unable to change the permissions on the Unix socket. (server only)
135 -4 - Unable to listen on the Unix socket. (server only)
136 -5 - The socket name was longer than allowed for a Unix socket.
137 realmmgr_queuecmd(cmdname, value)
139 This interface internally remembers a command and it's optional
140 value for later processing. See the realmmgr_getcmd() next for
141 further details.
142 realmmgr_getcmd()
144 realmmgr_getcmd() processes commands that need to be dealt with.
145 If there are any internally stored commands queued via the
146 realmmgr_queuecmd() function, they are dealt with first. After
147 that it retrieves a command sent over dtrealms's communications
148 channel by a client program. The command and the command's data
149 are sent in each message.
150 The command and the command's data are returned to the caller.
152 realmmgr_sendcmd(closeflag,cmd,data)
154 realmmgr_sendcmd() sends a command to dtrealms. The command must
155 be one of the commands from the table below. This interface
156 creates a communications channel to dtrealms and sends the message.
157 The channel is not closed, in case the caller wants to receive a
158 response from dtrealms.
159 The available commands and their required data are:
161 command data purpose
163 ------- ---- -------
164 REALMCMD_COMMAND realm, command run command in a realm
165 REALMCMD_DISPLAY 1/0 start/stop dtrealms'
166 graphical display
167 REALMCMD_GETSTATUS none currently unused
168 REALMCMD_LOGFILE log filename change the log file
169 REALMCMD_LOGLEVEL log level set a new logging level
170 REALMCMD_LOGMSG log message add a message to the log
171 REALMCMD_LOGTZ timezone set timezone for log messages
172 REALMCMD_NODISPLAY 0 stop dtrealms' graphical display
173 REALMCMD_REALMSTATUS none get status of the realms
174 REALMCMD_SHUTDOWN none stop dtrealms and its realms
175 REALMCMD_STARTALL none start all stopped realms
176 REALMCMD_STOPALL none stop all running realms
177 REALMCMD_STARTREALM realm name restart a suspended realm
178 REALMCMD_STOPREALM realm name stop realm
179 REALMCMD_STATUS none get status of dtrealms
180 The data aren't checked for validity by realmmgr_sendcmd();
182 validity checking is a responsibility of dtrealms.
183 If the caller does not need a response from dtrealms, then
185 closeflag should be set to CHANNEL_CLOSE; if a response is required
186 then closeflag should be CHANNEL_WAIT. These values are boolean
187 values, and the constants aren't required.
188 On success, 1 is returned. If an invalid command is given, 0 is
190 returned.
191 realmmgr_getresp()
193 After executing a client command sent via realmmgr_sendcmd(),
194 dtrealms will send a response to the client. realmmgr_getresp()
195 allows the client to retrieve the response.
196 A return code and a response string are returned, in that order.
198 Both are specific to the command sent.
199 realmmgr_verifycmd(cmd)
201 realmmgr_verifycmd() verifies that cmd is a valid command for
202 dtrealms. 1 is returned for a valid command; 0 is returned for an
203 invalid command.
204 1 is returned for a valid command; 0 is returned for an invalid
206 command.
207
209 1. realmmgr_getid() attempts to exclusively lock the id file. Set a
210 timer if this matters to you.
211 2. realmmgr_getid() has a nice little race condition. We should lock
213 the file prior to opening it, but we can't do so without it being open.
214
216 Copyright 2012-2014 SPARTA, Inc. All rights reserved. See the COPYING
217 file included with the DNSSEC-Tools package for details.
218
220 Wayne Morrison, tewok@tislabs.com
221
223 realmctl(1)
224 dtrealms(8)
226 Net::DNS::SEC::Tools::realm.pm(3), Net::DNS::SEC::Tools::rolllog.pm(3),
228 Net::DNS::SEC::Tools::rollmgr.pm(3)
229perl v5.38.0 2023-07-19 realmmgr(3)