diff options
Diffstat (limited to 'doc/ping903.8')
-rw-r--r-- | doc/ping903.8 | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/doc/ping903.8 b/doc/ping903.8 new file mode 100644 index 0000000..bf76d16 --- /dev/null +++ b/doc/ping903.8 @@ -0,0 +1,139 @@ +.\" This file is part of ping903 -*- nroff -*- +.\" Copyright (C) 2020 Sergey Poznyakoff +.\" +.\" Ping903 is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 3, or (at your option) +.\" any later version. +.\" +.\" Ping903 is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>. +.TH PING903 8 "February 12, 2020" "PING903" "System Administration" +.SH NAME +ping903 \- high-performance ICMP monitoring daemon +.SH SYNOPSIS +\fBping903\fR\ + [\fB\-fhsVv\fR]\ + [\fB\-c \fIFILE\fR] +.SH DESCRIPTION +\fBPing903\fR is a daemon designed to periodically monitor a very +large number of remote hosts using ICMP ECHO packets. Hosts are +monitored in separate \fBprobes\fR, each probe consisting of a +predefined number of ICMP requests sent with certain interval between +them. Probes are repeated periodically. +.PP +The round-trip statistics is collected for each host and is available +for querying via RESTful API. A separate querying utility +.BR ping903q (1) +is provided, which allows the user to request the information about +each particular host, or all monitored hosts at once. +.PP +Upon startup the program reads its configuration from file +.BR /etc/ping903.conf , +and detaches itself from the controlling terminal. This daemon +becomes a \fIsupervisor process\fR for the monitor process, which it +spawns. The supervisor controls that the monitoring process is +properly functioning and restarts it if it terminates abnormally. +.PP +The monitoring process, in turn, is responsible for periodic polling +of the configured hosts, maintaining the statistics information and +answering the REST requests. +.PP +The progam logs its activities using syslog channel \fBdaemon\fR. +.PP +The list of IP addresses to monitor is supplied by an \fIip\-list\fR +file specified in the configuration. Probes for each IP from the list +are initiated periodically, each +.B probe\-interval +seconds. Each probe consists of +.B ping\-count +ICMP ECHO requests sent with intervals of +.B ping\-interval +seconds between each of them. Obviously, these three parameters must +satisfy the following relation: +.PP +.EX +ping-count * ping-interval < probe-interval +.EE +.PP +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 \fItolerance\fR number) are lost, the status of the IP is +changed to "inactive". +.PP +The \fBHTTP\fR listener is provided for returning the collected +statistics. By default the program listens for queries on port 8080 +on all available interfaces. If compiled with the support for +\fBlibwrap\fR, the access to the HTTP interface can be controlled +using files +.B /etc/hosts.allow +and +.BR /etc/hosts.deny . +See +.BR hosts_access (5), +for details. +.SH CONFIGURATION FILE +By default, configuration file +.B /etc/ping903.conf +is read upon startup. Its location can be changed using the +.B \-c +command line option. This file can be used to alter all configurable +parameters of +.BR ping903 . +See +.BR ping903.conf (5), +for a detailed discussion of its syntax and available keywords. Most +parameters have sensible default values and can in many cases be left +unchanged. The only setting that must be present in this file is the +.BR ip\-list +statement, which defines a file (or files), from which the program +reads the IP addresses to monitor. +.SH OPTIONS +.TP +\fB\-c \fIFILE\fR +Read configuration from \fIFILE\fR. By default, +.B /etc/ping903.conf +is read. +.TP +.B \-f +Remain in foreground. +.TP +.B \-h +Print a short usage summary. +.TP +.B \-s +Don't start supervisor process. +.TP +.B \-V +Print program version, copyright information, and exit. +.TP +.B \-v +Turn on additional logging. +.SH BUGS +Only IPv4 is currently supported. +.SH SEE ALSO +.BR ping908.conf (5), +.BR ping908q (1). +.SH COPYRIGHT +Copyright \(co 2020 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> +.br +.ad +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. +.\" Local variables: +.\" eval: (add-hook 'write-file-hooks 'time-stamp) +.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.\\-]* [0-9] \"" +.\" time-stamp-format: "%:B %:d, %:y" +.\" time-stamp-end: "\"" +.\" time-stamp-line-limit: 20 +.\" end: |