/ 
Net-Prober-0.03
River stage zero No dependents
/ Net::Prober

NAME

Net::Prober - Probes network hosts for downtime, latency, etc...

VERSION

version 0.03

SYNOPSIS

use Net::Prober;

my $result = Net::Prober::probe({
    proto => 'tcp',
    port => 'ssh',
    host => 'localhost',
    timeout => 0.5,
});

# $result = {
#   ok => 1,
#   time => 0.0002345,
#   host => '127.0.0.1',
#   port => 22,
# }

# or...

my $result = Net::Prober::probe({
    proto => 'http',
    host => 'www.opera.com',
    url => '/browser',
    match => 'Faster',
});

DESCRIPTION

This module allows to probe hosts for downtime or latency.

You can use it if you want to know things like:

can we connect to host X on port whatever?
how long it takes to connect to host X on port whatever?
does host X respond to icmp pings?
check if host X responds within a given timeout

Various types of probes are implemented, namely:

tcp

Opens a socket, connects and closes the socket.

udp

Same as TCP, but using a UDP connection.

http

Makes an HTTP connection, and requests a given URL (or / if none given). Can check that the content of the response matches a given regular expression, or has an exact md5 hash.

NAME

Net::Prober - Probes network hosts for downtime, latency, etc...

MOTIVATION

There must be tons of ready-made modules that do exactly what this module tries to do. So why?

One reason is that, as ridiculous as this might sound, I couldn't find any CPAN module to do this.

For example, I looked at the nagios code, as Nagios does this (and more) but I couldn't find anything even remotely similar.

Another reason is that I need this code to be very compact and flexible enough to be wired directly to a small config file, to be able to specify the probe arguments as JSON. This is inspired by the Varnish probe config block:

# This is my config file.
# It's JSON presumably...

"backends": {
    "1.2.3.4" : {
        "datacenter" : "norway1",
        "probe" : {
            "proto": "tcp",
            "port" : "8432",
            "timeout" : 1.0,
        },
    },

    # ...
}

FUNCTIONS

port_name_to_num($port)

Converts a given port name (ex.: ssh, or http) to a number. Returns the number as result.

If the given port doesn't look like a port name, then you get back what you passed as argument, unchanged.

probe( \%probe_spec )

Runs a probe against a given host/port.

\%probe_spec allows you to specify what kind of probe you want to run and against what hostname and port.

Allowed hash keys are:

proto

What type of probe you want to run. Can be any of tcp, http, icmp.

Default is tcp.

host

Hostname or IP to be probed.

port

Port or service to be probed. Examples:

23, 'ssh', 8432, 'http', 'echo'
timeout

The maximum time to wait for a result. In seconds.

Returns the results as hashref. Example:

my $result = Net::Prober::probe({
    host => 'localhost',
    port => 'ssh',
    proto => 'tcp',
    timeout => 0.5,
});

You will get *at least* these keys:

$result = {
    ok => 1,
    time => 0.001234,    # how long it took (s)
}

or in case of failure:

$result = {
    ok => 0,
    time => 0.001234,
    reason => 'Why the probe failed',
}

http probe

The HTTP probe support additional arguments:

match

Checks if the content matches a given regular expression. Example:

match => 'Not found'
match => 'Log(in|out)'
md5

Checks if the whole content of the response matches a given MD5 hash. You can calculate the MD5 of a given URL with:

wget -q -O - http://your.url.here | md5sum
url

What URL to download. By default it uses /.

AUTHOR

Cosimo Streppone <cosimo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Cosimo Streppone.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.