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

NAME

       Net::DNS::SEC::Tools::rollmgr - Communicate with the DNSSEC-Tools rollover manager.

SYNOPSIS

         use Net::DNS::SEC::Tools::rollmgr;

         $dir = rollmgr_dir();

         $idfile = rollmgr_idfile();

         $id = rollmgr_getid();

         rollmgr_dropid();

         rollmgr_rmid();

         rollmgr_cmdint();

         $runflag = rollmgr_running();

         rollmgr_halt();

         rollmgr_phasemsg('long');

         rollmgr_channel(1);
         ($cmd,$data) = rollmgr_getcmd();
         $ret = rollmgr_verifycmd($cmd);

         rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZSK,"example.com");

         rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZSK,"example.com");
         ($retcode, $respmsg) = rollmgr_getresp();

         $descr = rollmgr_get_phase('KSK', $phasecnt);

DESCRIPTION

       The Net::DNS::SEC::Tools::rollmgr module provides standard, platform-independent methods
       for a program to communicate with DNSSEC-Tools' rollerd rollover manager.  There are two
       interface classes described here:  general interfaces and communications interfaces.

GENERAL INTERFACES

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

       rollmgr_dir()
           This routine returns rollerd's directory.

       rollmgr_idfile()
           This routine returns rollerd's id file.

       rollmgr_getid()
           This routine returns rollerd'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.

       rollmgr_dropid()
           This interface ensures that another instance of rollerd 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 rollerd
              -1 - unable to create the id file

       rollmgr_rmid()
           This interface deletes rollerd's id file.

           Return Values:

                1 - the id file was successfully deleted
                0 - no id file exists
               -1 - the calling process is not rollerd
               -2 - unable to delete the id file

       rollmgr_cmdint()
           This routine informs rollerd that a command has been sent via rollmgr_sendcmd().

           Return Values:

               -1 - an invalid process id was found for rollerd
               Anything else indicates the number of processes that were
               signaled.
               (This should only ever be 1.)

       rollmgr_running()
           This routine determines if rollerd is running and returns a value indicating the
           status.

           Return Values:

                1 - rollerd is running.
                0 - The process listed in the rollerd process id file
                    is not running.
               -1 - Unable to get the rollerd process id.

       rollmgr_halt()
           This routine informs rollerd to shut down.

           In the current implementation, the return code from the kill() command is returned.

               -1 - an invalid process id was found for rollerd
               Anything else indicates the number of processes that were
               signaled.
               (This should only ever be 1.)

       rollmgr_phasemsg()
           This routine sets the phase-message length.  of phase-related log messages used by
           rollerd.  The valid levels are "long" and "short", with "long" being the default
           value.

           The long message length means that a phase description will be included with some log
           messages.  For example, the long form of a message about ZSK rollover phase 3 will
           look like this:  "ZSK phase 3 (Waiting for old zone data to expire from caches)".

           The short message length means that a phase description will not be included with some
           log messages.  For example, the short form of a message about ZSK rollover phase 3
           will look like this:  "ZSK phase 3".

           Return Values:

                1 - the phase-message length was set
                0 - an invalid phase-message length was specified

