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. | |
afaf8da0 | 213 | A server configuration starts with |
b3370918 MW |
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. | |
838ff5e9 MW |
331 | Note that |
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, | |
336 | e.g., by setting the | |
337 | .B NNTPSERVER | |
338 | environment variable appropriately. | |
b3370918 MW |
339 | .TP |
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 | |
344 | .B NNTPAUTH | |
345 | environment variable. | |
346 | .TP | |
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. | |
351 | It defaults to the | |
352 | .I server | |
353 | name from the section heading | |
354 | (which must therefore be in the appropriate format). | |
355 | .TP | |
356 | .BI sshbind= host\fR[ : port\fR] | |
357 | Change the address and port number | |
358 | of the local end of the SSH tunnel | |
359 | set up by the | |
360 | .B via | |
361 | parameter. | |
362 | The default is to use | |
e8e64c07 | 363 | .\" FIXME Fuck you openssh |
b3370918 MW |
364 | 127.1.0.1:119. |
365 | It is | |
366 | .I not | |
367 | a problem for multiple servers to use the same address: | |
368 | .B with-authinfo-kludge | |
369 | uses the | |
370 | .BR noip (1) | |
371 | library to keep them | |
372 | separate. | |
373 | .TP | |
374 | .BI via= gateway | |
375 | Use SSH connection forwarding to reach the server. | |
376 | The | |
377 | .I gateway | |
378 | is passed to | |
379 | .BR ssh (1) | |
380 | as its hostname parameter, | |
381 | so may be a hostname or IP address, | |
382 | possibly prefixed by | |
383 | .IB user @ | |
384 | to choose a different login name; | |
385 | or it may name a | |
386 | .BR ssh_config (1) | |
387 | stanza providing detailed configuration. | |
388 | Note that the local end of the tunnel will | |
389 | .I not | |
390 | be exposed to other users of the local machine, | |
391 | since this instance of SSH is run under the control of | |
392 | .BR noip (1). | |
393 | .PP | |
394 | The various parameters which take network addresses | |
395 | accept a common syntax: | |
396 | .IP | |
397 | .IR host \c | |
398 | .RB [ : \c | |
399 | .IR port ] | |
400 | .PP | |
401 | The | |
402 | .I host | |
403 | may be a hostname; | |
404 | an IPv4 address in dotted-quad notation; or | |
405 | an IPv6 address in hex-and-colons notation, | |
406 | which must contain at least | |
407 | .I two | |
408 | colons to be valid. | |
409 | Raw IP addresses may be surrounded by square brackets; | |
410 | this is necessary to disambiguate a trailing | |
411 | .BI : port | |
412 | following an IPv6 address because the IPv6 address syntax is stupid. | |
413 | .PP | |
414 | The | |
415 | .B @GLOBAL | |
416 | section may set the following parameters. | |
417 | .TP | |
418 | .BI rundir= dir | |
419 | Set the runtime directory to be | |
420 | .IR dir . | |
421 | This directory (but not its parent directories) | |
422 | will be created automatically if necessary. | |
423 | The default runtime directory is chosen in a complicated way; | |
424 | see below. | |
425 | .PP | |
426 | The configuration file is found as follows. | |
427 | .hP 1. | |
428 | If server configurations are provided on the command line, | |
429 | then they are used instead of any configuration file. | |
430 | .hP 2. | |
431 | If a | |
432 | .B \-f | |
433 | option is given, then it is read as a configuration file. | |
434 | A fatal error is reported if the file does not exist, | |
435 | or cannot be read for some other reason. | |
436 | .hP 3. | |
437 | The user's home directory is determined, as follows. | |
438 | If the environment variable | |
439 | .B HOME | |
440 | is set, then its value is used. | |
b3370918 MW |
441 | Let |
442 | .I home | |
443 | be the home directory so determined, if any. | |
444 | .hP 4. | |
445 | A `configuration home' directory is determined, as follows. | |
446 | If the environment variable | |
447 | .B XDG_CONFIG_HOME | |
448 | is set, then its value is used. | |
449 | Otherwise, the configuration home is | |
450 | .IB home /.config \fR; | |
451 | a fatal error is reported at this point | |
452 | if no home directory was determined. | |
453 | Let | |
454 | .I config-home | |
455 | denote the configuration home directory so determined. | |
e8e64c07 | 456 | .\" FIXME XDG_CONFIG_DIRS too now |
b3370918 MW |
457 | .hP 5. |
458 | A `tag' is chosen, as follows. | |
459 | If the | |
460 | .B \-t | |
461 | option is given, then its value is used; | |
462 | otherwise the tag is the basename of the | |
463 | .I command | |
464 | (i.e., the part following the last | |
465 | .RB ` / ', | |
466 | if any). | |
467 | Let | |
468 | .I tag | |
469 | denote the tag so chosen. | |
470 | .hP 6. | |
471 | If | |
472 | .IB config-home /with-authinfo-kludge/ tag .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 7. | |
476 | If | |
477 | .IB config-home /with-authinfo-kludge/@default.conf | |
478 | exists, then it is read as a configuration file. | |
479 | (If it can't be read, then a fatal error is reported.) | |
480 | .hP 8. | |
481 | No configuration file could be found, | |
482 | so a default configuration is constructed, as follows. | |
483 | Let | |
484 | .I nntp-server | |
afaf8da0 | 485 | be the value of the |
b3370918 MW |
486 | .B NNTPSERVER |
487 | environment variable; | |
488 | if it is not set, then a fatal error is reported. | |
489 | The default configuration is as follows. | |
490 | .RS | |
491 | .IP | |
492 | .BI [ nntp-server ] | |
493 | .RE | |
494 | . | |
495 | .SS "The runtime directory" | |
496 | (This section is technical, and can safely be skipped by most users. | |
497 | It may be useful to know this stuff if | |
498 | .B with-authinfo-kludge | |
499 | is behaving confusingly and you're trying to understand why.) | |
500 | .PP | |
501 | The runtime directory is chosen as follows. | |
502 | .hP 1. | |
503 | If the | |
504 | .B \-d | |
505 | option is present, then its value is used. | |
e365c82b MW |
506 | Otherwise, if the configuration file specifies |
507 | a value for the global | |
508 | .B rundir | |
509 | parameter then that it used. | |
b3370918 MW |
510 | .hP 2. |
511 | If the environment variable | |
512 | .B XDG_RUNTIME_DIR | |
513 | is set, then let | |
514 | .I run | |
515 | denote its value; | |
516 | then | |
517 | .IB run /with-authinfo-kludge | |
518 | is used as the runtime directory. | |
d9c763dc | 519 | .hP 3 |
b3370918 MW |
520 | If the environment variable |
521 | .B TMPDIR | |
522 | is set, then let | |
523 | .I tmp | |
524 | be its value; | |
525 | otherwise, let | |
526 | .I tmp | |
527 | be | |
528 | .BR /tmp . | |
d9c763dc MW |
529 | Let |
530 | .I uid | |
531 | be the current effective uid, in decimal, | |
532 | without leading zeroes | |
533 | (if the superuser is foolish enough to run this program then | |
534 | .I uid | |
535 | is | |
536 | .BR 0 ). | |
b3370918 | 537 | If |
d9c763dc | 538 | .IB tmp/ with-authinfo-kludge- uid |
b3370918 MW |
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. | |
d9c763dc | 545 | .hP 4. |
b3370918 MW |
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. | |
b3370918 MW |
550 | Let |
551 | .I home | |
552 | be the home directory so determined, if any. | |
d9c763dc | 553 | .hP 5. |
b3370918 MW |
554 | A `cache home' directory is determined, as follows. |
555 | If the environment variable | |
556 | .B XDG_CACHE_HOME | |
557 | is set, then its value is used. | |
558 | Otherwise, the configuration home is | |
559 | .IB home /.cache \fR; | |
560 | a fatal error is reported at this point | |
561 | if no home directory was determined. | |
562 | Let | |
563 | .I cache-home | |
564 | denote the cache home directory so determined. | |
565 | If the cache home directory does not exist, | |
566 | then it is created with mode 0777 (as modified by the umask). | |
d9c763dc | 567 | .hP 6. |
b3370918 MW |
568 | Let |
569 | .I hostname | |
570 | be the local machine's hostname, | |
571 | as reported by | |
572 | .BR gethostname (2). | |
e365c82b | 573 | Then |
b3370918 | 574 | .IB cache-home /with-authinfo-kludge. hostname |
e365c82b MW |
575 | is used as the runtime directory. |
576 | .PP | |
577 | If the directory chosen by the above procedure does not exist, | |
b3370918 MW |
578 | then it is created as a directory, |
579 | with mode 0700 (and modified by the umask). | |
b3370918 MW |
580 | (If it exists, but is not in fact a directory, |
581 | then later operations will fail.) | |
582 | .PP | |
583 | The runtime directory contains a number of other directories, | |
584 | named | |
e8e64c07 MW |
585 | .\" FIXME junk, new, naming |
586 | .\" session dirs now entirely different | |
b3370918 MW |
587 | .IR tag . pid \fR. |
588 | Each such directory corresponds to a running | |
589 | (or failed) | |
590 | instance of | |
591 | .BR with-authinfo-kludge ; | |
592 | the | |
593 | .I pid | |
594 | is its process-id (possibly useful for diagnostic purposes), | |
595 | and the | |
596 | .I tag | |
597 | is the tag summarizing its purpose | |
598 | (as determined in step 5 of the procedure | |
599 | for finding a configuration file). | |
600 | .PP | |
601 | The contents of the instance directory are as follows. | |
602 | .TP | |
603 | .B client.pid | |
604 | The process-id of the client command run by | |
605 | .BR with-authinfo-kludge . | |
606 | .TP | |
607 | .B lock | |
608 | An empty file. | |
609 | A | |
610 | running | |
611 | .B with-authinfo-kludge | |
612 | process holds a lock on this file. | |
613 | It is used simply to tell other processes that | |
614 | the directory is still in use and shouldn't be cleaned up. | |
615 | .TP | |
616 | .B noip/ | |
617 | A directory containing Unix-domain sockets, | |
618 | maintained by the | |
619 | .B noip | |
620 | library. | |
621 | .TP | |
622 | .B ssh.pid | |
623 | The process-id of the SSH process started to satisfy a | |
624 | .B via | |
625 | server parameter. | |
626 | . | |
627 | .\"-------------------------------------------------------------------------- | |
628 | .SH BUGS | |
629 | . | |
630 | The program is probably too complicated for many uses, | |
631 | but the author finds the various bells and whistles useful. | |
632 | .PP | |
633 | There isn't a good way to get two or more NNTP clients | |
634 | to share the same proxy machinery. | |
635 | This is somewhat wasteful. | |
636 | Fixing this would necessitate some other way of | |
637 | orchestrating the setup and teardown of runtime directories. | |
b3370918 MW |
638 | . |
639 | .\"-------------------------------------------------------------------------- | |
640 | .SH SEE ALSO | |
641 | . | |
642 | .BR authinfo-kludge (1), | |
643 | .BR noip (1). | |
644 | .PP | |
645 | S. Barber, | |
646 | .IR "RFC2980, Common NNTP Extensions", | |
647 | .if !t \{\ | |
648 | .br | |
649 | \h'5m'\c | |
650 | .\} | |
651 | .BR "https://www.ietf.org/rfc/rfc2980.txt" . | |
652 | . | |
653 | .SH AUTHOR | |
654 | Mark Wooding, | |
655 | <mdw@distorted.org.uk> | |
656 | . | |
657 | .\"----- That's all, folks -------------------------------------------------- |