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 it 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 implemented 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.
241 or, less plausibly, beginning with
243 an argument consisting of a
245 sign on its own marks the end of the server configurations:
246 the following argument will be interpreted as the command name
247 regardless of its syntactic form.
250 marker, but no server configurations,
251 then the configuration file is read,
252 or the default configuration is used,
255 .SS "Configuration file"
257 .B with-authinfo-kludge
258 program reads configuration from a standard-ish
261 The file consists of parameter settings of the form
267 divided into sections by headers of the form
271 Whitespace around the
276 strings is discarded.
279 may itself contain square brackets,
280 and they need not be properly nested.
281 There is no syntax for continuing values over more than one line.
283 The file may also contain blank lines,
284 and comment lines whose first non-whitespace character is either
288 All such lines are ignored.
290 Parameter settings apply to the section named in the most recent
292 Settings appearing before the first section header apply to
293 the special section named
299 appeared at the very top of the file.
300 It is permitted (though not usually expected)
301 for several section headers to have the same name;
303 all of the settings following any of the occurrences are gathered together,
304 just as if they'd all appeared under a single header,
306 If the same parameter is assigned more than once,
309 assignment has any effect.
311 With the exception of the
314 each section header should name an NNTP server.
316 The following server parameters are recognized.
318 .BI local= host\fR[ : port \fR]
319 Sets the NNTP server address which the newsreader command
320 expects to connect to.
323 have to be an address local to the machine on which
324 .B with-authinfo-kludge
328 name from the section heading
329 (which must therefore be in the appropriate format),
330 and may be equal to the
332 address (below) without causing difficulty.
334 .B with-authinfo-kludge
335 will not do anything to encourage the client
336 to connect to the right address;
337 its caller must arrange to configure the client correctly,
340 environment variable appropriately.
342 .BI nntpauth= "parameter arguments\fR..."
343 Set the AUTHINFO GENERIC authentication parameter and arguments
344 to use for this server.
345 The default is to use the settings from the
347 environment variable.
349 .BI remote= host\fR[ : port \fR]
350 Sets the real address of the NNTP server which
351 .BR with-authinfo-kludge 's
352 proxy (or the SSH tunnel) should connect to.
355 name from the section heading
356 (which must therefore be in the appropriate format).
358 .BI sshbind= host\fR[ : port\fR]
359 Change the address and port number
360 of the local end of the SSH tunnel
364 The default is to use
366 because OpenSSH refuses to try to listen on low-numbered ports
367 rather than trying it and seeing whether it would work
368 (which it would, in this case).
371 a problem for multiple servers to use the same address:
372 .B with-authinfo-kludge
379 Use SSH connection forwarding to reach the server.
384 as its hostname parameter,
385 so may be a hostname or IP address,
388 to choose a different login name;
391 stanza providing detailed configuration.
392 Note that the local end of the tunnel will
394 be exposed to other users of the local machine,
395 since this instance of SSH is run under the control of
398 The various parameters which take network addresses
399 accept a common syntax:
408 an IPv4 address in dotted-quad notation; or
409 an IPv6 address in hex-and-colons notation,
410 which must contain at least
413 Raw IP addresses may be surrounded by square brackets;
414 this is necessary to disambiguate a trailing
416 following an IPv6 address because the IPv6 address syntax is stupid.
420 section may set the following parameters.
423 Set the runtime directory to be
425 This directory (but not its parent directories)
426 will be created automatically if necessary.
427 The default runtime directory is chosen in a complicated way;
430 The configuration file is found as follows.
432 If server configurations are provided on the command line,
433 then they are used instead of any configuration file.
437 option is given, then it is read as a configuration file.
438 A fatal error is reported if the file does not exist,
439 or cannot be read for some other reason.
443 be the value of the environment variable
445 if this variable is not set, then
449 A `configuration path' is built, as follows.
450 If the environment variable
452 is set, then its value is the first entry in the path;
453 otherwise the first entry is
454 .IB home /.config \fR;
455 a fatal error is reported at this point
456 if no home directory was determined.
457 If the environment variable
462 entries in its value are appended to the path;
463 otherwise, the single entry
467 A `tag' is chosen, as follows.
470 option is given, then its value is used;
471 otherwise the tag is the basename of the
473 (i.e., the part following the last
478 denote the tag so chosen.
480 A search is made for a file
481 .IB dir /with-authinfo-kludge/ tag .conf
484 in the configuration path established in step 4,
486 If such a file exists exists,
487 then it is read as a configuration file.
488 (If it can't be read, then a fatal error is reported.)
490 A similar search is made for
491 .IB dir /with-authinfo-kludge/@default.conf \fR.
492 If such a file exists,
493 then it is read as a configuration file.
494 (If it can't be read, then a fatal error is reported.)
496 No configuration file could be found,
497 so a default configuration is constructed, as follows.
502 environment variable;
503 if it is not set, then a fatal error is reported.
504 The default configuration is as follows.
510 .SS "The runtime directory"
511 (This section is technical, and can safely be skipped by most users.
512 It may be useful to know this stuff if
513 .B with-authinfo-kludge
514 is behaving confusingly and you're trying to understand why.)
516 The runtime directory is chosen as follows.
520 option is present, then its value is used.
521 Otherwise, if the configuration file specifies
522 a value for the global
524 parameter then that it used.
526 If the environment variable
532 .IB run /with-authinfo-kludge
533 is used as the runtime directory.
535 If the environment variable
546 be the current effective uid, in decimal,
547 without leading zeroes
548 (if the superuser is foolish enough to run this program then
553 .IB tmp/ with-authinfo-kludge- uid
555 is a directory (and not a symbolic link),
556 is owned by the current effective uid,
557 and has no permissions for group or others;
558 or if it does not exist but can be created with the above properties;
559 then it is used as the runtime directory.
563 be the value of the environment variable
565 if this variable is not set, then
569 A `cache home' directory is determined, as follows.
570 If the environment variable
572 is set, then its value is used.
573 Otherwise, the configuration home is
574 .IB home /.cache \fR;
575 a fatal error is reported at this point
576 if no home directory was determined.
579 denote the cache home directory so determined.
580 If the cache home directory does not exist,
581 then it is created with mode 0777 (as modified by the umask).
585 be the local machine's hostname,
589 .IB cache-home /with-authinfo-kludge. hostname
590 is used as the runtime directory.
592 If the directory chosen by the above procedure does not exist,
593 then it is created as a directory,
594 with mode 0700 (and modified by the umask).
595 (If it exists, but is not in fact a directory,
596 then later operations will fail.)
598 The runtime directory contains a number of other directories.
599 There are a small number of shared directories,
603 each one corresponding to a running
606 .BR with-authinfo-kludge .
608 The shared directories are as follows.
611 This is the `nursery' directory:
612 new session directories are created and populated in here.
613 Subdirectories have names of the form
614 .BI n. time . pid . rand /
618 (seconds since the POSIX epoch)
619 at which the directory was created;
621 is the creator's process id; and
623 is a random number chosen to minimize conflicts.
624 Directories in the nursery older than 300 seconds
626 The creation protocol is to
627 create a directory with an appropriate name;
628 create a file within it named
632 exclusive lock on this file;
633 and then move the directory to be a direct child
634 of the runtime directory.
637 Session and nursery directories are deleted in two stages:
638 the first stage is to make them be subdirectories of
640 Once there, any process may delete them.
641 Note that nursery directories can be junked
642 even if they're locked:
645 prevents them from being promoted to proper sessions.
647 Session directories are named
651 is the tag summarizing its purpose
652 (as determined in step 5 of the procedure
653 for finding a configuration file), and
656 is the creator's process-id,
657 which distinguishes this session from others with the same tag.
659 The contents of a session directory are as follows.
662 The process-id of the client command run by
663 .BR with-authinfo-kludge .
669 .B with-authinfo-kludge
673 It is used simply to tell other processes that
674 the directory is still in use and shouldn't be cleaned up.
677 A directory containing Unix-domain sockets created by
678 .BR with-authinfo-kludge ;
681 library arranges for the client program
682 to connect to these Unix-domain sockets
683 rather than to the real remote NNTP servers.
685 .BR noip-ssh. server /
686 This directory also contains Unix-domain sockets ;
692 both under the influence of
696 The process-id of the SSH process started to satisfy a
700 .\"--------------------------------------------------------------------------
703 The program is probably too complicated for many uses,
704 but the author finds the various bells and whistles useful.
706 There isn't a good way to get two or more NNTP clients
707 to share the same proxy machinery.
708 This is somewhat wasteful.
709 Fixing this would necessitate some other way of
710 orchestrating the setup and teardown of runtime directories.
712 .\"--------------------------------------------------------------------------
715 .BR authinfo-kludge (1),
719 .IR "RFC2980, Common NNTP Extensions",
724 .BR "https://www.ietf.org/rfc/rfc2980.txt" .
728 <mdw@distorted.org.uk>
730 .\"----- That's all, folks --------------------------------------------------
~mdw / with-authinfo-kludge / blob