Nagios::Object - perl objects/parser for Nagios config & log

[Al Tobey]

This announcement is also at:
http://use.perl.org/~tobert/journal/16004

I've been working on Nagios::Object, a set of perl modules for parsing
and working with Nagios objects in perl.  The first cut of this module
is available at http://www.tobert.org/perl/Nagios-Object-0.01.tar.gz . 
It's a little rough around the edges, but I need people to look at the
API and tell me what it needs.

There are three modules in the distribution (for now):
Nagios::Object - represent Nagios objects as perl objects
Nagios::Object::Config - parse Nagios object configs
Nagios::StatusLog - parse Nagios status logs

Some possible modules in the future:
Nagios::Default - parse files like nagios.cfg (will be in v0.02)
DBD::Nagios - DBI/SQL interface to the Nagios configuration
Nagios::HTML - HTML widgets for Nagios configuration & statuses

My hope is that as time goes by, these modules make it possible to
rewrite the Nagios CGIs in perl.  I also plan on looking at making the
backend of Nagios::Object be able to read Nagios v2's DBM cache or even
get it directly from Nagios via SHM or something crazy like that.

All (451) of my tests succeed on my Linux laptop, but I'd like for some
of you out there to beat on it and let me know what you think.  I'm
planning on posting version 0.02 to CPAN this weekend if I get some
feedback.

Attachment is output of pod2text for Nagios::Object.

-Al Tobey

-------------- next part --------------
NAME
    Nagios::Object

DESCRIPTION
    This module contains the code for creating perl objects to represent any
    of the Nagios objects. All of the perl classes are auto-generated at
    compile-time, so it's pretty trivial to add new attributes or even
    entire objects. The following is a list of currently supported classes:

     Nagios::TimePeriod
     Nagios::Command
     Nagios::Contact
     Nagios::ContactGroup
     Nagios::Host
     Nagios::Service
     Nagios::HostGroup
     Nagios::ServiceEscalation
     Nagios::HostDependency
     Nagios::HostEscalation
     Nagios::HostGroupEscalation
     Nagios::ServiceDependency

EXAMPLE
     use Nagios::Object;
     my $generic_host = Nagios::Host->new(
        register                     => 0,
        parents                      => undef,
        check_command                => $some_command,
        max_check_attempts           => 3,
        checks_enabled               => 1,
        event_handler                => $some_command,
        event_handler_enabled        => 0,
        low_flap_threshhold          => 0,
        high_flap_threshhold         => 0,
        flap_detection_enabled       => 0,
        process_perf_data            => 1,
        retain_status_information    => 1,
        retain_nonstatus_information => 1,
        notification_interval        => $timeperiod,
        notification_options         => [qw(d u r)],
        notifications_enabled        => 1,
        stalking_options             => [qw(o d u)]
     );

     my $localhost = Nagios::Host->new(
        use       => $generic_host,
        host_name => "localhost",
        alias     => "Loopback",
        address   => "127.0.0.1"
     );

     my $hostname = $localhost->host_name();
     printf "max check attempts for $hostname is %s.\n",
         $localhost->max_check_attempts;
 
     $localhost->set_event_handler(
         Nagios::Command->new(
             command_name => "new_event_handler",
             command_line => "/bin/true"
         )
     );

METHODS
    new()
        Create a new object of one of the types listed above.
        Nagios::Host->new( ... );

    dump()
        Output a Nagios define { } block from an object. This is still
        EXPERIMENTAL, but may eventually be robust enough to use for a
        configuration GUI.

         print $object->dump();

    name()
        This method is common to all calles created by this module. It
        should always return the textual name for an object. It is used
        internally by the Nagios::Object modules to allow polymorphism,
        which is what makes this module so compact. Also of note is that
        this is the only way to retrieve the name of a template, since they
        have a "name" field that they are identified by.

         my $svc_desc = $service->name;
         my $hostname = $host->name;

        Which is just short for:

         my $svc_desc = $service->service_description;
         my $hostname = $service->host_name;

    register()
        Returns true/undef to indicate whether the calling object is
        registerable or not.

         if ( $object->register ) { print $object->name, " is registerable." }

    has_attribute()
        Returns true/undef to indicate whether the calling object has the
        attribute specified as the only argument.

         # check to see if $object has attribute "command_line"
         die if ( !$object->has_attribute("command_line") );

    list_attributes()
        Returns a list of valid attributes for the calling object.

         my @host_attributes = $host->list_attributes();

    attribute_type()
        Returns the type of data expected by the object's set_ method for
        the given attribute.

         my $type = $host->attribute_type("notification_period");

    attribute_is_list()
        Returns true if the attribute is supposed to be a list (ARRAYREF).

         if ( $object->attribute_is_list("members") ) {
            $object->set_members( [$member] );
         } else {
            $object->set_members( $member );
         }

    attribute_allows_undef()
        Returns true if the attribute provided is allowed to have a value of
        undef. Setting an attribute to undef will cause the templates to be
        searched until a non-undef answer is found.

        NOTE: this may go away, since I'm not sure if it's really useful at
        all.

         my $answer = $object->attribute_allows_undef("command_line");

AUTHOR
    Al Tobey <tobeya at cpan.org>

    Thank you to the fine people of #perl on freenode.net for helping me
    with some hairy code and silly optimizations.

WARNINGS
    See AUTHOR.