/ 
Nagios-Plugin-OverHTTP-0.16
River stage zero No dependents
/ Nagios::Plugin::OverHTTP

NAME

Nagios::Plugin::OverHTTP - Nagios plugin to check over HTTP.

VERSION

This documentation refers to Nagios::Plugin::OverHTTP version 0.16

SYNOPSIS

my $plugin = Nagios::Plugin::OverHTTP->new(
    url => 'https://myserver.net/nagios/check_some_service.cgi',
);

my $plugin = Nagios::Plugin::OverHTTP->new(
    hostname => 'myserver.net',
    path     => '/nagios/check_some_service.cgi',
    ssl      => 1,
);

my $status  = $plugin->status;
my $message = $plugin->message;

DESCRIPTION

This Nagios plugin provides a way to check services remotely over the HTTP protocol.

CONSTRUCTOR

This is fully object-oriented, and as such before any method can be used, the constructor needs to be called to create an object to work with.

new

This will construct a new plugin object.

new(%attributes)

%attributes is a HASH where the keys are attributes (specified in the "ATTRIBUTES" section).

new($attributes)

$attributes is a HASHREF where the keys are attributes (specified in the "ATTRIBUTES" section).

new_with_options

This is identical to "new", except with the additional feature of reading the @ARGV in the invoked scope. @ARGV will be parsed for command-line arguments. The command-line can contain any variable that "new" can take. Arguments should be in the following format on the command line:

--url=http://example.net/check_something
--url http://example.net/check_something
# Note that quotes may be used, based on your shell environment

# For Booleans, like SSL, you would use:
--ssl    # Enable SSL
--no-ssl # Disable SSL

# For HashRefs, like warning and critical, you would use:
--warning name=value --warning name2=value2

ATTRIBUTES

# Set an attribute
$object->attribute_name($new_value);

# Get an attribute
my $value = $object->attribute_name;

autocorrect_unknown_html

Added in version 0.10; be sure to require this version for this feature.

This is a Boolean of wether or not to attempt to add a meaningful first line to the message when the HTTP response did not include the Nagios plugin status and the message looks like HTML and has multiple lines. The title of the web page will be added to the first line, or the first H1 element will. The default for this is on.

critical

Added in version 0.14; be sure to require this version for this feature.

This is a hash reference specifying different performance names (as the hash keys) and what threshold they need to be to result in a critical status. The format for the threshold is specified in "PERFORMANCE THRESHOLD".

default_status

Added in version 0.09; be sure to require this version for this feature.

This is the default status that will be used if the remote plugin does not return a status. The default is "UNKNOWN." The status may be the status number, or a string with the name of the status, like:

$plugin->default_status('CRITICAL');

hostname

This is the hostname of the remote server. This will automatically be populated if "url" is set.

parser

Added in version 0.14; be sure to require this version for this feature.

This is a response parser object that does Nagios::Plugin::OverHTTP::Parser. By default, it is the Nagios::Plugin::OverHTTP::Parser::Standard parser.

path

This is the path to the remove Nagios plugin on the remote server. This will automatically be populated if "url" is set.

ssl

This is a Boolean of whether or not to use SSL over HTTP (HTTPS). This defaults to false and will automatically be updated to true if a HTTPS URL is set to "url".

timeout

This is a positive integer for the timeout of the HTTP request. If set, this will override any timeout defined in the useragent for the duration of the request. The plugin will not permanently alter the timeout in the useragent. This defaults to not being set, and so the useragent's timeout is used.

url

This is the URL of the remote Nagios plugin to check. If not supplied, this will be constructed automatically from the "hostname" and "path" attributes.

useragent

This is the useragent to use when making requests. This defaults to LWP::Useragent with no options. Currently this must be an LWP::Useragent object.

verb

Added in version 0.12; be sure to require this version for this feature.

This is the HTTP verb that will be used to make the HTTP request. The default value is GET.

warning

Added in version 0.14; be sure to require this version for this feature.

This is a hash reference specifying different performance names (as the hash keys) and what threshold they need to be to result in a warning status. The format for the threshold is specified in "PERFORMANCE THRESHOLD".

METHODS

check

This will run the remote check. This is usually not needed, as attempting to access the message or status will result in the check being performed.

create_request

Added in version 0.14; be sure to require this version for this feature.

This will create a HTTP::Request object from the arguments including any additional headers added by the plugin. This method takes a HASH as the argument with the following keys:

method

This is the HTTP request method. By default this will be GET.

url

Required. This is the URL to request.

request

Added in version 0.14; be sure to require this version for this feature.

