--- name: "Net::DNS::SEC::Tools::realmmgr" section: "3pm" platform: "linux" package: "dnssec-tools" version: "2.2.3-16" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Net::DNS::SEC::Tools::realmmgr" --- # Net::DNS::SEC::Tools::realmmgr(3pm) Communicate with the DNSSEC-Tools realms manager. ## NAME Net::DNS::SEC::Tools::realmmgr - Communicate with the DNSSEC-Tools realms manager. ## SYNOPSIS ``` use Net::DNS::SEC::Tools::realmmgr; $dir = realmmgr_dir(); $idfile = realmmgr_idfile(); $id = realmmgr_getid(); realmmgr_dropid(); realmmgr_rmid(); realmmgr_cmdint(); $runflag = realmmgr_running(); realmmgr_halt(); realmmgr_channel(1); ($cmd,$data) = realmmgr_getcmd(); $ret = realmmgr_verifycmd($cmd); realmmgr_sendcmd(CHANNEL_CLOSE,REALMCMD_STARTREALM,"example-realm"); realmmgr_sendcmd(CHANNEL_WAIT,REALMCMD_STARTREALM,"example-realm"); ($retcode, $respmsg) = realmmgr_getresp(); ``` ## DESCRIPTION The **Net::DNS::SEC::Tools::realmmgr** module provides standard, platform-independent methods for a program to communicate with DNSSEC-Tools' **dtrealms** realms manager. There are two interface classes described here: general interfaces and communications interfaces. ## GENERAL INTERFACES The interfaces to the **Net::DNS::SEC::Tools::realmmgr** module are given below. - ***realmmgr\_dir()*** This routine returns **dtrealms**'s directory. - ***realmmgr\_idfile()*** This routine returns **dtrealms**'s id file. - ***realmmgr\_getid()*** This routine returns **dtrealms**'s process id. If a non-zero value is passed as an argument, the id file will be left open and accessible through the PIDFILE file handle. See the WARNINGS section below. Return Values: ``` On success, the first portion of the file contents (up to 80 characters) is returned. -1 is returned if the id file does not exist. ``` - ***realmmgr\_dropid()*** This interface ensures that another instance of **dtrealms** is not running and then creates a id file for future reference. Return Values: ``` 1 - the id file was successfully created for this process 0 - another process is already acting as dtrealms -1 - unable to create the id file ``` - ***realmmgr\_rmid()*** This interface deletes **dtrealms**'s id file. Return Values: ``` 1 - the id file was successfully deleted 0 - no id file exists -1 - the calling process is not dtrealms -2 - unable to delete the id file ``` - ***realmmgr\_cmdint()*** This routine informs **dtrealms** that a command has been sent via ***realmmgr\_sendcmd()***. Return Values: ``` -1 - an invalid process id was found for dtrealms Anything else indicates the number of processes that were signaled. (This should only ever be 1.) ``` - ***realmmgr\_running()*** This routine determines if dtrealms is running and returns a value indicating the status. Return Values: ``` 1 - dtrealms is running. 0 - The process listed in the dtrealms process id file is not running. -1 - Unable to get the dtrealms process id. ``` - ***realmmgr\_halt()*** This routine informs **dtrealms** to shut down. In the current implementation, the return code from the **kill()** command is returned. ``` -1 - an invalid process id was found for dtrealms Anything else indicates the number of processes that were signaled. (This should only ever be 1.) ``` ## DTREALMS COMMUNICATIONS INTERFACES - *realmmgr\_channel(serverflag)* This interface sets up a persistent channel for communications with **dtrealms**. If *serverflag* is true, then the server's side of the channel is created. If *serverflag* is false, then the client's side of the channel is created. Currently, the connection may only be made to the localhost. This may be changed to allow remote connections, if this is found to be needed. Return Values: ``` 1 - Communications channel successfully established. 0 - Unable to connect to the server. -1 - Unable to create a Unix socket. -2 - Unable to bind to the Unix socket. (server only) -3 - Unable to change the permissions on the Unix socket. (server only) -4 - Unable to listen on the Unix socket. (server only) -5 - The socket name was longer than allowed for a Unix socket. ``` - *realmmgr\_queuecmd(cmdname, value)* This interface internally remembers a command and it's optional value for later processing. See the ***realmmgr\_getcmd()*** next for further details. - ***realmmgr\_getcmd()*** ***realmmgr\_getcmd()*** processes commands that need to be dealt with. If there are any internally stored commands queued via the ***realmmgr\_queuecmd()*** function, they are dealt with first. After that it retrieves a command sent over **dtrealms**'s communications channel by a client program. The command and the command's data are sent in each message. The command and the command's data are returned to the caller. - *realmmgr\_sendcmd(closeflag,cmd,data)* ***realmmgr\_sendcmd()*** sends a command to **dtrealms**. The command must be one of the commands from the table below. This interface creates a communications channel to **dtrealms** and sends the message. The channel is not closed, in case the caller wants to receive a response from **dtrealms**. The available commands and their required data are: ``` command data purpose ------- ---- ------- REALMCMD_COMMAND realm, command run command in a realm REALMCMD_DISPLAY 1/0 start/stop dtrealms' graphical display REALMCMD_GETSTATUS none currently unused REALMCMD_LOGFILE log filename change the log file REALMCMD_LOGLEVEL log level set a new logging level REALMCMD_LOGMSG log message add a message to the log REALMCMD_LOGTZ timezone set timezone for log messages REALMCMD_NODISPLAY 0 stop dtrealms' graphical display REALMCMD_REALMSTATUS none get status of the realms REALMCMD_SHUTDOWN none stop dtrealms and its realms REALMCMD_STARTALL none start all stopped realms REALMCMD_STOPALL none stop all running realms REALMCMD_STARTREALM realm name restart a suspended realm REALMCMD_STOPREALM realm name stop realm REALMCMD_STATUS none get status of dtrealms ``` The data aren't checked for validity by ***realmmgr\_sendcmd()***; validity checking is a responsibility of **dtrealms**. If the caller does not need a response from **dtrealms**, then *closeflag* should be set to **CHANNEL\_CLOSE**; if a response is required then *closeflag* should be **CHANNEL\_WAIT**. These values are boolean values, and the constants aren't required. On success, 1 is returned. If an invalid command is given, 0 is returned. - ***realmmgr\_getresp()*** After executing a client command sent via ***realmmgr\_sendcmd()***, **dtrealms** will send a response to the client. ***realmmgr\_getresp()*** allows the client to retrieve the response. A return code and a response string are returned, in that order. Both are specific to the command sent. - *realmmgr\_verifycmd(cmd)* ***realmmgr\_verifycmd()*** verifies that *cmd* is a valid command for **dtrealms**. 1 is returned for a valid command; 0 is returned for an invalid command. 1 is returned for a valid command; 0 is returned for an invalid command. ## WARNINGS 1\. ***realmmgr\_getid()*** attempts to exclusively lock the id file. Set a timer if this matters to you. 2\. ***realmmgr\_getid()*** has a nice little race condition. We should lock the file prior to opening it, but we can't do so without it being open. ## COPYRIGHT Copyright 2012-2014 SPARTA, Inc. All rights reserved. See the COPYING file included with the DNSSEC-Tools package for details. ## AUTHOR Wayne Morrison, tewok@tislabs.com ## SEE ALSO **realmctl(1)** **dtrealms(8)** **Net::DNS::SEC::Tools::realm.pm(3)**, **Net::DNS::SEC::Tools::rolllog.pm(3)**, **Net::DNS::SEC::Tools::rollmgr.pm(3)**