aboutsummaryrefslogtreecommitdiff
path: root/doc/ping903.conf.5
blob: 7c29de9fec1bc61ecb076b56cd951ec5a73c5ed3 (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
.\" 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.

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

Return to:

Send suggestions and report system problems to the System administrator.