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)