diff options
author | Sergey Poznyakoff <gray@gnu.org> | 2020-02-12 23:08:49 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org> | 2020-02-12 23:08:49 +0200 |
commit | 1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a (patch) | |
tree | b61ae0ad99c3654684391c62bb1a1d29d1908273 /doc | |
parent | 28c6a911174d2ce2672e44b55e3e09c05adfad3f (diff) | |
download | ping903-1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a.tar.gz ping903-1d1687c574bcbf5a7f54cb45763ad36fa70b3c2a.tar.bz2 |
Add manpages
Diffstat (limited to 'doc')
-rw-r--r-- | doc/ping903.8 | 139 | ||||
-rw-r--r-- | doc/ping903.conf.5 | 165 | ||||
-rw-r--r-- | doc/ping903q.1 | 106 |
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: |