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

NAME

6       Net::DNS::SEC::Tools::realmmgr - Communicate with the DNSSEC-Tools
7       realms manager.
8

SYNOPSIS

10         use Net::DNS::SEC::Tools::realmmgr;
11
12         $dir = realmmgr_dir();
13
14         $idfile = realmmgr_idfile();
15
16         $id = realmmgr_getid();
17
18         realmmgr_dropid();
19
20         realmmgr_rmid();
21
22         realmmgr_cmdint();
23
24         $runflag = realmmgr_running();
25
26         realmmgr_halt();
27
28         realmmgr_channel(1);
29         ($cmd,$data) = realmmgr_getcmd();
30         $ret = realmmgr_verifycmd($cmd);
31
32         realmmgr_sendcmd(CHANNEL_CLOSE,REALMCMD_STARTREALM,"example-realm");
33
34         realmmgr_sendcmd(CHANNEL_WAIT,REALMCMD_STARTREALM,"example-realm");
35         ($retcode, $respmsg) = realmmgr_getresp();
36

DESCRIPTION

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

GENERAL INTERFACES

44       The interfaces to the Net::DNS::SEC::Tools::realmmgr module are given
45       below.
46
47       realmmgr_dir()
48           This routine returns dtrealms's directory.
49
50       realmmgr_idfile()
51           This routine returns dtrealms's id file.
52
53       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
58           Return Values:
59
60               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
64       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
68           Return Values:
69
70               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
74       realmmgr_rmid()
75           This interface deletes dtrealms's id file.
76
77           Return Values:
78
79                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
84       realmmgr_cmdint()
85           This routine informs dtrealms that a command has been sent via
86           realmmgr_sendcmd().
87
88           Return Values:
89
90               -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
95       realmmgr_running()
96           This routine determines if dtrealms is running and returns a value
97           indicating the status.
98
99           Return Values:
100
101                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
106       realmmgr_halt()
107           This routine informs dtrealms to shut down.
108
109           In the current implementation, the return code from the kill()
110           command is returned.
111
112               -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

DTREALMS COMMUNICATIONS INTERFACES

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
124           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
128           Return Values:
129
130                 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
138       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
143       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
151           The command and the command's data are returned to the caller.
152
153       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
160           The available commands and their required data are:
161
162              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
181           The data aren't checked for validity by realmmgr_sendcmd();
182           validity checking is a responsibility of dtrealms.
183
184           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
189           On success, 1 is returned.  If an invalid command is given, 0 is
190           returned.
191
192       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
197           A return code and a response string are returned, in that order.
198           Both are specific to the command sent.
199
200       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
205           1 is returned for a valid command; 0 is returned for an invalid
206           command.
207

WARNINGS

209       1.  realmmgr_getid() attempts to exclusively lock the id file.  Set a
210       timer if this matters to you.
211
212       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

AUTHOR

220       Wayne Morrison, tewok@tislabs.com
221

SEE ALSO

223       realmctl(1)
224
225       dtrealms(8)
226
227       Net::DNS::SEC::Tools::realm.pm(3), Net::DNS::SEC::Tools::rolllog.pm(3),
228       Net::DNS::SEC::Tools::rollmgr.pm(3)
229
230
231
232perl v5.34.0                      2021-07-21                       realmmgr(3)
Impressum