1 files changed, 94 insertions, 0 deletions
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 <http://www.gnu.org/licenses/>.
+.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 <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: