with-authinfo-kludge.1: Explain that we don't configure the client.

[with-authinfo-kludge] / with-authinfo-kludge.1

.\" -*-nroff-*-
.\"
.\" Manual page for `with-authinfo-kludge'.
.\"
.\" (c) 2016 Mark Wooding
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This program 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 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program 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 this program; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.ie t \{\
.  ds o \(bu
.\}
.el \{\
.  ds o o
.\}
.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.
.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.
.TH with-authinfo-kludge 1 "23 April 2016"
.
.\"--------------------------------------------------------------------------
.SH NAME
with-authinfo-kludge \- run a newsreader with AUTHINFO GENERIC support
.
.SH SYNOPSIS
with-authinfo-kludge
.RB [ \-v ]
.RB [ \-d
.IR dir ]
.RB [ \-f
.IR conf ]
.RB [ \-t
.IR tag ]
.br
\h'5m'\c
[
.BI + server
.RI [ param \fR= value
\&...] \&...]
.RB [ + ]
.br
\h'5m'\c
.I command
.RI [ args
\&...]
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
The
.B with-authinfo-kludge
program is an
.I adverbial modifier
which runs another command
(typically a newsreader)
in an environment in which at can,
transparently to it,
make connections to certain NNTP servers
which usually require
.B AUTHINFO GENERIC
authentication before they'll permit clients to read or post.
This is useful because support for
.B AUTHINFO GENERIC
has never been especially widely supported by newsreaders
and now seems to be being withdrawn from those newsreaders
which used to support it.
.PP
In the simple case, you say something like
.VS
with-authinfo-kludge slrn
.VE
and then
.B slrn
will start up,
connect to your default NNTP server
(as named in the
.B NNTPSERVER
environment variable),
authenticate to it as needed,
and let you read and post news.
In more complicated cases,
.B with-authinfo-kludge
can handle multiple NNTP servers,
set up SSH forwarding for them,
offer different authentication credentials to them,
and hide the fact that they might be running on nonstandard ports.
.PP
The
.B with-authinfo-kludge
program doesn't do all of this itself:
it depends on some other tools existing on the system in which it runs.
(It doesn't need anything special running on the server system.)
The external dependencies are as follows.
.hP \*o
The
.B authinfo-kludge
program, by Richard Kettlewell,
is a simple proxy which relays commands and responses
between the client (on stdin/stdout) and server (over TCP),
and responds transparently to authentication requests from the server.
.hP \*o
The
.B noip
hack, by Mark Wooding,
is an
.B LD_PRELOAD
library which selectively uses Unix-domain sockets
in place of IPv4 or IPv6 sockets.
.
.SS "Command line"
The
.B with-authinfo-kludge
program accepts a small number of options
before its main command-line arguments.
.TP
.B \-h
Write help about the command-line syntax to standard output,
and exit with status zero.
.TP
.BI "\-d " dir
Use
.I dir
as the `runtime directory',
which is used to store sockets and other working files
while
.B with-authinfo-kludge
is running.
By default, it will choose an appropriate place
in a moderately complicated manner described below;
this option lets you override its choice
in order to achieve special effects.
.TP
.BI "\-f " conf
Read configuration from
.IR conf .
The default is somewhat complicated;
see below.
.TP
.BI "\-t " tag
Use
.I tag
to distinguish this usage of
.B with-authinfo-kludge
from others.
The tag is used to select default configuration files
and runtime directories.
By default, the basename of the
.I command
is used.
.TP
.B "\-v"
Print messages explaining what
.B with-authinfo-kludge
is doing to standard error.
By default,
.B with-authinfo-kludge
does its thing silently unless there are problems.
.PP
The
.I command
argument names the command which should be run
with the various proxy arrangements which it is the task of
.B with-authinfo-kludge
to arrange; it will be passed the
.IR args ,
if any.
The command name and arguments are not subject to
interpretation by the shell;
if, for some reason, you wanted to make use of shell features,
you should specify a command of the form
.B /bin/sh
.B \-c
.IR shell-fragment .
.PP
Between the options (if any) and the
.I command
name,
there may be a number of server configurations.
If any are present, they take the place of any configuration file:
an error is reported if a
.B \-f
option was passed.
A server configuration starts with
an argument consisting of a server name prefixed by a
.RB ` + '
character:
.IP
.BI + server
.PP
This may be followed by assignments
.IP
.IB param = value
.PP
which set configuration parameters
for the previously-named server.
Such a server configuration on the command line
is treated exactly the same as a configuration-file section
.IP
.BI [ server ]
.br
.IB param = value
.br
\&...
.PP
See below for details about the configuration file.
.PP
To hedge against the unlikely event that the desired
.IR command 's
name actually begins with
.RB ` + ',
an argument consisting of a
.RB ` + '
sign on its own marks the end of the server configurations:
the following argument will be interpreted as the command name
regardless of its syntactic form.
If there is a
.RB ` + '
marker, but no server configurations,
then the configuration file is read,
or the default configuration is used,
as usual.
.
.SS "Configuration file"
The
.B with-authinfo-kludge
program reads configuration from a standard-ish
.RB ` .ini '-format
file.
The file consists of parameter settings of the form
.IP
.I param
.B =
.I value
.PP
divided into sections by headers of the form
.IP
.BI [ name ]
.PP
Whitespace around the
.IR name ,
.I param
and
.I value
strings is discarded.
A section
.I name
may itself contain square brackets,
and they need not be properly nested.
There is no syntax for continuing values over more than one line.
.PP
The file may also contain blank lines,
and comment lines whose first non-whitespace character is either
.RB ` # '
or
.RB ` ; '.
All such lines are ignored.
.PP
Parameter settings apply to the section named in the most recent
setion header.
Settings appearing before the first section header apply to
the special section named
.BR @GLOBAL ,
just as if a line
.IP
.B [@GLOBAL]
.PP
appeared at the very top of the file.
It is permitted (though not usually expected)
for several section headers to have the same name;
in this case,
all of the settings following any of the occurrences are gathered together,
just as if they'd all appeared under a single header,
in the same order.
If the same parameter is assigned more than once,
then only the
.I last
assignment has any effect.
.PP
With the exception of the
.B @GLOBAL
section,
each section header should name an NNTP server.
.PP
The following server parameters are recognized.
.TP
.BI local= host\fR[ : port \fR]
Sets the NNTP server address which the newsreader command
expects to connect to.
This does
.I not
have to be an address local to the machine on which
.B with-authinfo-kludge
runs.
It defaults to the
.I server
name from the section heading
(which must therefore be in the appropriate format),
and may be equal to the
.I remote
address (below) without causing difficulty.
Note that
.B with-authinfo-kludge
will not do anything to encourage the client
to connect to the right address;
its caller must arrange to configure the client correctly,
e.g., by setting the
.B NNTPSERVER
environment variable appropriately.
.TP
.BI nntpauth= "parameter arguments\fR..."
Set the AUTHINFO GENERIC authentication parameter and arguments
to use for this server.
The default is to use the settings from the
.B NNTPAUTH
environment variable.
.TP
.BI remote= host\fR[ : port \fR]
Sets the real address of the NNTP server which
.BR with-authinfo-kludge 's
proxy (or the SSH tunnel) should connect to.
It defaults to the
.I server
name from the section heading
(which must therefore be in the appropriate format).
.TP
.BI sshbind= host\fR[ : port\fR]
Change the address and port number
of the local end of the SSH tunnel
set up by the
.B via
parameter.
The default is to use
127.1.0.1:119.
It is
.I not
a problem for multiple servers to use the same address:
.B with-authinfo-kludge
uses the
.BR noip (1)
library to keep them
separate.
.TP
.BI via= gateway
Use SSH connection forwarding to reach the server.
The
.I gateway
is passed to
.BR ssh (1)
as its hostname parameter,
so may be a hostname or IP address,
possibly prefixed by
.IB user @
to choose a different login name;
or it may name a
.BR ssh_config (1)
stanza providing detailed configuration.
Note that the local end of the tunnel will
.I not
be exposed to other users of the local machine,
since this instance of SSH is run under the control of
.BR noip (1).
.PP
The various parameters which take network addresses
accept a common syntax:
.IP
.IR host \c
.RB [ : \c
.IR port ]
.PP
The
.I host
may be a hostname;
an IPv4 address in dotted-quad notation; or
an IPv6 address in hex-and-colons notation,
which must contain at least
.I two
colons to be valid.
Raw IP addresses may be surrounded by square brackets;
this is necessary to disambiguate a trailing
.BI : port
following an IPv6 address because the IPv6 address syntax is stupid.
.PP
The
.B @GLOBAL
section may set the following parameters.
.TP
.BI rundir= dir
Set the runtime directory to be
.IR dir .
This directory (but not its parent directories)
will be created automatically if necessary.
The default runtime directory is chosen in a complicated way;
see below.
.PP
The configuration file is found as follows.
.hP 1.
If server configurations are provided on the command line,
then they are used instead of any configuration file.
.hP 2.
If a
.B \-f
option is given, then it is read as a configuration file.
A fatal error is reported if the file does not exist,
or cannot be read for some other reason.
.hP 3.
The user's home directory is determined, as follows.
If the environment variable
.B HOME
is set, then its value is used.
Let
.I home
be the home directory so determined, if any.
.hP 4.
A `configuration home' directory is determined, as follows.
If the environment variable
.B XDG_CONFIG_HOME
is set, then its value is used.
Otherwise, the configuration home is
.IB home /.config \fR;
a fatal error is reported at this point
if no home directory was determined.
Let
.I config-home
denote the configuration home directory so determined.
.hP 5.
A `tag' is chosen, as follows.
If the
.B \-t
option is given, then its value is used;
otherwise the tag is the basename of the
.I command
(i.e., the part following the last
.RB ` / ',
if any).
Let
.I tag
denote the tag so chosen.
.hP 6.
If
.IB config-home /with-authinfo-kludge/ tag .conf
exists, then it is read as a configuration file.
(If it can't be read, then a fatal error is reported.)
.hP 7.
If
.IB config-home /with-authinfo-kludge/@default.conf
exists, then it is read as a configuration file.
(If it can't be read, then a fatal error is reported.)
.hP 8.
No configuration file could be found,
so a default configuration is constructed, as follows.
Let
.I nntp-server
be the value of the
.B NNTPSERVER
environment variable;
if it is not set, then a fatal error is reported.
The default configuration is as follows.
.RS
.IP
.BI [ nntp-server ]
.RE
.
.SS "The runtime directory"
(This section is technical, and can safely be skipped by most users.
It may be useful to know this stuff if
.B with-authinfo-kludge
is behaving confusingly and you're trying to understand why.)
.PP
The runtime directory is chosen as follows.
.hP 1.
If the
.B \-d
option is present, then its value is used.
Otherwise, if the configuration file specifies
a value for the global
.B rundir
parameter then that it used.
.hP 2.
If the environment variable
.B XDG_RUNTIME_DIR
is set, then let
.I run
denote its value;
then
.IB run /with-authinfo-kludge
is used as the runtime directory.
.hP 3
If the environment variable
.B TMPDIR
is set, then let
.I tmp
be its value;
otherwise, let
.I tmp
be
.BR /tmp .
Let
.I uid
be the current effective uid, in decimal,
without leading zeroes
(if the superuser is foolish enough to run this program then
.I uid
is
.BR 0 ).
If
.IB tmp/ with-authinfo-kludge- uid
exists,
is a directory (and not a symbolic link),
is owned by the current effective uid,
and has no permissions for group or others;
or if it does not exist but can be created with the above properties;
then it is used as the runtime directory.
.hP 4.
The user's home directory is determined, as follows.
If the environment variable
.B HOME
is set, then its value is used.
Let
.I home
be the home directory so determined, if any.
.hP 5.
A `cache home' directory is determined, as follows.
If the environment variable
.B XDG_CACHE_HOME
is set, then its value is used.
Otherwise, the configuration home is
.IB home /.cache \fR;
a fatal error is reported at this point
if no home directory was determined.
Let
.I cache-home
denote the cache home directory so determined.
If the cache home directory does not exist,
then it is created with mode 0777 (as modified by the umask).
.hP 6.
Let
.I hostname
be the local machine's hostname,
as reported by
.BR gethostname (2).
Then
.IB cache-home /with-authinfo-kludge. hostname
is used as the runtime directory.
.PP
If the directory chosen by the above procedure does not exist,
then it is created as a directory,
with mode 0700 (and modified by the umask).
(If it exists, but is not in fact a directory,
then later operations will fail.)
.PP
The runtime directory contains a number of other directories,
named
.IR tag . pid \fR.
Each such directory corresponds to a running
(or failed)
instance of
.BR with-authinfo-kludge ;
the
.I pid
is its process-id (possibly useful for diagnostic purposes),
and the
.I tag
is the tag summarizing its purpose
(as determined in step 5 of the procedure
for finding a configuration file).
.PP
The contents of the instance directory are as follows.
.TP
.B client.pid
The process-id of the client command run by
.BR with-authinfo-kludge .
.TP
.B lock
An empty file.
A
running
.B with-authinfo-kludge
process holds a lock on this file.
It is used simply to tell other processes that
the directory is still in use and shouldn't be cleaned up.
.TP
.B noip/
A directory containing Unix-domain sockets,
maintained by the
.B noip
library.
.TP
.B ssh.pid
The process-id of the SSH process started to satisfy a
.B via
server parameter.
.
.\"--------------------------------------------------------------------------
.SH BUGS
.
The program is probably too complicated for many uses,
but the author finds the various bells and whistles useful.
.PP
There isn't a good way to get two or more NNTP clients
to share the same proxy machinery.
This is somewhat wasteful.
Fixing this would necessitate some other way of
orchestrating the setup and teardown of runtime directories.
.
.\"--------------------------------------------------------------------------
.SH SEE ALSO
.
.BR authinfo-kludge (1),
.BR noip (1).
.PP
S. Barber,
.IR "RFC2980, Common NNTP Extensions",
.if !t \{\
.br
\h'5m'\c
.\}
.BR "https://www.ietf.org/rfc/rfc2980.txt" .
.
.SH AUTHOR
Mark Wooding,
<mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------