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

NAME

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

VERSION

version 0.17

SYNOPSIS

use Net::Prober;

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

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

# or...

my $result = Net::Prober::probe({
    protocol => '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...

LOGGING TO SYSLOG

It is possible to enable automatic logging to syslog. It was in fact the default before version 0.08.

To do that, include in your script:

use Net::Prober;
$Net::Prober::Probe::Base::USE_SYSLOG = 1;

Not very pretty, I know.

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" : {
            "protocol": "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:

protocol

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',
    protocol => '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 /.

up_status_re

By default, any HTTP response with status 2xx or 3xx (redirect) will be considered successful. However, it is also possible to specify your own custom regular expression instead. In this way, you can consider "healthy" a host that replies to your HTTP probe with a 404 (not found) or other status code.

Example:

up_status_re => '^[234]'
up_status_re => '^30[12]$'

icmp probe

Uses Net::Ping to perform ICMP probes, that is, to send a ping packet to the given host and port.

size of ping packets is not currently supported.

protocol is an additional key that allows to specify whether the pings should be sent via UDP or TCP. Remember that to send ICMP UDP packets you need root privileges.

The ICMP probe code will automatically switch to TCP if the necessary privileges are not available.

AUTHOR

Cosimo Streppone <cosimo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.