Document basic authorization

1 files changed, 53 insertions, 1 deletions

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