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 .BI nntpauth= "parameter arguments\fR..."
333 Set the AUTHINFO GENERIC authentication parameter and arguments
334 to use for this server.
335 The default is to use the settings from the
337 environment variable.
339 .BI remote= host\fR[ : port \fR]
340 Sets the real address of the NNTP server which
341 .BR with-authinfo-kludge 's
342 proxy (or the SSH tunnel) should connect to.
345 name from the section heading
346 (which must therefore be in the appropriate format).
348 .BI sshbind= host\fR[ : port\fR]
349 Change the address and port number
350 of the local end of the SSH tunnel
354 The default is to use
358 a problem for multiple servers to use the same address:
359 .B with-authinfo-kludge
366 Use SSH connection forwarding to reach the server.
371 as its hostname parameter,
372 so may be a hostname or IP address,
375 to choose a different login name;
378 stanza providing detailed configuration.
379 Note that the local end of the tunnel will
381 be exposed to other users of the local machine,
382 since this instance of SSH is run under the control of
385 The various parameters which take network addresses
386 accept a common syntax:
395 an IPv4 address in dotted-quad notation; or
396 an IPv6 address in hex-and-colons notation,
397 which must contain at least
400 Raw IP addresses may be surrounded by square brackets;
401 this is necessary to disambiguate a trailing
403 following an IPv6 address because the IPv6 address syntax is stupid.
407 section may set the following parameters.
410 Set the runtime directory to be
412 This directory (but not its parent directories)
413 will be created automatically if necessary.
414 The default runtime directory is chosen in a complicated way;
417 The configuration file is found as follows.
419 If server configurations are provided on the command line,
420 then they are used instead of any configuration file.
424 option is given, then it is read as a configuration file.
425 A fatal error is reported if the file does not exist,
426 or cannot be read for some other reason.
428 The user's home directory is determined, as follows.
429 If the environment variable
431 is set, then its value is used.
434 be the home directory so determined, if any.
436 A `configuration home' directory is determined, as follows.
437 If the environment variable
439 is set, then its value is used.
440 Otherwise, the configuration home is
441 .IB home /.config \fR;
442 a fatal error is reported at this point
443 if no home directory was determined.
446 denote the configuration home directory so determined.
448 A `tag' is chosen, as follows.
451 option is given, then its value is used;
452 otherwise the tag is the basename of the
454 (i.e., the part following the last
459 denote the tag so chosen.
462 .IB config-home /with-authinfo-kludge/ tag .conf
463 exists, then it is read as a configuration file.
464 (If it can't be read, then a fatal error is reported.)
467 .IB config-home /with-authinfo-kludge/@default.conf
468 exists, then it is read as a configuration file.
469 (If it can't be read, then a fatal error is reported.)
471 No configuration file could be found,
472 so a default configuration is constructed, as follows.
477 environment variable;
478 if it is not set, then a fatal error is reported.
479 The default configuration is as follows.
485 .SS "The runtime directory"
486 (This section is technical, and can safely be skipped by most users.
487 It may be useful to know this stuff if
488 .B with-authinfo-kludge
489 is behaving confusingly and you're trying to understand why.)
491 The runtime directory is chosen as follows.
495 option is present, then its value is used.
497 If the environment variable
503 .IB run /with-authinfo-kludge
504 is used as the runtime directory.
506 If the environment variable
517 be the current effective uid, in decimal,
518 without leading zeroes
519 (if the superuser is foolish enough to run this program then
524 .IB tmp/ with-authinfo-kludge- uid
526 is a directory (and not a symbolic link),
527 is owned by the current effective uid,
528 and has no permissions for group or others;
529 or if it does not exist but can be created with the above properties;
530 then it is used as the runtime directory.
532 The user's home directory is determined, as follows.
533 If the environment variable
535 is set, then its value is used.
538 be the home directory so determined, if any.
540 A `cache home' directory is determined, as follows.
541 If the environment variable
543 is set, then its value is used.
544 Otherwise, the configuration home is
545 .IB home /.cache \fR;
546 a fatal error is reported at this point
547 if no home directory was determined.
550 denote the cache home directory so determined.
551 If the cache home directory does not exist,
552 then it is created with mode 0777 (as modified by the umask).
556 be the local machine's hostname,
560 .IB cache-home /with-authinfo-kludge. hostname
562 then it is created as a directory,
563 with mode 0700 (and modified by the umask).
564 This directory is then used as the runtime directory.
565 (If it exists, but is not in fact a directory,
566 then later operations will fail.)
568 The runtime directory contains a number of other directories,
571 Each such directory corresponds to a running
574 .BR with-authinfo-kludge ;
577 is its process-id (possibly useful for diagnostic purposes),
580 is the tag summarizing its purpose
581 (as determined in step 5 of the procedure
582 for finding a configuration file).
584 The contents of the instance directory are as follows.
587 The process-id of the client command run by
588 .BR with-authinfo-kludge .
594 .B with-authinfo-kludge
595 process holds a lock on this file.
596 It is used simply to tell other processes that
597 the directory is still in use and shouldn't be cleaned up.
600 A directory containing Unix-domain sockets,
606 The process-id of the SSH process started to satisfy a
610 .\"--------------------------------------------------------------------------
613 The program is probably too complicated for many uses,
614 but the author finds the various bells and whistles useful.
616 There isn't a good way to get two or more NNTP clients
617 to share the same proxy machinery.
618 This is somewhat wasteful.
619 Fixing this would necessitate some other way of
620 orchestrating the setup and teardown of runtime directories.
622 Maybe there ought to be a way to set
623 a separate runtime directory for each server.
624 But, really, I had to draw a line somewhere.
626 .\"--------------------------------------------------------------------------
629 .BR authinfo-kludge (1),
633 .IR "RFC2980, Common NNTP Extensions",
638 .BR "https://www.ietf.org/rfc/rfc2980.txt" .
642 <mdw@distorted.org.uk>
644 .\"----- That's all, folks --------------------------------------------------