aboutsummaryrefslogtreecommitdiff
path: root/doc/ping903.8
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ping903.8')
-rw-r--r--doc/ping903.8139
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:

Return to:

Send suggestions and report system problems to the System administrator.