1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
.\" 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 14, 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 REST 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 program 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 localhost,
port 8080. 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:
|
