PING903.CONF

NAME
DESCRIPTION
STATEMENTS
SEE ALSO
COPYRIGHT

NAME

ping903.conf - configuration file for high-performance ICMP monitoring daemon

DESCRIPTION

The file /etc/ping903.conf is read by ping903(8) at startup. It consists of a series of statements, 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.

The pound sign (#) appearing as the first non-whitespace character on a line introduces a comment. Such lines are ignored. Empty lines are ignored as well.

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.

STATEMENTS

Server configuration
pidfile
FILE

Instructs ping903 to write its PID to the specified file. If running with supervisor process (the default), the supervisor’s PID will be written.

By default no pidfile is created.

syslog-facility NAME

Configures the syslog facility to use. Valid arguments are auth, authpriv, cron, daemon (default), ftp, kern, lpr, mail, news, security, syslog, user, uucp, and local0 through local7.

Monitoring setup
ip-list
FILE

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.

ip-list <<WORD

A here-document version of the above statement. WORD is an arbitrary word. The material following this statement is scanned up to the line consisting only of WORD (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 here-document.

Multiple ip-list statements of any form accumulate.
probe-interval
N

Sets interval between subsequent probes, in seconds. Default is 60 (one minute).

ping-count N

Configures the number of ICMP echo requests to be sent to each host within a single probe. Default is 10.

ping-interval N

Configures the time between two subsequent echo requests in a probe.

tolerance N

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.

data-length N

Number of additional bytes to send in each ICMP echo requests (apart from the timestamp). Default is 56.

HTTP responder configuration
listen
IPADDR:PORT

Listen for incoming HTTP requests on the given IP address and port. IPADDR is a IPv4 address (or hostname) to listen on. PORT is the port number of symbolic service name from /etc/services. Either IPADDR or PORT (but not both) can be omitted. Missing IPADDR is equivalent to 127.0.0.1 (note, that in this case the colon before PORT must be present). Missing PORT means use the default port number (8080).

To summarize, possible arguments are: IPADDR:PORT, IPADDR, or :PORT.

Default is 0.0.0.0:8080.

http-backlog-size N

Configures the size of the listen(2) backlog queue. Default is the platform-dependent value SOMAXCONN, (128 on most GNU/Linux systems).

access-log BOOL

Enable apache-style HTTPD access logging. Valid BOOL values are: 1, t, true, yes, or on, to enable logging, and 0, f, nil, false, no, or off, to disable it.

access-log-verbose BOOL

Configures whether to include dumps of JSON replies to access logs. See above for the possible values of BOOL.

trusted-ip CIDR

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

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

trusted-ip <<WORD

A here-document version of the above statement. See the description of ip-list above for the description of here-document syntax. The collected material must contain a single CIDR per line.

HTTP Authorization configuration
It is suggested that HTTP entry points be protected by the HTTP authorization. This is especially critical for /config and below, which allows the requester to modify ping903 configuration. This version of ping903 supports HTTP basic authorization.
auth basic
METHOD URL PWFILE REALM

This statement enables basic authentication for URL when accessed using the given HTTP METHOD.

METHOD is either one of HTTP methods (GET, POST, etc.) or a wildcard * matching any method.

URL is the ping903 URL. It is treated as a prefix, i.e. the statement takes effect for anything below that URL as well. The URL can also contain glob(7) wildcards.

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

REALM 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 REALM contains whitespace, it must be enclosed in double-quotes. Within a double-quoted string any occurrence of a double-quote or backslash character must be escaped by prefixing it with a backslash.

These parameters are mandatory only for the very first occurrence of the auth statements. The statements that follow it may omit the IPFILE and/or REALM, if they are the same as in the preceding statement. For example, the following statements protect modifications to the ping903 configuration with basic authorization:

auth basic POST /config /etc/ping903/htpasswd Modification
auth basic PUT /config

auth none METHOD URL

Disables authorization for this combination of METHOD and URL. See auth basic for the description of METHOD and URL.

Use this statement to exempt an URL from authorization which is otherwise required for its parent URL. For example, the two statements below require basic authorization for "/config", excepting "/config/ip-list":

auth none GET /config/ip-list
auth basic GET /config /etc/ping903/htpasswd "Config Access"

Notice, that an incoming HTTP request is matched against each auth statement in turn, in the order they appear in the configuration file, and it is the first matching statement that takes effect. Therefore, be sure to place more specific METHOD/URL combinations before more general ones.

SEE ALSO

ping903(8), ping903q(1), ping903.cred(5).

COPYRIGHT

Copyright © 2020 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


Manpage server at man.gnu.org.ua.

Powered by mansrv 1.1