This will return a Nagios::Plugin::OverHTTP::Response object representing the plugin response from the server. This method takes either one argument which is a HTTP::Request object that will use "useragent" to make the request, or a HASH with the same arguments as "create_request". The response is parsed with the parser in "parser".

run

This will run the plugin in a standard way. The message will be printed to standard output and the status code will be returned. Good for doing the following:

my $plugin = Plugin::Nagios::OverHTTP->new_with_options;

exit $plugin->run;

PERFORMANCE THRESHOLD

Anywhere a performance threshold is accepted, the threshold value can be in any of the following formats (same as listed in http://nagiosplug.sourceforge.net/developer-guidelines.html#THRESHOLDFORMAT):

<number>

This will cause an alert if the level is less than zero or greater than <number>.

<number>:

This will cause an alert if the level is less than <number>.

~:<number>

This will cause an alert if the level is greater than <number>.

<number>:<number2>

This will cause an alert if the level is less than <number> or greater than <number2>.

@<number>:<number2>

This will cause an alert if the level is greater than or equal to <number> and less than or equal to <number2>. This is basically the exact opposite of the previous format.

PROTOCOL

HTTP STATUS

The protocol that this plugin uses to communicate with the Nagios plugins is unique to my knowledge. If anyone knows another way that plugins are communicating over HTTP then let me know.

A request that returns a 5xx status will automatically return as CRITICAL and the plugin will display the error code and the status message (this will typically result in 500 Internal Server Error).

A request that returns a 2xx status will be parsed using the methods listed in "HTTP BODY" and "HTTP HEADER".

If the response results is a redirect, the "useragent" will automatically redirect the response and all processing will ultimately be done on the final response. Any other status code will cause the plugin to return as UNKNOWN and the plugin will display the error code and the status message.

HTTP BODY

The body of the HTTP response will be the output of the plugin unless the header "X-Nagios-Information" is present. To determine what the status code will be, the following methods are used:

  1. If a the header X-Nagios-Status is present, the value from that is used as the output. See "X-Nagios-Status".

  2. If the header was not present, then the status will be extracted from the body of the response. The very first set of all capital letters is taken from the body and used to determine the result. The different possibilities for this is listed in "NAGIOS STATUSES".

HTTP HEADER

The following HTTP headers have special meanings:

X-Nagios-Information

Added in version 0.12; be sure to require this version for this feature.

If this header is present, then the content of this header will be used as the message for the plugin. Note: the body will not be parsed. This is meant as an indication that the Nagios output is solely contained in the headers. This MUST contain the message ONLY. If this header appears multiple times, each instance is appended together with line breaks in the same order for multiline plugin output support.

X-Nagios-Information: Connection to database succeeded
X-Nagios-Information: 'www'@'localhost'

X-Nagios-Performance

Added in version 0.14; be sure to require this version for this feature.

This header specifies various performance data from the plugin. This will add performance to the list of any data collected from the response body as specified in "HTTP BODY". Many performance data may be contained in a single header seperated by spaces any many headers may be specified.

X-Nagios-Performance: 'connect time'=0.0012s

X-Nagios-Status

This header specifies the status. When this header is specified, then this is will override any other location where the status can come from. The content of this header MUST be either the decimal return value of the plugin or the status name in all capital letters. The different possibilities for this is listed in "NAGIOS STATUSES". If the header appears more than once, the first occurance is used.

X-Nagios-Status: OK

NAGIOS STATUSES

0 OK

$Nagios::Plugin::OverHTTP::STATUS_OK

1 WARNING

$Nagios::Plugin::OverHTTP::STATUS_WARNING

2 CRITICAL

$Nagios::Plugin::OverHTTP::STATUS_CRITICAL

3 UNKNOWN

$Nagios::Plugin::OverHTTP::STATUS_UNKNOWN

EXAMPLE

The following is an example of a simple bootstrapping of a plugin on a remote server.

#!/usr/bin/env perl

use strict;
use warnings;

my $output = qx{/usr/local/libexec/nagios/check_users2 -w 100 -c 500};

my $status = $? > 0 ? $? >> 8 : 3;

printf "X-Nagios-Status: %d\n", $status;
print  "Content-Type: text/plain\n\n";
print  $output if $output;

exit 0;

DEPENDENCIES

AUTHOR

Douglas Christopher Wilson, <doug at somethingdoug.com>

ACKNOWLEDGEMENTS

  • Alex Wollangk contributed the idea and code for the "X-Nagios-Information" header.

  • Peter van Eijk pushed me to get performance data handling implemented.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-nagios-plugin-overhttp at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Nagios-Plugin-OverHTTP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Nagios::Plugin::OverHTTP

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2009-2012 Douglas Christopher Wilson, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

  • the Artistic License version 2.0.