DragonFly On-Line Manual Pages
MRTG-PING-PROBE(1) User Contributed Perl Documentation MRTG-PING-PROBE(1)
NAME
mrtg-ping-probe - a round trip time and packet loss probe for MRTG
SYNOPSIS
mrtg-ping-probe [ -hsvV ] [ -d deadtime ] [ -k count ] [ -l length ] [
-o ping_options ] [ -p [factor*]item/[factor*]item ] [ -r
[rsh:][user@]host[:osname] ] [ -t timeout ] host
DESCRIPTION
mrtg-ping-probe pings the given host host and prints on stdout two
lines extracted from the ping output. The default is to print the
maximum, and the minimum round trip time.
It is meant to be called by the Multi Router Traffic Grapher (MRTG).
OPTIONS
-h print help on stdout and exit.
-v Be more verbose.
-V Print version number on stderr and exit.
-d deadtime
Specifies the value we return for round trip times in case we
assume that the target is down. The default is zero. We
assume that the target is unreachable, if we cannot find the
ping summary or if the ping program was aborted because of a
set timeout.
For WAN connections that usually have round trip times of 10ms
and higher, ranges of zero round trip time are highly visible.
In a LAN environment, you might set it to a high value, e.g.
999, which however might change the scale of the graphs in such
a way that you hardly see the regular round trip times. You
might use mrtg-misc-probe's pong option to generate a graph
that shows reachability of targets, instead.
-k count
Specifies the number of of ping packets to be sent. The
default is to send 10 ping packets.
-l length
Use length as the length of the data portion of the ICMP ECHO
request packet. The default length is 56 data bytes.
-o ping_options
Pass ping_options to the ping program. You can use this
generic option to e.g. pass an option to ping to suppress
displaying addresses as host names. This helps to prevent the
ping to fail because it cannot map hostnames to IP addresses
and vice versa. To pass several arguments, enclose the options
in quotes. Check the documentation of your ping program for
possible options.
-p [factor*]item/[factor*]item
Pick the values you want mrtg-ping-probe to return. Allowed
values for item are: min, max, avg, loss, or an integer. Each
item can be preceded by a integer factor used to multiply the
value returned by the ping program. The default pick-list is
min/max.
To display ping times in microseconds instead of milliseconds,
use: -p 1000*max/1000*min.
-r [rsh:][user@]host[:osname]
Not Yet Implemented
run ping on remote host host, as user user (or as local user,
if no user is given). Uses rsh -n to start program on remote
host, unless you provide a different program name. If the
remote host has a different system type than the local host (if
the osname is different) you have to say so.
This option can be used if you run mrtg on a host that cannot
ping to the final target, and you cannot install mrtg and/or
perl on the intermediate host used to ping the final target.
-s Silent mode. Do not generate error messages if there is no
response from the ping program or if it ran into the timeout.
Usually cron will mail you these error messages, which might be
helpful to debug problems.
-t timeout
Abort the external ping program after timeout seconds. A
timeout value of zero (the default) means, we do not abort the
external ping program.
If mrtg-ping-probe seems to hang forever, check your ping
program, it might be a version that wants to receive the given
number of ECHO_RESPONSE packets instead of just sending them.
If your target is unreachable, these pings ping forever.
You want to choose timeout as short as possible to leave mrtg
enough time for all your other targets, but long enough so you
do not abort pings (too often). You might use (count * worst
case round trip time) as a starting point. (Or install a ping
program that is not broken ;-)
If your perl installation does not implement the built-in
alarm() function, the timeout option will be ignored. You will
get a warning about this only in verbose mode (option -v). I
have not found a perl installation on Windows that implements
the alarm() built-in function on Win32. So basically on
Windows the timeout option is not working.
RETURN VALUE
The program exits with an exit value 0, if it believes it was
successful.
EXAMPLES
mrtg-ping-probe ricochet
Retrieves the maximum and minimum round trip time to the host
ricochet, using the default length and count.
mrtg-ping-probe -p max/avg ricochet
Retrieves the maximum and average round trip time to the host
ricochet, using the default length and count.
mrtg-ping-probe -p '1000*max/1000*avg' ricochet
Retrieves the maximum and average round trip time to the host
ricochet multiplied by a factor of 1000, using the default length
and count.
mrtg-ping-probe -k 17 -l 1000 192.168.192.42
Retrieves the maximum and minimum round trip time to the host
192.168.192.42, using 17 1000 data bytes pings.
mrtg-ping-probe -o -n ricochet.pwo.de
Suppress displaying addresses as host names on Solaris 2 (to
protect from DNS problems causing the ping to fail) by passing
option -n to the ping program.
Note that in this example `-n' is not an option for mrtg-ping-
probe, but gets passed to the ping program.
mrtg-ping-probe -o '-n -I 3' ricochet.pwo.de
Pass several options -n -I 3 to the ping program.
mrtg-ping-probe -p loss/loss ricochet.pwo.de
Monitors the packet loss for the link to host ricochet.pwo.de.
FILES
mrtg-ping-probe uses an external ping program, like /usr/sbin/ping.
SEE ALSO
mrtg(1), mrtg-ping-cfg, ping(1), mrtg.cfg-ping, mrtg-misc-probe(1)
http://www.mrtg.org/
http://pwo.de/projects/mrtg/
DIAGNOSTICS
FATAL: Not yet configured for osname
Currently mrtg-ping-probe depends on an external ping program,
which every operating systems hides in another place. Also
different programs require different arguments. We have a
configuration table listing the ping program for each operating
systems. You have to figure out how to call which program on your
platform, and add to the information to the table. Please
contribute back any additions, so I can include them in the next
version.
ERROR: ignoring superfluous arguments
More than one argument was given. mrtg-ping-probe will ignore all
but the first argument. The first argument is taken as a hostname
or IP address of an host and mrtg-ping-probe will try to ping it.
FATAL: ping what?
No argument was given. mrtg-ping-probe terminates, as there is
nothing to ping.
FATAL: option option requires numeric argument.
The argument for option option was not an integer number.
FATAL: Can't open ping: some reason
mrtg-ping-probe was not able to execute the external ping program.
Check the pathname and permissions of the external ping program.
some reason might give some useful hints.
ERROR: external ping hit timeout timeout, assuming target host is
unreachable
We ran into a timeout pinging the target host host. You might have
to increase the timeout value (Option -t) if this happens when the
target is up and the round trip time just happens to be longer than
usual.
The captured output of the ping program is printed and will
(hopefully) give further hints why this problem occurred.
This message is not printed if mrtg-ping-probe runs in silent mode
(Option -s).
ERROR: Could not find ping summary for host
mrtg-ping-probe was not able to find the ping summary. Most
likely, the host is not reachable. If your operating system
changed (e.g. it was upgraded to a new version, or a new version of
the ping program was installed), it might also be necessary to
change the regular expression that extracts the round trip times.
You might want to use the perl script check-ping-fmt (which is part
of the source distribution) to test the regular expression.
The captured output of the ping program is printed and will
(hopefully) give further hints why this problem occurred.
This message is not printed if mrtg-ping-probe runs in silent mode
(Option -s).
ERROR: Could not find packet loss summary for host
mrtg-ping-probe was not able to find the packet loss summary. If
your operating system changed (e.g. it was upgraded to a new
version, or a new version of the ping program was installed), it
might also be necessary to change the regular expression that
extracts the packet loss. You might want to use the perl script
check-ping-fmt (which is part of the source distribution) to test
the regular expression.
The captured output of the ping program is printed and will
(hopefully) give further hints why this problem occurred.
This message is not printed if mrtg-ping-probe runs in silent mode
(Option -s).
RESTRICTIONS
mrtg-ping-probe currently depends on an external ping(1) program. If
the external program does not support an option, the option given to
mrtg-ping-probe will be ignored.
Under freebsd release 3.x or later, ping option -s packet-length (mrtg-
ping-probe option -l length) is only allowed to be used when we run as
root (which we should not), therefore this option is silently removed
on freebsd before we call the external ping program.
BUGS
This program has way too many options and tries to support too many
different systems.
Using this program to monitor sub-millisecond round trip times or
packet loss might be questionable.
Option -r, remote execution of the ping program, is not yet
implemented.
COPYRIGHT
Copyright (c) 1997-2003 Peter W. Osel <pwo@pwo.de>. All Rights
Reserved.
See the file COPYRIGHT in the distribution for the exact terms.
AUTHOR
Written by Peter W. Osel <pwo@pwo.de>. http://pwo.de/
perl v5.20.3 2016-02-18 MRTG-PING-PROBE(1)