aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2020-09-19 21:24:38 +0300
committerSergey Poznyakoff <gray@gnu.org>2020-09-19 21:24:38 +0300
commit6c0b1a6431540c074920252a3b2a964fe9bdf99b (patch)
tree5c238a011e96674430120259b969cddd1eab09d3
parenta9974c3f5be1077909849151c14d01f5eed86576 (diff)
downloadping903-master.tar.gz
ping903-master.tar.bz2
Proof-read the docs.HEADmaster
-rw-r--r--README32
-rw-r--r--doc/ping903.819
-rw-r--r--doc/ping903.conf.526
-rw-r--r--doc/ping903.cred.58
-rw-r--r--doc/ping903q.115
-rwxr-xr-xexamples/dbload2
-rw-r--r--rc/README6
7 files changed, 54 insertions, 54 deletions
diff --git a/README b/README
index 94ec8d9..7de1140 100644
--- a/README
+++ b/README
@@ -45,13 +45,13 @@ alter the default installation paths. For example, to install to the
Please refer to the INSTALL document in this directory for a
discussion of available options to configure and their effect.
After installing the package, copy the file src/ping903.conf to
/etc/ping903.conf and edit it to your liking. This file contains
configuration settings that control the behavior of the server daemon
-and, to a certain extent, that of a query tool. The file contains
+and, to a certain extent, that of the query tool. The file contains
short annotations before each statement to help you navigate through
it. You will find a detailed discussion of the configuration file in
the manpage ping903.conf(5). What follows is a short outline, intended
for quick start.
At the very beginning you can leave most settings at their default
@@ -83,15 +83,15 @@ You are not required to keep all your IP addresses in a single file.
If necessary, you can scatter them among several files and name each
of them in a separate ip-list statement.
IP addresses listed in ip-list files form the "immutable" IP list,
called so because it cannot be altered while the program is running.
The REST API allows the user to add any number of IP addresses at
-runtime as well as remove any of IP addresses added this way. These
-addresses form the "mutable" IP list. Mutable IP list is preserved
-across program restarts.
+runtime as well as to remove any of IP addresses added this way.
+These addresses form the "mutable" IP list. Mutable IP list is
+preserved across program restarts.
This means that actually the immutable IP list is optional. You may
choose to keep monitored addresses in an external storage (an SQL
database, for example) and load them dynamically after the daemon
has started. A working example program for adding IP addresses from
a MySQL database is shipped in the examples directory. A full-fledged
@@ -99,14 +99,14 @@ client package able to add or delete keywords at runtime, both
individually or in batches and providing another features is available
from <http://git.gnu.org.ua/cgit/ping903/mangemanche.git>.
Normally, the ip-list file should contain IP addresses of the hosts to
monitor. It is OK, however, to use symbolic DNS names, too. If a
hostname resolves to a single A record, such usage is equivalent to
-placing that IP in the ip-list. However, if the hostnames resolves to
-multiple IPs, only first one will be used.
+placing that IP in the ip-list. However, if it resolves to multiple IPs,
+only the first one will be used.
By default, the server will wake up each minute and send 10 echo
requests within 1 second intervals to each registered IP. If the
number of collected replies is less than 7, the IP will be declared as
dead ("alive": false, in the returned JSON). Otherwise it is
considered alive ("alive": true).
@@ -145,15 +145,15 @@ and in the syslog channel "daemon"). To verify if the daemon is
operational, run
curl http://localhost:8080/config
This should return the running configuration.
-Within the next 'probe-interval' seconds the server will collect
-enough statistics to answer your queries. You can request information
-about any particular IP from your ip-list by running
+Within the first 'probe-interval' seconds after startup, the daemon will
+collect enough statistics to answer your queries. You can request
+information about any particular IP from your ip-list by running
ping903q IP
This will return the current status of the IP, e.g.
$ ping903q 203.0.113.1
@@ -178,17 +178,17 @@ To check the current status of all hosts, run
$ ping903q -a
Note, that depending on your settings the output can be huge.
Please refer to ping903q(1), for a detailed discussion of the tool.
-* System start-up sequence
+* Startup scripts
-To configure ping903 to start automatically at the system start-up,
-see the "rc" subdirectory. It contains start up scripts for various
-flavors of GNU/Linux distributions.
+The package includes startup scripts for several major GNU/Linux
+distributions. Please refer to rc/README for instructions on
+adding ping903 to the operating system startup and shutdown sequences.
* Nagios external check
The ping903q tool can be used as a Nagios external check program. The
following snippet illustrates the simple Nagios configuration that
makes use of it:
@@ -206,18 +206,12 @@ makes use of it:
service_description Server status
check_command check_ping903!200.0,20%!600.0,60%
check_interval 5
retry_interval 1
}
-* Startup scripts
-
-The package includes startup scripts for several major GNU/Linux
-distributions. Please refer to rc/README for instructions on
-adding ping903 to the operating system startup and shutdown sequences.
-
* Installation from a git clone
If you are building from a clone of the Git repository, you will need
GNU autotools to bootstrap the package first. Run
./bootstrap
diff --git a/doc/ping903.8 b/doc/ping903.8
index 35cbb4a..f8967af 100644
--- a/doc/ping903.8
+++ b/doc/ping903.8
@@ -10,13 +10,13 @@
.\" 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 "March 11, 2020" "PING903" "System Administration"
+.TH PING903 8 "September 19, 2020" "PING903" "System Administration"
.SH NAME
ping903 \- high-performance ICMP monitoring daemon
.SH SYNOPSIS
\fBping903\fR\
[\fB\-fhsVv\fR]\
[\fB\-c \fIFILE\fR]
@@ -49,18 +49,19 @@ The program logs its activities using syslog channel \fBdaemon\fR.
The set of monitored IP addresses consists of two parts. The
.I immutable
IP list is supplied in the configuration file and cannot be altered at
run-time. The
.I 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
+changed when the server runs. The content of the mutable IP list is
preserved during server restarts.
.PP
-Probes for each IP from the list are initiated periodically, each
+Each
.B probe\-interval
-seconds. Each probe consists of
+seconds, the daemon wakes up and probes each IP from the list. 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
@@ -73,16 +74,16 @@ 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
An \fBHTTP\fR 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
-\fBlibwrap\fR, the access to the HTTP interface can be controlled
-using files
+statistics and serving other requests. By default it listens for
+queries on localhost, port 8080. If compiled with the support for
+\fBlibwrap\fR, the access to the HTTP interface is controlled using
+the files
.B /etc/hosts.allow
and
.BR /etc/hosts.deny .
See
.BR hosts_access (5),
for details.
@@ -143,13 +144,13 @@ Turn on additional logging. This option can be given several times to
request more verbose output. If given single \fB\-v\fR option, the
program prints at the end of each probe the total number of echo
requests sent and replies received. Two options (\fB\-vv\fR), 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
-\fB\-v\fR options can produce huge amount of logs.
+\fB\-v\fR options can produce a huge amount of output.
.SH BUGS
Only IPv4 is currently supported.
.SH SEE ALSO
.BR ping903.conf (5),
.BR ping903q (1).
.SH COPYRIGHT
diff --git a/doc/ping903.conf.5 b/doc/ping903.conf.5
index cf3432e..a5e9cc4 100644
--- a/doc/ping903.conf.5
+++ b/doc/ping903.conf.5
@@ -10,13 +10,13 @@
.\" 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.CONF 5 "March 10, 2020" "PING903.CONF" "File Formats Manual"
+.TH PING903.CONF 5 "September 19, 2020" "PING903.CONF" "File Formats Manual"
.SH NAME
ping903.conf \- configuration file for high-performance ICMP monitoring daemon
.SH DESCRIPTION
The file
.B /etc/ping903.conf
is read by
@@ -64,13 +64,13 @@ through
.BR local7.
.SS Monitoring setup
.TP
\fBip\-list \fIFILE\fR
Name of the file supplying a list of IP addresses (or hostnames) to
monitor. Each IP must be listed on a separate line. Empty lines,
-leading and trailing whitespace is ignored. Comments are introduced
+leading and trailing whitespace are ignored. Comments are introduced
by a hash sign as the first non-whitespace character on the line.
.TP
\fBip\-list <<\fIWORD\fR
A \fIhere-document\fR version of the above statement. \fIWORD\fR is
an arbitrary word. The material following this statement is scanned
up to the line consisting only of \fIWORD\fR (surrounding whitespace
@@ -79,13 +79,13 @@ address or host name to be incorporated into IP list.
Empty lines and comments are allowed within \fIhere-document\fR.
.PP
Multiple \fBip\-list\fR statements of any form accumulate.
.TP
\fBprobe\-interval \fIN\fR
-Sets interval between subsequent probes, in seconds. Default is 60
+Sets interval (in seconds) between subsequent probes. Default is 60
(one minute).
.TP
\fBping\-count \fIN\fR
Configures the number of ICMP echo requests to be sent to each host
within a single probe. Default is 10.
.TP
@@ -109,28 +109,28 @@ Listen for incoming HTTP requests on the given IP address and port.
is the port number of
symbolic service name from
.BR /etc/services .
Either \fIIPADDR\fR or \fIPORT\fR (but not both) can be omitted. Missing
\fIIPADDR\fR is equivalent to 127.0.0.1 (note, that in this case the
colon before \fIPORT\fR must be present). Missing \fIPORT\fR means
-use the default port number (8080).
+the default port number (8080).
To summarize, possible arguments are:
\fIIPADDR\fB:\fIPORT\fR, \fIIPADDR\fR, or \fB:\fIPORT\fR.
Default is \fB0.0.0.0:8080\fR.
.TP
\fBhttp\-backlog\-size \fIN\fR
Configures the size of the
-.BR listen(2)
+.BR listen (2)
backlog queue. Default is the platform-dependent value
.BR SOMAXCONN ,
(128 on most GNU/Linux systems).
.TP
\fBaccess\-log \fIBOOL\fR
-Enable apache-style HTTPD access logging. Valid \fIBOOL\fR values are:
+Enables the apache-style HTTP access logging. Valid \fIBOOL\fR values are:
.BR 1 ,
.BR t ,
.BR true ,
.BR yes ,
or
.BR on ,
@@ -153,13 +153,13 @@ Adds a CIDR to the list of trusted IP networks. This list is used
when determining source IP address of a HTTP connection for the
purpose of logging. By default, each log message contains the client
IP of the connection. If the
.B X\-Forwarded\-For
header is present, its value overrides that IP. If the
header contains a comma-delimited list of IP addresses, this list is
-processed in right-to-left order, until either a not trusted IP or the
+processed from right to left, until either a not trusted IP or the
first IP in the list is encountered, whichever occurs first.
\fICIDR\fR is either an IPv4 address, or an address followed by slash
and the network mask in dotted quad, or the length of the network mask
in decimal.
.TP
@@ -167,22 +167,22 @@ in decimal.
A \fIhere-document\fR version of the above statement. See the
description of \fBip\-list\fR above for the description of
\fIhere-document\fR syntax. The collected material must contain a
single CIDR per line.
.SS HTTP Authorization configuration
It is suggested that HTTP entry points be protected by the HTTP
-authorization. This is especially critical for \fB/config\fR and
-below, which allows the requester to modify \fBping903\fR
+authorization. This is especially critical for the \fB/config\fR
+URL and URLs below it, which allow the requester to modify \fBping903\fR
configuration. This version of \fBping903\fR supports HTTP basic
authorization.
.TP
\fBauth basic\fR \fIMETHOD\fR \fIURL\fR \fIPWFILE\fR \fIREALM\fR
This statement enables basic authentication for \fIURL\fR when
accessed using the given HTTP \fIMETHOD\fR.
-\fIMETHOD\fR is either one of HTTP methods (\fBGET\fR, \fBPOST\fR,
+\fIMETHOD\fR is either the name of an HTTP method (\fBGET\fR, \fBPOST\fR,
etc.) or a wildcard \fB*\fR matching any method.
\fIURL\fR is the \fBping903\fR URL. It is treated as a prefix, i.e.
the statement takes effect for anything below that URL as well. The
\fIURL\fR can also contain
.BR glob (7)
@@ -200,13 +200,13 @@ realm is used by the client to determine what user name and password
to send for a given authenticated area. If \fIREALM\fR contains
whitespace, it must be enclosed in double-quotes. Within a
double-quoted string any occurrence of a double-quote or backslash
character must be escaped by prefixing it with a backslash.
These parameters are mandatory only for the very first occurrence of the
-\fBauth\fR statements. The statements that follow it may omit the
+\fBauth\fR statement. The statements that follow it may omit the
\fIIPFILE\fR and/or \fIREALM\fR, if they are the same as in the
preceding statement. For example, the following statements protect
modifications to the \fBping903\fR configuration with basic
authorization:
.sp
.nf
@@ -218,14 +218,14 @@ auth basic PUT /config
Disables authorization for this combination of \fIMETHOD\fR and
\fIURL\fR. See \fBauth basic\fR for the description of \fIMETHOD\fR
and \fIURL\fR.
Use this statement to exempt an URL from authorization which is
otherwise required for its parent URL. For example, the two
-statements below require basic authorization for "/config", excepting
-"/config/ip-list":
+statements below require basic authorization for "/config", but not
+for "/config/ip-list":
.sp
.nf
auth none GET /config/ip-list
auth basic GET /config /etc/ping903/htpasswd "Config Access"
.fi
.PP
diff --git a/doc/ping903.cred.5 b/doc/ping903.cred.5
index ede1b2b..2a4203b 100644
--- a/doc/ping903.cred.5
+++ b/doc/ping903.cred.5
@@ -10,13 +10,13 @@
.\" 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.CRED 5 "March 22, 2020" "PING903.CRED" "File Formats Manual"
+.TH PING903.CRED 5 "September 19, 2020" "PING903.CRED" "File Formats Manual"
.SH NAME
ping903.cred \- Credentials storage for ping903
.SH DESCRIPTION
The file
.B .ping903.conf
located in the user home directory contains credentials for accessing
@@ -41,14 +41,14 @@ Each definition consists of the following four fields:
.PP
Their meaning is as follows:
.TP
.I SERVER
Specifies the server to which this entry applies. It consists of the
server IP address or DNS name, optionally followed by a colon and port
-number. A wildcard character \fB*\fR can be used in place of the
-either part, in which case this part will match any IP (or port).
+number. Either part can be replaced with a wildcard character
+\fB*\fR, in which case it will match any IP (or port).
If a DNS name is used, it will be resolved.
This field corresponds to the \fBlisten\fR statement in
.BR ping903.conf .
.TP
@@ -65,13 +65,13 @@ User password.
.PP
When the server requests authorization, the client program
(\fBping903q\fR) will scan the
.B ~/.ping903.cred
file for an entry with the \fISERVER\fR matching the IP and port of
the server (as configured by the \fBlisten\fR statement in the
-\fB/etc/ping903.conf\fR file) and the \fIREALM\fR filed matching the
+\fB/etc/ping903.conf\fR file) and the \fIREALM\fR field matching the
authorization realm presented by the server. If such an entry is
found, the client will re-submit the request using the
\fIUSER\fR and \fIPASSWORD\fR for authorization.
.SH SEE ALSO
.BR ping903 (8),
.BR ping903.conf (5),
diff --git a/doc/ping903q.1 b/doc/ping903q.1
index cf6172e..9352ca9 100644
--- a/doc/ping903q.1
+++ b/doc/ping903q.1
@@ -10,13 +10,13 @@
.\" 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 PING903Q 1 "March 10, 2020" "PING903Q" "User Commands"
+.TH PING903Q 1 "September 19, 2020" "PING903Q" "User Commands"
.SH NAME
ping903q \- ping903 query tool
.SH SYNOPSIS
\fBping903q\fR\
[\fB\-ahVv\fR]\
[\fB\-f \fIFILE\fR]\
@@ -48,14 +48,14 @@ information can be requested with the
command line option. When given this option, the program will output
detailed information about round trip times and lost packets.
.PP
By default, the program attempts to connect to the default REST API
port of (localhost:8080). If the file
.B /etc/ping903.conf
-exists, it will obtain the socket address from the \fBlisten\fR
-statement. See
+exists and contains the \fBlisten\fR statement, the value of this
+statement will be used instead. See
.BR ping903.conf (5),
for detailed description of the configuration file.
.SS Nagios check mode
When the \fB\-H\fR, \fB\-c\fR, and \fB\-w\fR options are used, the
program enters \fINagios check mode\fR. In this mode its output
complies with the requirements for external \fBNagios\fR check
@@ -73,26 +73,26 @@ for a detailed discussion of the file). The file is scanned for
an entry that matches the server name and port (as given in the
\fBlisten\fR statement of the \fBping903.conf\fR file) and the
authorization \fIrealm\fR name presented by the server. If such an
entry is found, the user name and password listed in it will be used
to send the authorized request.
.PP
-Using the \fB\-R\fR option, you can force using a specific realm for
+The \fB\-R\fR option allows you to use a specific realm for
authorization. In this case, the \fB.ping903.cred\fR file is scanned
at startup and the credentials found in it are used to authorize the
request, without sending unauthorized request first and consulting the
reply.
.SH EXIT CODE
When called with one argument, the program exits with code 0 (success)
if the IP is alive, 2 if it is not, and 3 if the host status is unknown.
.PP
When called without arguments, the program exits with code 0 if all
monitored IP addresses are alive, 2 if none of them is reachable and 1
if some of them are.
.PP
-Exit codes in nagios check mode:
+In Nagios check mode, exit codes are:
.TP
.B 0
Success
.TP
.B 1
Warning condition.
@@ -164,13 +164,13 @@ also that the use of the percent sign is mandatory.
Sets the warning threshold value. See above for the discussion of the
arguments.
.PP
Other options valid in this mode:
.TP
\fB\-N\fR
-By default hosts in initial state (i.e. for which no data has been
+By default, hosts in initial state (i.e. for which no data has been
collected) are treated as "OK" (exit status 0). This option changes
the default to treat them as "UNKNOWN" (exit status 3).
.TP
\fB\-p \fIPREFIX\fR
Supplies the prefix to be displayed before Nagios status string. The
default is "PING". The \fIPREFIX\fR string can contain the
@@ -180,13 +180,14 @@ host being monitored. E.g. \fB\-p 'PING %h'\fR.
.TP
.B \-m
Switch to the host match mode.
.SH SEE ALSO
.BR ping903 (8),
.BR ping903.cred (5),
-.BR Nagios <https://www.nagios.org/>.
+.B Nagios
+<https://www.nagios.org/>.
.SH COPYRIGHT
Copyright \(co 2020 Sergey Poznyakoff
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
diff --git a/examples/dbload b/examples/dbload
index 4502d55..f59dee9 100755
--- a/examples/dbload
+++ b/examples/dbload
@@ -56,13 +56,13 @@ hosts of L<ping903>.
Most parameters are configurable. You need to supply at least the database
connection information and the query to use. For the latter, use the
B<--table> and B<--column> options together. For really complex queries,
use the B<--query> option instead. See below for details.
On success, prints on standard output the number of IP addresses loaded and
-exits with status 0. On error, displays on stabdard error the detailed
+exits with status 0. On error, displays on standard error the detailed
diagnostic information as obtained from the server and exits with status 1.
=head1 OPTIONS
=head2 General options
diff --git a/rc/README b/rc/README
index 40e716e..e3abc05 100644
--- a/rc/README
+++ b/rc/README
@@ -1,36 +1,39 @@
* Overview
+
This directory contains distribution-specific startup scripts for
Ping903. All scripts assume the daemon binary is installed at
/usr/sbin/ping903. If it's not the case, change the value of the
COMMAND variable, located at the start of the script.
* debian.rc
+
The start script for Debian-based systems without systemd. Use it on
Debian 7, Ubuntu up to 16.04, etc.
1. Copy the script and make it executable:
cp debian.rc /etc/init.d/ping903
chmod +x /etc/init.d/ping903
2. Register it in the startup and shutdown sequences:
update-rc.d ping903 defaults
-Optionally, you may create the file /etc/default/903, which can
+Optionally, you may create the file /etc/default/ping903, which can
define two shell variables:
START
Whether or not to start the service. Set it to "no", to
disable the service. Set it to "yes" (or simply remove it)
to enable the service.
DAEMON_OPTS
Additional options to be passed to the server.
* ping903.service
+
Service definition for systems with systemd. Usage:
1. Copy
cp ping903.service /etc/systemd/system/
2. Enable it
@@ -40,12 +43,13 @@ Service definition for systems with systemd. Usage:
systemctl daemon-reload
4. Start the service
systemctl start ping903
* slackware.rc
+
Slackware rc script. In fact, it is the most general of all and it
will work an all systems with no (or at a pinch, little) changes.
Usage:
1. Copy it to where startup scripts live and make it executable.
cp slackware.rc /etc/rc.d/rc.pound903

Return to:

Send suggestions and report system problems to the System administrator.