From a7d03cd5f6ab8884ee2f2ef89c3e514c811c2c9f Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Thu, 27 Feb 2020 14:09:07 +0200 Subject: Document basic authorization --- doc/Makefile.am | 2 +- doc/ping903.conf.5 | 54 ++++++++++++++++++++++++++++++- doc/ping903.cred.5 | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ping903q.1 | 30 ++++++++++++++++- 4 files changed, 177 insertions(+), 3 deletions(-) create mode 100644 doc/ping903.cred.5 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 +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 ping903q (1), +.BR ping903.cred (5). .SH COPYRIGHT Copyright \(co 2020 Sergey Poznyakoff .br 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 +.\" 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 . +.TH PING903.CRED 5 "February 27, 2020" "PING903.CONF" "File Formats Manual" +.SH NAME +ping903.conf \- Credentials storage for ping903 +.SH DESCRIPTION +The file +.B .ping903.conf +located in the user home directory contains credentials for accessing +various URLs handled by the +.B ping903 +server. +.PP +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. +.PP +Empty lines and lines beginning with a hash sign are ignored. +.PP +Each definition consists of the following four fields: +.sp +.nf +.I SERVER REALM USER PASSWORD +.fi +.PP +Their meaning is as follows: +.TP +.I SERVER +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 . +.TP +.I REALM +Name of the authentication realm. This corresponds to the fifth +parameter of the \fBauth\fR statement in +.BR ping903.conf . +.TP +.I USER +Authorization user name. +.TP +.I PASSWORD +User password. +.PP +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. +.SH SEE ALSO +.BR ping903 (8), +.BR ping903.conf (5), +.BR ping903q (1). +.SH COPYRIGHT +Copyright \(co 2020 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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: 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 . -.TH PING903Q 1 "February 24, 2020" "PING903Q" "User Commands" +.TH PING903Q 1 "February 27, 2020" "PING903Q" "User Commands" .SH NAME ping903q \- ping903 query tool .SH SYNOPSIS \fBping903q\fR\ [\fB\-hVv\fR]\ [\fB\-f \fIFILE\fR]\ + [\fB\-R \fIREALM\fR]\ [\fIIP\fR] .PP \fBping903q\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 .PP \fBping903q\fR\ [\fB\-f \fIFILE\fR]\ + [\fB\-R \fIREALM\fR]\ \fB\-m\fR .SH DESCRIPTION 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. +.PP +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 +reply. .SH EXIT CODE 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. .TP +\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. +.TP .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. .SH SEE ALSO .BR ping903 (8), +.BR ping903.cred (5), .BR Nagios . .SH COPYRIGHT Copyright \(co 2020 Sergey Poznyakoff -- cgit v1.2.1