1 files changed, 165 insertions, 0 deletions
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: