NAME

SYNOPSIS

DESCRIPTION

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

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

SEE ALSO

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

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

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

See the file COPYRIGHT in the distribution for the exact terms.

AUTHOR