Commit | Line | Data |
---|---|---|
b3370918 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Manual page for `with-authinfo-kludge'. | |
4 | .\" | |
5 | .\" (c) 2016 Mark Wooding | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
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. | |
14 | .\" | |
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. | |
19 | .\" | |
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. | |
23 | . | |
24 | .ie t \{\ | |
25 | . ds o \(bu | |
26 | .\} | |
27 | .el \{\ | |
28 | . ds o o | |
29 | .\} | |
30 | . | |
31 | .de hP | |
32 | .IP | |
33 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
34 | .. | |
35 | . | |
36 | .de VS | |
37 | .sp 1 | |
38 | .RS | |
39 | .nf | |
40 | .ft B | |
41 | .. | |
42 | .de VE | |
43 | .ft R | |
44 | .fi | |
45 | .RE | |
46 | .sp 1 | |
47 | .. | |
48 | . | |
49 | .TH with-authinfo-kludge 1 "23 April 2016" | |
50 | . | |
51 | .\"-------------------------------------------------------------------------- | |
52 | .SH NAME | |
53 | with-authinfo-kludge \- run a newsreader with AUTHINFO GENERIC support | |
54 | . | |
55 | .SH SYNOPSIS | |
56 | with-authinfo-kludge | |
57 | .RB [ \-v ] | |
58 | .RB [ \-d | |
59 | .IR dir ] | |
60 | .RB [ \-f | |
61 | .IR conf ] | |
62 | .RB [ \-t | |
63 | .IR tag ] | |
64 | .br | |
65 | \h'5m'\c | |
66 | [ | |
67 | .BI + server | |
68 | .RI [ param \fR= value | |
69 | \&...] \&...] | |
70 | .RB [ + ] | |
71 | .br | |
72 | \h'5m'\c | |
73 | .I command | |
74 | .RI [ args | |
75 | \&...] | |
76 | . | |
77 | .\"-------------------------------------------------------------------------- | |
78 | .SH DESCRIPTION | |
79 | . | |
80 | The | |
81 | .B with-authinfo-kludge | |
82 | program is an | |
83 | .I adverbial modifier | |
84 | which runs another command | |
85 | (typically a newsreader) | |
86 | in an environment in which at can, | |
87 | transparently to it, | |
88 | make connections to certain NNTP servers | |
89 | which usually require | |
90 | .B AUTHINFO GENERIC | |
91 | authentication before they'll permit clients to read or post. | |
92 | This is useful because support for | |
93 | .B AUTHINFO GENERIC | |
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. | |
97 | .PP | |
98 | In the simple case, you say something like | |
99 | .VS | |
100 | with-authinfo-kludge slrn | |
101 | .VE | |
102 | and then | |
103 | .B slrn | |
104 | will start up, | |
105 | connect to your default NNTP server | |
106 | (as named in the | |
107 | .B NNTPSERVER | |
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. | |
117 | .PP | |
118 | The | |
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. | |
124 | .hP \*o | |
125 | The | |
126 | .B authinfo-kludge | |
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. | |
131 | .hP \*o | |
132 | The | |
133 | .B noip | |
134 | hack, by Mark Wooding, | |
135 | is an | |
136 | .B LD_PRELOAD | |
137 | library which selectively uses Unix-domain sockets | |
138 | in place of IPv4 or IPv6 sockets. | |
139 | . | |
140 | .SS "Command line" | |
141 | The | |
142 | .B with-authinfo-kludge | |
143 | program accepts a small number of options | |
144 | before its main command-line arguments. | |
145 | .TP | |
146 | .B \-h | |
147 | Write help about the command-line syntax to standard output, | |
148 | and exit with status zero. | |
149 | .TP | |
150 | .BI "\-d " dir | |
151 | Use | |
152 | .I dir | |
153 | as the `runtime directory', | |
154 | which is used to store sockets and other working files | |
155 | while | |
156 | .B with-authinfo-kludge | |
157 | is running. | |
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. | |
162 | .TP | |
163 | .BI "\-f " conf | |
164 | Read configuration from | |
165 | .IR conf . | |
166 | The default is somewhat complicated; | |
167 | see below. | |
168 | .TP | |
169 | .BI "\-t " tag | |
170 | Use | |
171 | .I tag | |
172 | to distinguish this usage of | |
173 | .B with-authinfo-kludge | |
174 | from others. | |
175 | The tag is used to select default configuration files | |
176 | and runtime directories. | |
177 | By default, the basename of the | |
178 | .I command | |
179 | is used. | |
180 | .TP | |
181 | .B "\-v" | |
182 | Print messages explaining what | |
183 | .B with-authinfo-kludge | |
184 | is doing to standard error. | |
185 | By default, | |
186 | .B with-authinfo-kludge | |
187 | does its thing silently unless there are problems. | |
188 | .PP | |
189 | The | |
190 | .I command | |
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 | |
195 | .IR args , | |
196 | if any. | |
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 | |
201 | .B /bin/sh | |
202 | .B \-c | |
203 | .IR shell-fragment . | |
204 | .PP | |
205 | Between the options (if any) and the | |
206 | .I command | |
207 | name, | |
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 | |
211 | .B \-f | |
212 | option was passed. | |
213 | A server configuration starts with | |
214 | an argument consisting of a server name prefixed by a | |
215 | .RB ` + ' | |
216 | character: | |
217 | .IP | |
218 | .BI + server | |
219 | .PP | |
220 | This may be followed by assignments | |
221 | .IP | |
222 | .IB param = value | |
223 | .PP | |
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 | |
228 | .IP | |
229 | .BI [ server ] | |
230 | .br | |
231 | .IB param = value | |
232 | .br | |
233 | \&... | |
234 | .PP | |
235 | See below for details about the configuration file. | |
236 | .PP | |
237 | To hedge against the unlikely event that the desired | |
238 | .IR command 's | |
239 | name actually begins with | |
240 | .RB ` + ', | |
241 | an argument consisting of a | |
242 | .RB ` + ' | |
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. | |
246 | If there is a | |
247 | .RB ` + ' | |
248 | marker, but no server configurations, | |
249 | then the configuration file is read, | |
250 | or the default configuration is used, | |
251 | as usual. | |
252 | . | |
253 | .SS "Configuration file" | |
254 | The | |
255 | .B with-authinfo-kludge | |
256 | program reads configuration from a standard-ish | |
257 | .RB ` .ini '-format | |
258 | file. | |
259 | The file consists of parameter settings of the form | |
260 | .IP | |
261 | .I param | |
262 | .B = | |
263 | .I value | |
264 | .PP | |
265 | divided into sections by headers of the form | |
266 | .IP | |
267 | .BI [ name ] | |
268 | .PP | |
269 | Whitespace around the | |
270 | .IR name , | |
271 | .I param | |
272 | and | |
273 | .I value | |
274 | strings is discarded. | |
275 | A section | |
276 | .I name | |
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. | |
280 | .PP | |
281 | The file may also contain blank lines, | |
282 | and comment lines whose first non-whitespace character is either | |
283 | .RB ` # ' | |
284 | or | |
285 | .RB ` ; '. | |
286 | All such lines are ignored. | |
287 | .PP | |
288 | Parameter settings apply to the section named in the most recent | |
289 | setion header. | |
290 | Settings appearing before the first section header apply to | |
291 | the special section named | |
292 | .BR @GLOBAL , | |
293 | just as if a line | |
294 | .IP | |
295 | .B [@GLOBAL] | |
296 | .PP | |
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; | |
300 | in this case, | |
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, | |
303 | in the same order. | |
304 | If the same parameter is assigned more than once, | |
305 | then only the | |
306 | .I last | |
307 | assignment has any effect. | |
308 | .PP | |
309 | With the exception of the | |
310 | .B @GLOBAL | |
311 | section, | |
312 | each section header should name an NNTP server. | |
313 | .PP | |
314 | The following server parameters are recognized. | |
315 | .TP | |
316 | .BI local= host\fR[ : port \fR] | |
317 | Sets the NNTP server address which the newsreader command | |
318 | expects to connect to. | |
319 | This does | |
320 | .I not | |
321 | have to be an address local to the machine on which | |
322 | .B with-authinfo-kludge | |
323 | runs. | |
324 | It defaults to the | |
325 | .I server | |
326 | name from the section heading | |
327 | (which must therefore be in the appropriate format), | |
328 | and may be equal to the | |
329 | .I remote | |
330 | address (below) without causing difficulty. | |
331 | .TP | |
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 | |
336 | .B NNTPAUTH | |
337 | environment variable. | |
338 | .TP | |
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. | |
343 | It defaults to the | |
344 | .I server | |
345 | name from the section heading | |
346 | (which must therefore be in the appropriate format). | |
347 | .TP | |
348 | .BI sshbind= host\fR[ : port\fR] | |
349 | Change the address and port number | |
350 | of the local end of the SSH tunnel | |
351 | set up by the | |
352 | .B via | |
353 | parameter. | |
354 | The default is to use | |
355 | 127.1.0.1:119. | |
356 | It is | |
357 | .I not | |
358 | a problem for multiple servers to use the same address: | |
359 | .B with-authinfo-kludge | |
360 | uses the | |
361 | .BR noip (1) | |
362 | library to keep them | |
363 | separate. | |
364 | .TP | |
365 | .BI via= gateway | |
366 | Use SSH connection forwarding to reach the server. | |
367 | The | |
368 | .I gateway | |
369 | is passed to | |
370 | .BR ssh (1) | |
371 | as its hostname parameter, | |
372 | so may be a hostname or IP address, | |
373 | possibly prefixed by | |
374 | .IB user @ | |
375 | to choose a different login name; | |
376 | or it may name a | |
377 | .BR ssh_config (1) | |
378 | stanza providing detailed configuration. | |
379 | Note that the local end of the tunnel will | |
380 | .I not | |
381 | be exposed to other users of the local machine, | |
382 | since this instance of SSH is run under the control of | |
383 | .BR noip (1). | |
384 | .PP | |
385 | The various parameters which take network addresses | |
386 | accept a common syntax: | |
387 | .IP | |
388 | .IR host \c | |
389 | .RB [ : \c | |
390 | .IR port ] | |
391 | .PP | |
392 | The | |
393 | .I host | |
394 | may be a hostname; | |
395 | an IPv4 address in dotted-quad notation; or | |
396 | an IPv6 address in hex-and-colons notation, | |
397 | which must contain at least | |
398 | .I two | |
399 | colons to be valid. | |
400 | Raw IP addresses may be surrounded by square brackets; | |
401 | this is necessary to disambiguate a trailing | |
402 | .BI : port | |
403 | following an IPv6 address because the IPv6 address syntax is stupid. | |
404 | .PP | |
405 | The | |
406 | .B @GLOBAL | |
407 | section may set the following parameters. | |
408 | .TP | |
409 | .BI rundir= dir | |
410 | Set the runtime directory to be | |
411 | .IR dir . | |
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; | |
415 | see below. | |
416 | .PP | |
417 | The configuration file is found as follows. | |
418 | .hP 1. | |
419 | If server configurations are provided on the command line, | |
420 | then they are used instead of any configuration file. | |
421 | .hP 2. | |
422 | If a | |
423 | .B \-f | |
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. | |
427 | .hP 3. | |
428 | The user's home directory is determined, as follows. | |
429 | If the environment variable | |
430 | .B HOME | |
431 | is set, then its value is used. | |
432 | Otherwise, the current effective uid is looked up | |
433 | in the password database | |
434 | (using | |
435 | .BR getpwuid (3)); | |
436 | and the home directory taken from the record. | |
437 | Let | |
438 | .I home | |
439 | be the home directory so determined, if any. | |
440 | .hP 4. | |
441 | A `configuration home' directory is determined, as follows. | |
442 | If the environment variable | |
443 | .B XDG_CONFIG_HOME | |
444 | is set, then its value is used. | |
445 | Otherwise, the configuration home is | |
446 | .IB home /.config \fR; | |
447 | a fatal error is reported at this point | |
448 | if no home directory was determined. | |
449 | Let | |
450 | .I config-home | |
451 | denote the configuration home directory so determined. | |
452 | .hP 5. | |
453 | A `tag' is chosen, as follows. | |
454 | If the | |
455 | .B \-t | |
456 | option is given, then its value is used; | |
457 | otherwise the tag is the basename of the | |
458 | .I command | |
459 | (i.e., the part following the last | |
460 | .RB ` / ', | |
461 | if any). | |
462 | Let | |
463 | .I tag | |
464 | denote the tag so chosen. | |
465 | .hP 6. | |
466 | If | |
467 | .IB config-home /with-authinfo-kludge/ tag .conf | |
468 | exists, then it is read as a configuration file. | |
469 | (If it can't be read, then a fatal error is reported.) | |
470 | .hP 7. | |
471 | If | |
472 | .IB config-home /with-authinfo-kludge/@default.conf | |
473 | exists, then it is read as a configuration file. | |
474 | (If it can't be read, then a fatal error is reported.) | |
475 | .hP 8. | |
476 | No configuration file could be found, | |
477 | so a default configuration is constructed, as follows. | |
478 | Let | |
479 | .I nntp-server | |
480 | be the value of the | |
481 | .B NNTPSERVER | |
482 | environment variable; | |
483 | if it is not set, then a fatal error is reported. | |
484 | The default configuration is as follows. | |
485 | .RS | |
486 | .IP | |
487 | .BI [ nntp-server ] | |
488 | .RE | |
489 | . | |
490 | .SS "The runtime directory" | |
491 | (This section is technical, and can safely be skipped by most users. | |
492 | It may be useful to know this stuff if | |
493 | .B with-authinfo-kludge | |
494 | is behaving confusingly and you're trying to understand why.) | |
495 | .PP | |
496 | The runtime directory is chosen as follows. | |
497 | .hP 1. | |
498 | If the | |
499 | .B \-d | |
500 | option is present, then its value is used. | |
501 | .hP 2. | |
502 | If the environment variable | |
503 | .B XDG_RUNTIME_DIR | |
504 | is set, then let | |
505 | .I run | |
506 | denote its value; | |
507 | then | |
508 | .IB run /with-authinfo-kludge | |
509 | is used as the runtime directory. | |
510 | .hP 3. | |
511 | The user's name is determined, as follows. | |
512 | If the environment variable | |
513 | .B USER | |
514 | is set, then its value is used. | |
515 | Otherwise, if, the environment variable | |
516 | .B LOGNAME | |
517 | is set, then its value is used. | |
518 | Otherwise, the current effective uid is looked up | |
519 | in the password database | |
520 | (using | |
521 | .BR getpwuid (3)); | |
522 | and the name taken from the record. | |
523 | Let | |
524 | .I user | |
525 | be the user name so determined, if any. | |
526 | .hP 4 | |
527 | If no user name could be determined, then skip this step. | |
528 | If the environment variable | |
529 | .B TMPDIR | |
530 | is set, then let | |
531 | .I tmp | |
532 | be its value; | |
533 | otherwise, let | |
534 | .I tmp | |
535 | be | |
536 | .BR /tmp . | |
537 | If | |
538 | .IB tmp/ with-authinfo-kludge- user | |
539 | exists, | |
540 | is a directory (and not a symbolic link), | |
541 | is owned by the current effective uid, | |
542 | and has no permissions for group or others; | |
543 | or if it does not exist but can be created with the above properties; | |
544 | then it is used as the runtime directory. | |
545 | .hP 5. | |
546 | The user's home directory is determined, as follows. | |
547 | If the environment variable | |
548 | .B HOME | |
549 | is set, then its value is used. | |
550 | Otherwise, the current effective uid is looked up | |
551 | in the password database | |
552 | (using | |
553 | .BR getpwuid (3)); | |
554 | and the home directory taken from the record. | |
555 | Let | |
556 | .I home | |
557 | be the home directory so determined, if any. | |
558 | .hP 6. | |
559 | A `cache home' directory is determined, as follows. | |
560 | If the environment variable | |
561 | .B XDG_CACHE_HOME | |
562 | is set, then its value is used. | |
563 | Otherwise, the configuration home is | |
564 | .IB home /.cache \fR; | |
565 | a fatal error is reported at this point | |
566 | if no home directory was determined. | |
567 | Let | |
568 | .I cache-home | |
569 | denote the cache home directory so determined. | |
570 | If the cache home directory does not exist, | |
571 | then it is created with mode 0777 (as modified by the umask). | |
572 | .hP 7. | |
573 | Let | |
574 | .I hostname | |
575 | be the local machine's hostname, | |
576 | as reported by | |
577 | .BR gethostname (2). | |
578 | If | |
579 | .IB cache-home /with-authinfo-kludge. hostname | |
580 | does not exist, | |
581 | then it is created as a directory, | |
582 | with mode 0700 (and modified by the umask). | |
583 | This directory is then used as the runtime directory. | |
584 | (If it exists, but is not in fact a directory, | |
585 | then later operations will fail.) | |
586 | .PP | |
587 | The runtime directory contains a number of other directories, | |
588 | named | |
589 | .IR tag . pid \fR. | |
590 | Each such directory corresponds to a running | |
591 | (or failed) | |
592 | instance of | |
593 | .BR with-authinfo-kludge ; | |
594 | the | |
595 | .I pid | |
596 | is its process-id (possibly useful for diagnostic purposes), | |
597 | and the | |
598 | .I tag | |
599 | is the tag summarizing its purpose | |
600 | (as determined in step 5 of the procedure | |
601 | for finding a configuration file). | |
602 | .PP | |
603 | The contents of the instance directory are as follows. | |
604 | .TP | |
605 | .B client.pid | |
606 | The process-id of the client command run by | |
607 | .BR with-authinfo-kludge . | |
608 | .TP | |
609 | .B lock | |
610 | An empty file. | |
611 | A | |
612 | running | |
613 | .B with-authinfo-kludge | |
614 | process holds a lock on this file. | |
615 | It is used simply to tell other processes that | |
616 | the directory is still in use and shouldn't be cleaned up. | |
617 | .TP | |
618 | .B noip/ | |
619 | A directory containing Unix-domain sockets, | |
620 | maintained by the | |
621 | .B noip | |
622 | library. | |
623 | .TP | |
624 | .B ssh.pid | |
625 | The process-id of the SSH process started to satisfy a | |
626 | .B via | |
627 | server parameter. | |
628 | . | |
629 | .\"-------------------------------------------------------------------------- | |
630 | .SH BUGS | |
631 | . | |
632 | The program is probably too complicated for many uses, | |
633 | but the author finds the various bells and whistles useful. | |
634 | .PP | |
635 | There isn't a good way to get two or more NNTP clients | |
636 | to share the same proxy machinery. | |
637 | This is somewhat wasteful. | |
638 | Fixing this would necessitate some other way of | |
639 | orchestrating the setup and teardown of runtime directories. | |
640 | .PP | |
641 | Maybe there ought to be a way to set | |
642 | a separate runtime directory for each server. | |
643 | But, really, I had to draw a line somewhere. | |
644 | . | |
645 | .\"-------------------------------------------------------------------------- | |
646 | .SH SEE ALSO | |
647 | . | |
648 | .BR authinfo-kludge (1), | |
649 | .BR noip (1). | |
650 | .PP | |
651 | S. Barber, | |
652 | .IR "RFC2980, Common NNTP Extensions", | |
653 | .if !t \{\ | |
654 | .br | |
655 | \h'5m'\c | |
656 | .\} | |
657 | .BR "https://www.ietf.org/rfc/rfc2980.txt" . | |
658 | . | |
659 | .SH AUTHOR | |
660 | Mark Wooding, | |
661 | <mdw@distorted.org.uk> | |
662 | . | |
663 | .\"----- That's all, folks -------------------------------------------------- |