Provided by: dnssec-tools_2.0-1_all bug


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


         use Net::DNS::SEC::Tools::realmmgr;

         $dir = realmmgr_dir();

         $idfile = realmmgr_idfile();

         $id = realmmgr_getid();




         $runflag = realmmgr_running();


         ($cmd,$data) = realmmgr_getcmd();
         $ret = realmmgr_verifycmd($cmd);


         ($retcode, $respmsg) = realmmgr_getresp();


       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.


       The interfaces to the Net::DNS::SEC::Tools::realmmgr module are given below.

           This routine returns dtrealms's directory.

           This routine returns dtrealms's id file.

           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.

           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

           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

           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
               (This should only ever be 1.)

           This routine determines if dtrealms is running and returns a value indicating the

           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.

           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
               (This should only ever be 1.)


           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() 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

           The command and the command's data are returned to the caller.

           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.

           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

           A return code and a response string are returned, in that order.  Both are specific to
           the command sent.

           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.


       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 2012-2013 SPARTA, Inc.  All rights reserved.  See the COPYING file included with
       the DNSSEC-Tools package for details.


       Wayne Morrison,