.\" This file is part of ping903 -*- nroff -*-
.\" Copyright (C) 2020-2023 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 "September 19, 2020" "PING903.CRED" "File Formats Manual"
.SH NAME
ping903.cred \- 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.  Either part can be replaced with a wildcard character
\fB*\fR, in which case it 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 field 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: