3 .\" Manual page for `with-authinfo-kludge'.
5 .\" (c) 2016 Mark Wooding
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This program is free software; you can redistribute it and/or modify
11 .\" it under the terms of the GNU General Public License as published by
12 .\" the Free Software Foundation; either version 2 of the License, or
13 .\" (at your option) any later version.
15 .\" This program is distributed in the hope that it will be useful,
16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 .\" GNU General Public License for more details.
20 .\" You should have received a copy of the GNU General Public License
21 .\" along with this program; if not, write to the Free Software Foundation,
22 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
33 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
49 .TH with-authinfo-kludge 1 "23 April 2016"
51 .\"--------------------------------------------------------------------------
53 with-authinfo-kludge \- run a newsreader with AUTHINFO GENERIC support
68 .RI [ param \fR= value
77 .\"--------------------------------------------------------------------------
81 .B with-authinfo-kludge
84 which runs another command
85 (typically a newsreader)
86 in an environment in which at can,
88 make connections to certain NNTP servers
91 authentication before they'll permit clients to read or post.
92 This is useful because support for
94 has never been especially widely supported by newsreaders
95 and now seems to be being withdrawn from those newsreaders
96 which used to support it.
98 In the simple case, you say something like
100 with-authinfo-kludge slrn
105 connect to your default NNTP server
108 environment variable),
109 authenticate to it as needed,
110 and let you read and post news.
111 In more complicated cases,
112 .B with-authinfo-kludge
113 can handle multiple NNTP servers,
114 set up SSH forwarding for them,
115 offer different authentication credentials to them,
116 and hide the fact that they might be running on nonstandard ports.
119 .B with-authinfo-kludge
120 program doesn't do all of this itself:
121 it depends on some other tools existing on the system in which it runs.
122 (It doesn't need anything special running on the server system.)
123 The external dependencies are as follows.
127 program, by Richard Kettlewell,
128 is a simple proxy which relays commands and responses
129 between the client (on stdin/stdout) and server (over TCP),
130 and responds transparently to authentication requests from the server.
134 hack, by Mark Wooding,
137 library which selectively uses Unix-domain sockets
138 in place of IPv4 or IPv6 sockets.
142 .B with-authinfo-kludge
143 program accepts a small number of options
144 before its main command-line arguments.
147 Write help about the command-line syntax to standard output,
148 and exit with status zero.
153 as the `runtime directory',
154 which is used to store sockets and other working files
156 .B with-authinfo-kludge
158 By default, it will choose an appropriate place
159 in a moderately complicated manner described below;
160 this option lets you override its choice
161 in order to achieve special effects.
164 Read configuration from
166 The default is somewhat complicated;
172 to distinguish this usage of
173 .B with-authinfo-kludge
175 The tag is used to select default configuration files
176 and runtime directories.
177 By default, the basename of the
182 Print messages explaining what
183 .B with-authinfo-kludge
184 is doing to standard error.
186 .B with-authinfo-kludge
187 does its thing silently unless there are problems.
191 argument names the command which should be run
192 with the various proxy arrangements which it is the task of
193 .B with-authinfo-kludge
194 to arrange; it will be passed the
197 The command name and arguments are not subject to
198 interpretation by the shell;
199 if, for some reason, you wanted to make use of shell features,
200 you should specify a command of the form
205 Between the options (if any) and the
208 there may be a number of server configurations.
209 If any are present, they take the place of any configuration file:
210 an error is reported if a
213 A server configuration starts with
214 an argument consisting of a server name prefixed by a
220 This may be followed by assignments
224 which set configuration parameters
225 for the previously-named server.
226 Such a server configuration on the command line
227 is treated exactly the same as a configuration-file section
235 See below for details about the configuration file.
237 To hedge against the unlikely event that the desired
239 name actually begins with
241 an argument consisting of a
243 sign on its own marks the end of the server configurations:
244 the following argument will be interpreted as the command name
245 regardless of its syntactic form.
248 marker, but no server configurations,
249 then the configuration file is read,
250 or the default configuration is used,
253 .SS "Configuration file"
255 .B with-authinfo-kludge
256 program reads configuration from a standard-ish
259 The file consists of parameter settings of the form
265 divided into sections by headers of the form
269 Whitespace around the
274 strings is discarded.
277 may itself contain square brackets,
278 and they need not be properly nested.
279 There is no syntax for continuing values over more than one line.
281 The file may also contain blank lines,
282 and comment lines whose first non-whitespace character is either
286 All such lines are ignored.
288 Parameter settings apply to the section named in the most recent
290 Settings appearing before the first section header apply to
291 the special section named
297 appeared at the very top of the file.
298 It is permitted (though not usually expected)
299 for several section headers to have the same name;
301 all of the settings following any of the occurrences are gathered together,
302 just as if they'd all appeared under a single header,
304 If the same parameter is assigned more than once,
307 assignment has any effect.
309 With the exception of the
312 each section header should name an NNTP server.
314 The following server parameters are recognized.
316 .BI local= host\fR[ : port \fR]
317 Sets the NNTP server address which the newsreader command
318 expects to connect to.
321 have to be an address local to the machine on which
322 .B with-authinfo-kludge
326 name from the section heading
327 (which must therefore be in the appropriate format),
328 and may be equal to the
330 address (below) without causing difficulty.
332 .B with-authinfo-kludge
333 will not do anything to encourage the client
334 to connect to the right address;
335 its caller must arrange to configure the client correctly,
338 environment variable appropriately.
340 .BI nntpauth= "parameter arguments\fR..."
341 Set the AUTHINFO GENERIC authentication parameter and arguments
342 to use for this server.
343 The default is to use the settings from the
345 environment variable.
347 .BI remote= host\fR[ : port \fR]
348 Sets the real address of the NNTP server which
349 .BR with-authinfo-kludge 's
350 proxy (or the SSH tunnel) should connect to.
353 name from the section heading
354 (which must therefore be in the appropriate format).
356 .BI sshbind= host\fR[ : port\fR]
357 Change the address and port number
358 of the local end of the SSH tunnel
362 The default is to use
366 a problem for multiple servers to use the same address:
367 .B with-authinfo-kludge
374 Use SSH connection forwarding to reach the server.
379 as its hostname parameter,
380 so may be a hostname or IP address,
383 to choose a different login name;
386 stanza providing detailed configuration.
387 Note that the local end of the tunnel will
389 be exposed to other users of the local machine,
390 since this instance of SSH is run under the control of
393 The various parameters which take network addresses
394 accept a common syntax:
403 an IPv4 address in dotted-quad notation; or
404 an IPv6 address in hex-and-colons notation,
405 which must contain at least
408 Raw IP addresses may be surrounded by square brackets;
409 this is necessary to disambiguate a trailing
411 following an IPv6 address because the IPv6 address syntax is stupid.
415 section may set the following parameters.
418 Set the runtime directory to be
420 This directory (but not its parent directories)
421 will be created automatically if necessary.
422 The default runtime directory is chosen in a complicated way;
425 The configuration file is found as follows.
427 If server configurations are provided on the command line,
428 then they are used instead of any configuration file.
432 option is given, then it is read as a configuration file.
433 A fatal error is reported if the file does not exist,
434 or cannot be read for some other reason.
436 The user's home directory is determined, as follows.
437 If the environment variable
439 is set, then its value is used.
442 be the home directory so determined, if any.
444 A `configuration home' directory is determined, as follows.
445 If the environment variable
447 is set, then its value is used.
448 Otherwise, the configuration home is
449 .IB home /.config \fR;
450 a fatal error is reported at this point
451 if no home directory was determined.
454 denote the configuration home directory so determined.
456 A `tag' is chosen, as follows.
459 option is given, then its value is used;
460 otherwise the tag is the basename of the
462 (i.e., the part following the last
467 denote the tag so chosen.
470 .IB config-home /with-authinfo-kludge/ tag .conf
471 exists, then it is read as a configuration file.
472 (If it can't be read, then a fatal error is reported.)
475 .IB config-home /with-authinfo-kludge/@default.conf
476 exists, then it is read as a configuration file.
477 (If it can't be read, then a fatal error is reported.)
479 No configuration file could be found,
480 so a default configuration is constructed, as follows.
485 environment variable;
486 if it is not set, then a fatal error is reported.
487 The default configuration is as follows.
493 .SS "The runtime directory"
494 (This section is technical, and can safely be skipped by most users.
495 It may be useful to know this stuff if
496 .B with-authinfo-kludge
497 is behaving confusingly and you're trying to understand why.)
499 The runtime directory is chosen as follows.
503 option is present, then its value is used.
504 Otherwise, if the configuration file specifies
505 a value for the global
507 parameter then that it used.
509 If the environment variable
515 .IB run /with-authinfo-kludge
516 is used as the runtime directory.
518 If the environment variable
529 be the current effective uid, in decimal,
530 without leading zeroes
531 (if the superuser is foolish enough to run this program then
536 .IB tmp/ with-authinfo-kludge- uid
538 is a directory (and not a symbolic link),
539 is owned by the current effective uid,
540 and has no permissions for group or others;
541 or if it does not exist but can be created with the above properties;
542 then it is used as the runtime directory.
544 The user's home directory is determined, as follows.
545 If the environment variable
547 is set, then its value is used.
550 be the home directory so determined, if any.
552 A `cache home' directory is determined, as follows.
553 If the environment variable
555 is set, then its value is used.
556 Otherwise, the configuration home is
557 .IB home /.cache \fR;
558 a fatal error is reported at this point
559 if no home directory was determined.
562 denote the cache home directory so determined.
563 If the cache home directory does not exist,
564 then it is created with mode 0777 (as modified by the umask).
568 be the local machine's hostname,
572 .IB cache-home /with-authinfo-kludge. hostname
573 is used as the runtime directory.
575 If the directory chosen by the above procedure does not exist,
576 then it is created as a directory,
577 with mode 0700 (and modified by the umask).
578 (If it exists, but is not in fact a directory,
579 then later operations will fail.)
581 The runtime directory contains a number of other directories,
584 Each such directory corresponds to a running
587 .BR with-authinfo-kludge ;
590 is its process-id (possibly useful for diagnostic purposes),
593 is the tag summarizing its purpose
594 (as determined in step 5 of the procedure
595 for finding a configuration file).
597 The contents of the instance directory are as follows.
600 The process-id of the client command run by
601 .BR with-authinfo-kludge .
607 .B with-authinfo-kludge
608 process holds a lock on this file.
609 It is used simply to tell other processes that
610 the directory is still in use and shouldn't be cleaned up.
613 A directory containing Unix-domain sockets,
619 The process-id of the SSH process started to satisfy a
623 .\"--------------------------------------------------------------------------
626 The program is probably too complicated for many uses,
627 but the author finds the various bells and whistles useful.
629 There isn't a good way to get two or more NNTP clients
630 to share the same proxy machinery.
631 This is somewhat wasteful.
632 Fixing this would necessitate some other way of
633 orchestrating the setup and teardown of runtime directories.
635 .\"--------------------------------------------------------------------------
638 .BR authinfo-kludge (1),
642 .IR "RFC2980, Common NNTP Extensions",
647 .BR "https://www.ietf.org/rfc/rfc2980.txt" .
651 <mdw@distorted.org.uk>
653 .\"----- That's all, folks --------------------------------------------------