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'");
    
    #
    # Ways to get a Logging object.
    #

    # 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");

    # get an existing logging object
    $logging = $conf->get_logging () 
        or $logging->die ("couldn't get logging");
    
    #
    # Operations that can be performed on a Logging object.
    #

    # 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'");

    $ret = $logging->delete_channel ('my_file_chan')
                or $ret->die ("couldn't delete channel `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 (
            qw (eventlib 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
 }
 or
 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
                        # WARG is to be provided only in case WHERE eq 'BEFORE 
                        # or WHERE eq 'AFTER'
 PARENT => reference,   # to the Conf object datastructure.

Class constructor. Create a new Unix::Conf::Bind8::Conf::Logging object, initialize it, and return it on success, or an Err object on failure. Do not use this constructor directly. Use the Unix::Conf::Bind8::Conf::new_logging () method instead.

category ()

 Arguments
 'CATEGORY-NAME',
 LIST                           
 or 
 [ LIST ]                       # of legal channel names

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.

add_to_category ()

 Arguments
 category,
 LIST           # of channel names

Object method. Adds to the channels defined for category `categtory' and returns true on success, an Err object otherwise.

delete_from_category ()

 Arguments
 category,
 LIST           # of channel names

Object method. Deletes from the channels defined for category `category' and returns true on success, an Err object otherwise. If all the channels defined for that category is deleted, the category itself is deleted.

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.