--- /dev/null
+.\" -*-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.
+.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.
+Otherwise, the current effective uid is looked up
+in the password database
+(using
+.BR getpwuid (3));
+and the home directory taken from the record.
+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.
+.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.
+The user's name is determined, as follows.
+If the environment variable
+.B USER
+is set, then its value is used.
+Otherwise, if, the environment variable
+.B LOGNAME
+is set, then its value is used.
+Otherwise, the current effective uid is looked up
+in the password database
+(using
+.BR getpwuid (3));
+and the name taken from the record.
+Let
+.I user
+be the user name so determined, if any.
+.hP 4
+If no user name could be determined, then skip this step.
+If the environment variable
+.B TMPDIR
+is set, then let
+.I tmp
+be its value;
+otherwise, let
+.I tmp
+be
+.BR /tmp .
+If
+.IB tmp/ with-authinfo-kludge- user
+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 5.
+The user's home directory is determined, as follows.
+If the environment variable
+.B HOME
+is set, then its value is used.
+Otherwise, the current effective uid is looked up
+in the password database
+(using
+.BR getpwuid (3));
+and the home directory taken from the record.
+Let
+.I home
+be the home directory so determined, if any.
+.hP 6.
+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 7.
+Let
+.I hostname
+be the local machine's hostname,
+as reported by
+.BR gethostname (2).
+If
+.IB cache-home /with-authinfo-kludge. hostname
+does not exist,
+then it is created as a directory,
+with mode 0700 (and modified by the umask).
+This directory is then used as the runtime directory.
+(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.
+.PP
+Maybe there ought to be a way to set
+a separate runtime directory for each server.
+But, really, I had to draw a line somewhere.
+.
+.\"--------------------------------------------------------------------------
+.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 --------------------------------------------------
~mdw / with-authinfo-kludge / commitdiff