path: root/doc/ping903.conf.5

.\" 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 27, 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 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).  

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)
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:
.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.

.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
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,
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)
wildcards.

\fIPWFILE\fR is the name of a textual file containing the list of
users and passwords for user authentication.  This file is compatible
with Apache \fBmod_authn_file\fR module and can be generated using
the Apache
.BR htpasswd (1)
utility.

\fIREALM\fR sets the realm to be used in the authentication.  The
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 double-quote or backslash must
be escaped by prefixing it with a backslash character.

These parameters are mandatory only for the very first occurrence of the
\fBauth\fR statements.  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
auth basic POST /config /etc/ping903/htpasswd Modification
auth basic PUT  /config
.fi
.sp
Notice, that an incoming HTTP request is matched against each
\fBauth\fR statement in turn, in the order they appear in the
configuration file, and it is the first matching statement that
takes effect.  Therefore, place more specific METHOD/URL combinations
before more general ones.
.SH SEE ALSO
.BR ping903 (8),
.BR ping903q (1),
.BR ping903.cred (5).
.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: