diff options
authorSergey Poznyakoff <gray@gnu.org.ua>2020-02-27 14:09:07 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2020-02-27 17:40:57 +0200
commita7d03cd5f6ab8884ee2f2ef89c3e514c811c2c9f (patch)
parent9b546466f4e0f34a63e5f49c752dffea3ef9a47a (diff)
Document basic authorization
4 files changed, 177 insertions, 3 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 52b2d52..ea01b66 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1 +1 @@
-dist_man_MANS=ping903q.1 ping903.8 ping903.conf.5
+dist_man_MANS=ping903q.1 ping903.8 ping903.conf.5 ping903.cred.5
diff --git a/doc/ping903.conf.5 b/doc/ping903.conf.5
index 7c29de9..c6835f3 100644
--- a/doc/ping903.conf.5
+++ b/doc/ping903.conf.5
@@ -150,9 +150,61 @@ first IP in the list is encountered, whichever occurs first.
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
+\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)
+\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)
+\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
+auth basic POST /config /etc/ping903/htpasswd Modification
+auth basic PUT /config
+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.
.BR ping903 (8),
-.BR ping903q (1).
+.BR ping903q (1),
+.BR ping903.cred (5).
Copyright \(co 2020 Sergey Poznyakoff
diff --git a/doc/ping903.cred.5 b/doc/ping903.cred.5
new file mode 100644
index 0000000..b2e187a
--- /dev/null
+++ b/doc/ping903.cred.5
@@ -0,0 +1,94 @@
+.\" 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
+.\" 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.CRED 5 "February 27, 2020" "PING903.CONF" "File Formats Manual"
+ping903.conf \- Credentials storage for ping903
+The file
+.B .ping903.conf
+located in the user home directory contains credentials for accessing
+various URLs handled by the
+.B ping903
+The file is organized as a sequence of definitions, which consist of
+four fields separated by any amount of whitespace. Initial and
+trailing whitespace is ignored. Any field containing whitespace
+characters on its own must be enclosed in double quotes.
+Double-quotes and backslashes appearing within quoted strings must be
+escaped by prefixing them with a backslash.
+Empty lines and lines beginning with a hash sign are ignored.
+Each definition consists of the following four fields:
+Their meaning is as follows:
+Specifies the server to which this entry applies. It consists of the
+server IP address or DNS name, optionally followed by a colon and port
+number. A wildcard character \fB*\fR can be used in place of the
+either part, in which case this part will match any IP (or port).
+If a DNS name is used, it will be resolved.
+This field corresponds to the \fBlisten\fR statement in
+.BR ping903.conf .
+Name of the authentication realm. This corresponds to the fifth
+parameter of the \fBauth\fR statement in
+.BR ping903.conf .
+Authorization user name.
+User password.
+When the server requests authorization, the client program
+(\fBping903q\fR) will scan the
+.B ~/.ping903.cred
+file for an entry with the \fISERVER\fR matching the IP and port of
+the server (as configured by the \fBlisten\fR statement in the
+\fB/etc/ping903.conf\fR file) and the \fIREALM\fR filed matching the
+authorization realm presented by the server. If such an entry is
+found, the client will re-submit the request using the
+\fIUSER\fR and \fIPASSWORD\fR for authorization.
+.BR ping903 (8),
+.BR ping903.conf (5),
+.BR ping903q (1).
+Copyright \(co 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.
+.\" 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:
diff --git a/doc/ping903q.1 b/doc/ping903q.1
index ffe1830..5da343d 100644
--- a/doc/ping903q.1
+++ b/doc/ping903q.1
@@ -13,24 +13,27 @@
.\" You should have received a copy of the GNU General Public License
.\" along with Ping903. If not, see <http://www.gnu.org/licenses/>.
-.TH PING903Q 1 "February 24, 2020" "PING903Q" "User Commands"
+.TH PING903Q 1 "February 27, 2020" "PING903Q" "User Commands"
ping903q \- ping903 query tool
[\fB\-f \fIFILE\fR]\
+ [\fB\-R \fIREALM\fR]\
[\fB\-f \fIFILE\fR]\
[\fB\-p \fIPREFIX\fR]\
+ [\fB\-R \fIREALM\fR]\
\fB\-H \fIHOST\fR\
\fB\-c \fIRTA\fB,\fIPCT\fB%\fR\
\fB\-w \fIRTA\fB,\fIPCT\fB%\fR
[\fB\-f \fIFILE\fR]\
+ [\fB\-R \fIREALM\fR]\
Queries monitoring statistics from the \fBping903\fR daemon. When
@@ -61,6 +64,23 @@ programs.
When invoked with the \fB\-m\fR option, \fBping903q\fR checks if
\fIHOST\fR is monitored by the server. If so, it prints the matching
host names and exits with code 0.
+.SS Basic authorization
+If the server requires authorization, \fBping903q\fR will look into
+the file \fB.ping903.cred\fR in the user home directory in order to
+find authentication credentials (see
+.BR ping903.cred (5),
+for a detailed discussion of the file). The file is scanned for
+an entry that matches the server name and port (as given in the
+\fBlisten\fR statement of the \fBping903.conf\fR file) and the
+authorization \fIrealm\fR name presented by the server. If such an
+entry is found, the user name and password listed in it will be used
+to send the authorized request.
+Using the \fB\-R\fR option, you can force using a specific realm for
+authorization. In this case, the \fB.ping903.cred\fR file is scanned
+at startup and the credentials found in it are used to authorize the
+request, without sending unauthorized request first and consulting the
When called with one argument, the program exits with code 0 (success)
if the IP is alive and 2 otherwise.
@@ -93,6 +113,13 @@ Read configuration from \fIFILE\fR instead of from the default
.B \-h
Print a short usage summary.
+\fB\-R \fIREALM\fR
+Specifies authentication realm to use to authenticate the request.
+This option causes the program to look up the credentials in the
+.B .ping903.cred
+file at startup and to use them when forming the request as described
+in \fBBasic authorization\fR above.
.B \-r
Resolve host argument to IP address and use the IP address to query
the server. Using this option you can supply a symbolic host name
@@ -139,6 +166,7 @@ host being monitored. E.g. \fB\-p 'PING %h'\fR.
Switch to the host match mode.
.BR ping903 (8),
+.BR ping903.cred (5),
.BR Nagios <https://www.nagios.org/>.
Copyright \(co 2020 Sergey Poznyakoff

Return to:

Send suggestions and report system problems to the System administrator.