aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org>2020-02-12 23:08:49 +0200
committerSergey Poznyakoff <gray@gnu.org>2020-02-12 23:08:49 +0200
commit1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a (patch)
treeb61ae0ad99c3654684391c62bb1a1d29d1908273 /doc
parent28c6a911174d2ce2672e44b55e3e09c05adfad3f (diff)
downloadping903-1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a.tar.gz
ping903-1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a.tar.bz2
Add manpages
Diffstat (limited to 'doc')
-rw-r--r--doc/ping903.8139
-rw-r--r--doc/ping903.conf.5165
-rw-r--r--doc/ping903q.1106
3 files changed, 410 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:
diff --git a/doc/ping903.conf.5 b/doc/ping903.conf.5
new file mode 100644
index 0000000..25321d9
--- /dev/null
+++ b/doc/ping903.conf.5
@@ -0,0 +1,165 @@
+.\" 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.CONF 5 "February 12, 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
+.BR ping903 (8)
+at startup. It consists of a series of \fIstatements\fR, each
+statement occupying a separate line. A statement consists of a
+keyword and argument, separated by one or more whitespace characters.
+Leading and trailing whitespace characters are ignored.
+.PP
+The pound sign (\fB#\fR) appearing as the first non-whitespace
+character on a line introduces a comment. Such lines are ignored.
+Empty lines are ignored as well.
+.SH STATEMENTS
+.SS Server configuration
+.TP
+\fBpidfile \fIFILE\fR
+Instructs \fBping903\fR to write its PID the specified file. If
+running with supervisor process (the default), the supervisor's PID
+will be written.
+
+By default no pidfile is created.
+.TP
+\fBsyslog\-facility \fINAME\fR
+Configures the syslog facility to use. Valid arguments are
+.BR auth ,
+.BR authpriv ,
+.BR cron ,
+.BR daemon "(default), "
+.BR ftp ,
+.BR kern ,
+.BR lpr ,
+.BR mail ,
+.BR news ,
+.BR security ,
+.BR syslog ,
+.BR user ,
+.BR uucp ,
+and
+.B local0
+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
+by a hash sign as the first non-whitespace character on the line.
+
+Multiple \fBip\-list\fR statements accumulate. At least
+one must be present.
+.TP
+\fBprobe\-interval \fIN\fR
+Sets interval between subsequent probes, in seconds. 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
+\fBping\-interval \fIN\fR
+Configures the time between two subsequent echo requests in a probe.
+.TP
+\fBtolerance \fIN\fR
+Failure tolerance. This is the maximum number of echo requests in a
+probe that may remain unanswered without declaring the host as dead.
+Default is 3, i.e. a host is declared dead if more than 3 pings out of
+each 10 are lost.
+.TP
+\fBdata\-length \fIN\fR
+Number of additional bytes to send in each ICMP echo requests (apart from
+the timestamp). Default is 40.
+.SS HTTP responder configuration
+.TP
+\fBlisten \fIIPADDR\fB:\fIPORT\fR
+Listen for incoming HTTP requests on the given IP address and port.
+\fIIPADDR\fR is a IPv4 address (or hostname) to listen on. \fIPORT\fR
+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 0.0.0.0 and means "listen on all
+available interfaces" (note, that in this case the colon before
+\fIPORT\fR must be present). Missing \fIPORT\fR means use 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
+\fBaccess\-log \fIBOOL\fR
+Enable apache-style HTTPD access logging. Valid \fIBOOL\fR values are:
+.BR 1 ,
+.BR t ,
+.BR true ,
+.BR yes ,
+or
+.BR on ,
+to enable logging, and
+.BR 0 ,
+.BR f ,
+.BR nil ,
+.BR false ,
+.BR no ,
+or
+.BR off ,
+to disable it.
+.TP
+\fBaccess\-log\-verbose \fIBOOL\fR
+Configures whether to include dumps of JSON replies to access logs.
+See above for the possible values of \fIBOOL\fR.
+.TP
+\fBtrusted\-ip \fICIDR\fR
+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
+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.
+
+.SH SEE ALSO
+.BR ping903 (8),
+.BR ping903q (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:
diff --git a/doc/ping903q.1 b/doc/ping903q.1
new file mode 100644
index 0000000..3a2a91a
--- /dev/null
+++ b/doc/ping903q.1
@@ -0,0 +1,106 @@
+.\" 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 PING903Q 8 "February 12, 2020" "PING903Q" "User Commands"
+.SH NAME
+ping903q \- ping903 query tool
+.SH SYNOPSIS
+\fBping903q\fR\
+ [\fB\-hVv\fR]\
+ [\fB\-c \fIFILE\fR]\
+ [\fIIP\fR]
+.SH DESCRIPTION
+Queries monitoring statistics from the \fBping903\fR daemon. When
+used with a single argument (\fIIP\fR), displays information about
+this particular IP address. Used without arguments, displays
+statistics about all IP addresses monitored by the running daemon.
+.PP
+By default a one-line summary is displayed, which informs about the IP
+and its current status ("alive" vs. "not alive"). Additional
+information can be requested with the
+.B \-v
+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 look obtain the socket address from the \fBlisten\fR
+statement. See
+.BR ping903.conf (5),
+for detailed description of the configuration file.
+.SH EXIT CODE
+When called with one argument, the program exits with code 0 (success)
+if the IP is alive and 1 otherwise.
+.PP
+When called without arguments, the program exits with code 0 if all
+monitored IP addresses are alive, 1 if none of them is reachable and 2
+if some of them are.
+.PP
+Other possible exit codes are:
+.TP
+.B 64
+Command line usage error.
+.TP
+.B 65
+Data format error. The returned JSON is malformed.
+.TP
+.B 69
+Service unavailable. This means some error occurred, which will be
+diagnosed on the standard error.
+.TP
+.B 70
+Internal software error.
+.TP
+.B 71
+System error (e.g. error reading from socket or the like).
+.TP
+.B 76
+Protocol error when talking to the daemon.
+.TP
+.B 78
+Error in configuration file.
+.SH OPTIONS
+.TP
+\fB\-c \fIFILE\fR
+Read configuration from \fIFILE\fR instead of from the default
+.BR /etc/ping903.conf .
+.TP
+.B \-h
+Print a short usage summary.
+.TP
+.B \-V
+Print program version, copyright information, and exit.
+.TP
+.B \-v
+Turn on verbose output.
+.SH SEE ALSO
+.BR ping903 (8).
+.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.