.TH XYMONPING 1 "Version 4.3.28: 17 Jan 2017" "Xymon"
.SH NAME
xymonping \- Xymon ping tool
.SH SYNOPSIS
.B "xymonping [\-\-retries=N] [\-\-timeout=N] [IP\-addresses]"

.SH DESCRIPTION
.I xymonping(1)
is used for ping testing of the hosts monitored by the
.I xymon(7)
monitoring system. It reads a list of IP addresses from stdin,
and performs a "ping" check to see if these hosts are alive.
It is normally invoked by the
.I xymonnet(1)
utility, which performs all of the Xymon network tests.

Optionally, if a list of IP-addresses is passed as command-line
arguments, it will ping those IP's instead of reading them 
from stdin.

xymonping only handles IP-addresses, not hostnames.

xymonping was inspired by the
.I fping(1)
tool, but has been written from scratch to implement a fast
ping tester without much of the overhead found in other
such utilities. The output from xymonping is similar to that 
of "fping \-Ae".

xymonping probes multiple systems in parallel, and the runtime
is therefore mostly dependent on the timeout-setting and the
number of retries. With the default options, xymonping takes
approximately 18 seconds to ping all hosts (tested with an
input set of 1500 IP addresses).

.SH SUID-ROOT INSTALLATION REQUIRED
xymonping needs to be installed with suid-root privileges,
since it requires a "raw socket" to send and receive ICMP
Echo (ping) packets.

xymonping is implemented such that it immediately drops
the root privileges, and only regains them to perform two
operations: Obtaining the raw socket, and optionally binding
it to a specific source address. These operations are performed
as root, the rest of the time xymonping runs with normal user
privileges. Specifically, no user-supplied data or network data
is used while running with root privileges. Therefore it 
should be safe to provide xymonping with the necessary
suid-root privileges.

.SH OPTIONS
.IP \-\-retries=N
Sets the number of retries for hosts that fail to respond to
the initial ping, i.e. the number of ping probes sent in addition
to the initial probe. The default is \-\-retries=2, to ping a host 
3 times before concluding that it is not responding.

.IP \-\-timeout=N
Determines the timeout (in seconds) for ping probes. If a
host does not respond within N seconds, it is regarded as
unavailable, unless it responds to one of the retries.
The default is \-\-timeout=5.

.IP \-\-responses=N
xymonping normally stops pinging a host after receiving a single
response, and uses that to determine the round-trip time. If the
first response takes longer to arrive - e.g. because of additional
network overhead when first determining the route to the target host -
it may skew the round-trip-time reports. You can then use this option
to require N responses, and xymonping will calculate the round-trip
time as the average of all of responsetimes.

.IP \-\-max\-pps=N
Maximum number of packets per second. This limits the number of
ICMP packets xymonping will send per second, by enforcing a
brief delay after each packet is sent. The default setting is
to send a maximum of 50 packets per second. Note that increasing
this may cause flooding of the network, and since ICMP packets
can be discarded by routers and other network equipment, this
can cause erratic behaviour with hosts recorded as not responding
when they are in fact OK.

.IP \-\-source=ADDRESS
Use ADDRESS as the source IP address of the ping packets sent.
On multi-homed systems, allows you to select the source IP of
the hosts going out, which might be necessary for ping to work.

.IP \-\-debug
Enable debug output. This prints out all packets sent and received.

.SH "SEE ALSO"
xymon(7), xymonnet(1), fping(1)