From b337091895378abc68fae09625ff97f302b78027 Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Sat, 23 Apr 2016 17:50:15 +0100 Subject: [PATCH] with-authinfo-kludge.1: Let's start with a manpage. --- with-authinfo-kludge.1 | 663 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 663 insertions(+) create mode 100644 with-authinfo-kludge.1 diff --git a/with-authinfo-kludge.1 b/with-authinfo-kludge.1 new file mode 100644 index 0000000..138c5f8 --- /dev/null +++ b/with-authinfo-kludge.1 @@ -0,0 +1,663 @@ +.\" -*-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, + +. +.\"----- That's all, folks -------------------------------------------------- -- 2.11.0