ROLLERD COMMUNICATIONS INTERFACES

       rollmgr_channel(serverflag)
           This interface sets up a persistent channel for communications with rollerd.  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.

       rollmgr_queuecmd(cmdname, value)
           This interface internally remembers a command and it's optional value for later
           processing.  See the rollmgr_getcmd() next for further details.

       rollmgr_getcmd()
           rollmgr_getcmd() processes commands that need to be dealt with.  If there are any
           internally stored commands queued via the rollmgr_queuecmd() function, they are dealt
           with first.  After that it retrieves a command sent over rollerd'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.

       rollmgr_sendcmd(closeflag,cmd,data)
           rollmgr_sendcmd() sends a command to rollerd.  The command must be one of the commands
           from the table below.  This interface creates a communications channel to rollerd and
           sends the message.  The channel is not closed, in case the caller wants to receive a
           response from rollerd.

           The available commands and their required data are:

              command              data            purpose
              -------              ----            -------
              ROLLCMD_DISPLAY      1/0             start/stop rollerd's
                                                   graphical display
              ROLLCMD_DSPUB        zone-name       a DS record has been
                                                   published
              ROLLCMD_DSPUBALL     none            DS records published for all
                                                   zones in KSK rollover phase 5
              ROLLCMD_GETSTATUS    none            currently unused
              ROLLCMD_LOGFILE      log filename    change the log file
              ROLLCMD_LOGLEVEL     log level       set a new logging level
              ROLLCMD_LOGMSG       log message     add a message to the log
              ROLLCMD_LOGTZ        timezone        set timezone for log messages
              ROLLCMD_MERGERRFS    rollrec files   merge rollrec files with the
                                                   current rollrec file
              ROLLCMD_PHASEMSG     long/short      set long or short phase
                                                   messages
              ROLLCMD_QUEUELIST    none            returns the names and next
                                                   event time of zones in the
                                                   "soon queue
                                                   (experimental)
              ROLLCMD_QUEUESTATUS  none            returns information about
                                                   the state of soon-queue
                                                   processing
                                                   (experimental)
              ROLLCMD_ROLLALL      none            resume rollover for all
                                                   suspended zones
              ROLLCMD_ROLLALLZSKS  none            force all zones to start
                                                   ZSK rollover
              ROLLCMD_ROLLKSK      zone-name       force a zone to start
                                                   KSK rollover
              ROLLCMD_ROLLREC      rollrec-name    change rollerd's rollrec file
              ROLLCMD_ROLLZONE     zone name       restart rollover for a
                                                   suspended zone
              ROLLCMD_ROLLZSK      zone-name       force a zone to start
                                                   ZSK rollover
              ROLLCMD_RUNQUEUE     none            rollerd runs through
                                                   its queue
              ROLLCMD_SHUTDOWN     none            stop rollerd
              ROLLCMD_SIGNZONE     zone            sign a zone (no rollover)
              ROLLCMD_SIGNZONEs    all or active   sign all or active zones
              ROLLCMD_SKIPALL      none            suspend all rollovers
              ROLLCMD_SKIPZONE     zone name       suspend rollover for a
                                                   rolling zone
              ROLLCMD_SLEEPTIME    seconds-count   set rollerd's sleep time
              ROLLCMD_SPLITRRF     rollrec-name,   move a set of zones from the
                                   zone names      current rollrec file into a
                                                   new rollrec file
              ROLLCMD_STATUS       none            get status of rollerd
              ROLLCMD_ZONEGROUP    zonegroup name  get info on all zonegroups
                                                   or a particular zonegroup
              ROLLCMD_ZONELOG      zone name       set the logging level for
                                   logging level   a particular zone
              ROLLCMD_ZONESTATUS   none            get status of the zones
              ROLLCMD_ZSARGS       zonesigner args add a (probably temporary)
                                   zone list       set of options to the signing
                                                   of a set of zones

           The data aren't checked for validity by rollmgr_sendcmd(); validity checking is a
           responsibility of rollerd.

           If the caller does not need a response from rollerd, 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.

       rollmgr_getresp()
           After executing a client command sent via rollmgr_sendcmd(), rollerd will send a
           response to the client.  rollmgr_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.

       rollmgr_verifycmd(cmd)
           rollmgr_verifycmd() verifies that cmd is a valid command for rollerd.  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.

       rollmgr_get_phase(phasetype, phasenum)
           rollmgr_get_phase() returns a description of a particular phase for a particular type
           of rollover.  phasetype specifies the type of rollover, and may be "KSK" or "ZSK".
           phasenum specifies the phase number whose description is desired.  This must be an
           integer between 0 and 7 (KSK) or 0 and 4 (ZSK).  If an invalid phase type or phase
           number is specified, an empty string is returned.

WARNINGS

       1.  rollmgr_getid() attempts to exclusively lock the id file.  Set a timer if this matters
       to you.

       2.  rollmgr_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 2005-2013 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

       rollctl(1)

       Net::DNS::SEC::Tools::keyrec.pm(3) Net::DNS::SEC::Tools::rolllog.pm(3)
       Net::DNS::SEC::Tools::rollrec.pm(3)

       rollerd(8)