PING903

NAME
SYNOPSIS
DESCRIPTION
CONFIGURATION FILE
OPTIONS
BUGS
SEE ALSO
COPYRIGHT

NAME

ping903 - high-performance ICMP monitoring daemon

SYNOPSIS

ping903 [-fhsVv] [-c FILE]

DESCRIPTION

Ping903 is a daemon designed to periodically monitor a very large number of remote hosts using ICMP ECHO packets. Hosts are monitored in separate probes, each probe consisting of a predefined number of ICMP requests sent with certain interval between them. Probes are repeated periodically.

The round-trip statistics is collected for each host and is available for querying via REST API. A separate querying utility ping903q(1) is provided, which allows the user to request the information about each particular host, or all monitored hosts at once.

Upon startup the program reads its configuration from file /etc/ping903.conf, and detaches itself from the controlling terminal. This daemon becomes a supervisor process for the monitor process, which it spawns. The supervisor controls that the monitoring process is properly functioning and restarts it if it terminates abnormally.

The monitoring process, in turn, is responsible for periodic polling of the configured hosts, maintaining the statistics information and answering incoming REST requests.

The program logs its activities using syslog channel daemon.

The set of monitored IP addresses consists of two parts. The immutable IP list is supplied in the configuration file and cannot be altered at run-time. The mutable IP list, in contrast, is maintained via the REST API and thus can be changed while the server runs. The content of mutable IP list is preserved during server restarts.

Probes for each IP from the list are initiated periodically, each probe-interval seconds. Each probe consists of ping-count ICMP ECHO requests sent with intervals of ping-interval seconds between each of them. Obviously, these three parameters must satisfy the following relation:

ping-count * ping-interval < probe-interval

At the end of each probe the following information is computed: number of received echo replies, percentage of lost requests, minimal, average and maximal round-trip time, and its standard deviation. If more than a predefined number of echo requests (the failure tolerance number) are lost, the status of the IP is changed to "inactive".

An HTTP listener thread is responsible for returning the collected statistics and serving other requests. By default the program listens for queries on localhost, port 8080. If compiled with the support for libwrap, the access to the HTTP interface can be controlled using files /etc/hosts.allow and /etc/hosts.deny. See hosts_access(5), for details.

For information about accessing the statistics, see ping903q(1).

A utility for maintaining the mutable IP list is available from <http://git.gnu.org.ua/cgit/ping903/mangemanche.git>.

CONFIGURATION FILE

By default, the configuration is read from the file /etc/ping903.conf. See ping903.conf(5), for a detailed discussion of its syntax and available keywords. It is OK if the file does not exist. In this case ping903 will use the following built-in defaults:

data-length 56
# ip-list is empty
ping-count 10
ping-interval 1
probe-interval 60
syslog-facility daemon
tolerance 3

listen localhost:8080
access-log off
access-log-verbose off
http-backlog-size 128
# trusted-ip is empty

OPTIONS

-c FILE

Read configuration from FILE. By default, /etc/ping903.conf is read.

	-f		Remain in foreground.
	-h		Print a short usage summary.
	-s		Don’t start supervisor process.
	-V		Print program version, copyright information, and exit.
	-v		Turn on additional logging. This option can be given several times to request more verbose output. If given single -v option, the program prints at the end of each probe the total number of echo requests sent and replies received. Two options (-vv), enable additional diagnostics of invalid echo replies. Three options enable logging of each received echo reply, and four options enable verbose logging of each echo request sent. Notice that three or more -v options can produce huge amount of logs.

BUGS

Only IPv4 is currently supported.

COPYRIGHT

Copyright © 2020 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at man.gnu.org.ua.