Linux Certif

Toute la documentation sur la certification Linux LPI

Net::DNS::SEC::Tools::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();
 
   rollmgr_halt();
 
   @levels = rollmgr_loglevels();
 
   $curlevel = rollmgr_loglevel();
   $oldlevel = rollmgr_loglevel("info");
   $oldlevel = rollmgr_loglevel(LOG_ERR,1);
 
   $curlogfile = rollmgr_logfile();
   $oldlogfile = rollmgr_logfile("-");
   $oldlogfile = rollmgr_logfile("/var/log/roll.log",1);
 
   $loglevelstr = rollmgr_logstr(8)
   $loglevelstr = rollmgr_logstr("info")
 
   $ret = rollmgr_lognum("info");
 
   rollmgr_log(LOG_INFO,"example.com","zone is valid");
 
   rollmgr_channel(1);
   ($cmd,$data) = rollmgr_getcmd();
   $ret = rollmgr_verifycmd($cmd);
 
   rollmgr_sendcmd(CHANNEL_CLOSE,ROLLCMD_ROLLZONE,"example.com");
 
   rollmgr_sendcmd(CHANNEL_WAIT,ROLLCMD_ROLLZONE,"example.com");
   ($retcode, $respmsg) = rollmgr_getresp();
 
 

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 three interface classes described here: general interfaces, logging 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
 
 

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_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.)
 
 

LOGGING INTERFACES

rollmgr_loglevels()

This routine returns an array holding the text forms of the user-settable logging levels. The levels are returned in order, from most verbose to least.

rollmgr_loglevel(newlevel,useflag)

This routine sets and retrieves the logging level for rollerd. The newlevel argument specifies the new logging level to be set. The valid levels are:

     text       numeric  meaning
     ----       -------  -------
     tmi           1     The highest level -- all log messages
                         are saved.
     expire        3     A verbose countdown of zone expiration
                         is given.
     info          4     Many informational messages are recorded.
     phase         6     Each zone's current rollover phase
                         is given.
     err           8     Errors are recorded.
     fatal         9     Fatal errors are saved.
 
 

newlevel may be given in either text or numeric form. The levels include all numerically higher levels. For example, if the log level is set to phase, then err and fatal messages will also be recorded.

The useflag argument is a boolean that indicates whether or not to give a descriptive message and exit if an invalid logging level is given. If useflag is true, the message is given and the process exits; if false, -1 is returned.

If given with no arguments, the current logging level is returned. In fact, the current level is always returned unless an error is found. -1 is returned on error.

rollmgr_logfile(newfile,useflag)

This routine sets and retrieves the log file for rollerd. The newfile argument specifies the new log file to be set. If newfile exists, it must be a regular file.

The useflag argument is a boolean that indicates whether or not to give a descriptive message if an invalid logging level is given. If useflag is true, the message is given and the process exits; if false, no message is given. For any error condition, an empty string is returned.

rollmgr_lognum(loglevel)

This routine translates a text log level (given in loglevel) into the associated numeric log level. The numeric log level is returned to the caller.

If loglevel is an invalid log level, -1 is returned.

rollmgr_logstr(loglevel)

This routine translates a log level (given in loglevel) into the associated text log level. The text log level is returned to the caller.

If loglevel is a text string, it is checked to ensure it is a valid log level. Case is irrelevant when checking loglevel.

If loglevel is numeric, it is must be in the valid range of log levels. undef is returned if loglevel is invalid.

rollmgr_log(level,group,message)

The rollmgr_log() interface writes a message to the log file. Log messages have this format:

         timestamp: group: message
 
 

The level argument is the message's logging level. It will only be written to the log file if the current log level is numerically equal to or less than level.

group allows messages to be associated together. It is currently used by rollerd to group messages by the zone to which the message applies.

The message argument is the log message itself. Trailing newlines are removed.

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.

rollmgr_getcmd()

rollmgr_getcmd() 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_LOGFILE      log-file        set rollerd's log filename
    ROLLCMD_LOGLEVEL     log-level       set rollerd's logging level
    ROLLCMD_ROLLALL      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       force a zone to start
                                         ZSK rollover
    ROLLCMD_RUNQUEUE     none            rollerd runs through
                                         its queue
    ROLLCMD_SHUTDOWN     none            stop rollerd
    ROLLCMD_SLEEPTIME    seconds-count   set rollerd's sleep time
    ROLLCMD_STATUS       none            get rollerd's status
 
 

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.

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

AUTHOR

Wayne Morrison, tewok@users.sourceforge.net

SEE ALSO

rollctl(1)

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

rollerd(8)