NAME

       Net::DNS::SEC::Tools::rolllog - DNSSEC-Tools rollover logging interfaces.

SYNOPSIS

         use Net::DNS::SEC::Tools::rolllog;

         @levels = rolllog_levels();

         $curlevel = rolllog_level();
         $oldlevel = rolllog_level("info");
         $oldlevel = rolllog_level(LOG_ERR,1);

         $curlogfile = rolllog_file();
         $oldlogfile = rolllog_file("-");
         $oldlogfile = rolllog_file("/var/log/roll.log",1);

         $loglevelstr = rolllog_str(8)
         $loglevelstr = rolllog_str("info")

         $ret = rolllog_num("info");

         $bool = rolllog_validlevel($newlevel);
         $bool = rolllog_validlevel(8);

         $curtz = rolllog_gettz();
         $oldtz = rolllog_settz('local');

         rolllog_log(LOG_INFO,"example.com","zone is valid");

DESCRIPTION

       The Net::DNS::SEC::Tools::rolllog module provides logging interfaces for the rollover
       programs.  The logging interfaces allow log messages to be recorded.  rollerd must be
       running, as it is responsible for updating the log file.

       Each log message is assigned a particular logging level.  The valid logging 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.

       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.

LOGGING INTERFACES

       rolllog_file(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 log file 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.

       rolllog_gettz()
           This routine returns the timezone selector currently in use.  This value may be either
           'gmt' (for Greenwich Mean Time) or 'local' (for the host's local time.)

       rolllog_level(newlevel,useflag)
           This routine sets and retrieves the logging level for rollerd.  The newlevel argument
           specifies the new logging level to be set.  newlevel may be given in either text or
           numeric form.

           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.

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

       rolllog_log(level,group,message)
           The rolllog_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.

       rolllog_num(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.

       rolllog_settz(tzsel)
           This routine sets the timezone to be used for timestamps in messages written to the
           log.  This tzsel value may be either 'gmt' (Greenwich Mean Time) or 'local' (for the
           host's local time.)  tzsel may be uppercase or lowercase; the value will be converted
           to lowercase.  If no value is passed, then the default will be used.

           The current timezone selector is returned.  If an invalid selector is given, then an
           undefined value is returned.

       rolllog_str(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.

       rolllog_validlevel(level)
           This interface returns a boolean value indicating if the given logging level is valid.

           The level argument is the logging level to be validated.  It may be a numeric or
           textual value.

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)

       rollerd(8)

       Net::DNS::SEC::Tools::rollmgr.pm(3)