aboutsummaryrefslogtreecommitdiff
path: root/doc/ping903.conf.5
blob: befe0828b6a4cf48836d68367b53bd221fb9f9e8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
.\" 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 28, 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.
.PP
Maximum length of a statement line is limited to 1022 characters.
Lines longer than that cause syntax error to be reported and are
ignored otherwise.
.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.
.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
allowed).  Each line in the collected material must contain a single IP
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
(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.
.TP
\fBtrusted\-ip <<\fIWORD\fR
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
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:

Return to:

Send suggestions and report system problems to the System administrator.