NAME

Unix::Conf::Bind8::Conf::Logging - Class representing the 'logging' directive in a Bind8 Configuration file.

SYNOPSIS

    use Unix::Conf::Bind8;
    my ($conf, $logging, $channel, $ret);

    $conf = Unix::Conf::Bind8->new_conf (
        FILE        => '/etc/named.conf',
        SECURE_OPEN => 1,
    ) or $conf->die ("couldn't open `named.conf'");
    
    # get an existing logging object
    $logging = $conf->get_logging () 
        or $logging->die ("couldn't get logging");
    
    # or create a new logging object
    $logging = $conf->new_logging (
        CHANNELS => [
            {
                NAME             => 'my_file_chan',
                OUTPUT           => 'file',
                FILE             => {
                                  PATH     => '/var/log/named/file_chan.log',
                                  VERSIONS => 3,
                                  SIZE     => '10k',
                },
                SEVERITY         => { NAME => 'debug', LEVEL => '3' },
                'PRINT-TIME'     => 'yes',
                'PRINT-SEVERITY' => 'yes',
                'PRINT-CATEGORY' => 'yes'
            },
            {
                NAME             => 'my_syslog_chan',
                OUTPUT           => 'syslog',
                SYSLOG           => 'daemon',
                SEVERITY         => { NAME => 'info' },
                'PRINT-TIME'     => 'yes',
                'PRINT-SEVERITY' => 'yes',
                'PRINT-CATEGORY' => 'yes'
            },
        ],
        CATEGORIES => [
            [ db                => [ qw (my_file_chan default_debug default_syslog) ] ],
            [ 'lame-servers'    => [ qw (null) ], ],
            [ cname             => [ qw (null) ], ],
            ['xfer-out'         => [ qw (default_stderr) ], ]
        ],
                WHERE   => 'FIRST',
    ) or $logging->die ("couldn't create logging");

    # create new channel
    $channel = $logging->new_channel (
        NAME             => 'new_chan',
        OUTPUT           => 'syslog',
        SYSLOG           => 'info',
        SEVERITY         => { NAME => 'debug', LEVEL => 3 },
        'PRINT-TIME'     => 'yes',
        'PRINT-SEVERITY' => 'no',
        'PRINT-CATEGORY  => 'yes',
    ) or $channel->die ("couldn't create `new_chan'");

    # or get an already defined channel
    $channel = $logging->get_channel ('my_file_chan)
        or $channel->die ("couldn't get `my_file_chan'");

    # For further operations on channel objects refer to the 
    # documentation for Unix::Conf::Bind8::Conf::Logging::Channel

    # delete define channel
    $ret = $logging->delete_channel ('my_syslog_chan')
        or $ret->die 

    # iterate through defined channels 
    printf "%s\n", $_->name () for ($logging->channels ());

    # set channels for categories
    $ret = $logging->category (
            'eventlib', [ qw (new_chan default_syslog) ]
    ) or $ret->die ("couldn't set channels for category `eventlib'");
    
    # delete categories
    $ret = $logging->delete_category ('db') 
        or $ret->die ("coudn't delete category `db'");

    # print out defined categories
    # note the difference in the usage for channels () and categories ().
    print "$_\n" for ($logging->categories ());

DESCRIPTION

This class has methods to handle the various aspects of the logging statement. Channels are implemented as a sub class, while categories are handled within this class itself.

new ()

 Arguments
 CHANNELS    => [ 
     { 
         NAME             => 'channel-name',
         OUTPUT           => 'value',        # syslog|file|null
         FILE             => {               # only if OUTPUT eq 'file'
                   PATH     => 'file-name',
                   VERSIONS => number,
                   SIZE     => size_spec,
         },
         SYSLOG           => 'facility-name',# only if OUTPUT eq 'syslog'
         SEVERITY         => 'severity-name',
         'PRINT-TIME'     => 'value',        # yes|no
         'PRINT-SEVERITY' => 'value',        # yes|no
         'PRINT-CATEGORY' => 'value',        # yes|no
     },
 ],
 CATEGORIES  => [
     [ CATEGORY-NAME    => [ qw (channel1 channel2) ] ],
 ],
 WHERE             => 'FIRST'|'LAST'|'BEFORE'|'AFTER'
 WARG              => Unix::Conf::Bind8::Conf::Directive subclass object

Class constructor. Create a new Unix::Conf::Bind8::Conf::Logging object, initialize it, and return it on success, or an Err object on failure.

category ()

 Arguments
 'CATEGORY-NAME',
 [ qw (channel1 channel2) ],      # optional

Object method. Get/Set the object's channel attribute. If the an array reference is passed as the second argument, sets the catetgory 'CATEGORY-NAME' channels to the elements of the array ref. Returns true if able to set channels if array ref passed as the second argument, an Err object otherwise. If second argument is not passed, then returns the channels set for category as an array reference if defined, an Err object otherwise.

delete_category ()

 Arguments
 'CATEGORY-NAME',

Object method. Deletes category named by 'CATEGORY-NAME', and returns true if successful, an Err object otherwise.

categories ()

Object method. Iterate through defined categories, returning names of all defined categories in a list context, or one at a time in a scalar context.

new_channel ()

 Arguments
 [
     {
         NAME             => 'channel-name',
         OUTPUT           => 'value',        # syslog|file|null
         FILE             => 'file-name',    # only if OUTPUT eq 'file'
         SYSLOG           => 'facility-name',# only if OUTPUT eq 'syslog'
         SEVERITY         => 'severity-name',
         'PRINT-TIME'     => 'value',        # yes|no
         'PRINT-SEVERITY' => 'value',        # yes|no
         'PRINT-CATEGORY' => 'value',        # yes|no
     },
 ],

Object method. This method is a wrapper around the class constructor for Unix::Conf::Bind8::Conf::Logging::Channel. Use this method instead of the accessing the constructor directly. Returns a new Unix::Conf::Bind8::Conf::Logging::Channel object on success, an Err object otherwise.

get_channel ()

 Arguments
 'CHANNEL-NAME',

Object method. Returns a channel object for 'CHANNEL-NAME', if defined (either through a call to new_channel (), or one defined while parsing the configuration file), an Err object otherwise.

delete_channel ()

 Arguments
 'CHANNEL-NAME'

Object method. Deletes channel object for 'CHANNEL-NAME', if defined (either through a call to new_channel (), or one defined while parsing the configuration file), an Err object otherwise.

channels ()

Class/Object method Iterates through the list of defined Unix::Conf::Bind8::Conf::Logging::Channel objects, returning one at a time when called in scalar context, or a list of all defined objects when called in list context.