rollmgr(3pm)						User Contributed Perl Documentation					      rollmgr(3pm)

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 6
	      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-2012 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)

perl v5.14.2							    2012-06-28							      rollmgr(3pm)