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 | |
363 | 127.1.0.1:119. | |
364 | It is | |
365 | .I not | |
366 | a problem for multiple servers to use the same address: | |
367 | .B with-authinfo-kludge | |
368 | uses the | |
369 | .BR noip (1) | |
370 | library to keep them | |
371 | separate. | |
372 | .TP | |
373 | .BI via= gateway | |
374 | Use SSH connection forwarding to reach the server. | |
375 | The | |
376 | .I gateway | |
377 | is passed to | |
378 | .BR ssh (1) | |
379 | as its hostname parameter, | |
380 | so may be a hostname or IP address, | |
381 | possibly prefixed by | |
382 | .IB user @ | |
383 | to choose a different login name; | |
384 | or it may name a | |
385 | .BR ssh_config (1) | |
386 | stanza providing detailed configuration. | |
387 | Note that the local end of the tunnel will | |
388 | .I not | |
389 | be exposed to other users of the local machine, | |
390 | since this instance of SSH is run under the control of | |
391 | .BR noip (1). | |
392 | .PP | |
393 | The various parameters which take network addresses | |
394 | accept a common syntax: | |
395 | .IP | |
396 | .IR host \c | |
397 | .RB [ : \c | |
398 | .IR port ] | |
399 | .PP | |
400 | The | |
401 | .I host | |
402 | may be a hostname; | |
403 | an IPv4 address in dotted-quad notation; or | |
404 | an IPv6 address in hex-and-colons notation, | |
405 | which must contain at least | |
406 | .I two | |
407 | colons to be valid. | |
408 | Raw IP addresses may be surrounded by square brackets; | |
409 | this is necessary to disambiguate a trailing | |
410 | .BI : port | |
411 | following an IPv6 address because the IPv6 address syntax is stupid. | |
412 | .PP | |
413 | The | |
414 | .B @GLOBAL | |
415 | section may set the following parameters. | |
416 | .TP | |
417 | .BI rundir= dir | |
418 | Set the runtime directory to be | |
419 | .IR dir . | |
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; | |
423 | see below. | |
424 | .PP | |
425 | The configuration file is found as follows. | |
426 | .hP 1. | |
427 | If server configurations are provided on the command line, | |
428 | then they are used instead of any configuration file. | |
429 | .hP 2. | |
430 | If a | |
431 | .B \-f | |
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. | |
435 | .hP 3. | |
436 | The user's home directory is determined, as follows. | |
437 | If the environment variable | |
438 | .B HOME | |
439 | is set, then its value is used. | |
b3370918 MW |
440 | Let |
441 | .I home | |
442 | be the home directory so determined, if any. | |
443 | .hP 4. | |
444 | A `configuration home' directory is determined, as follows. | |
445 | If the environment variable | |
446 | .B XDG_CONFIG_HOME | |
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. | |
452 | Let | |
453 | .I config-home | |
454 | denote the configuration home directory so determined. | |
455 | .hP 5. | |
456 | A `tag' is chosen, as follows. | |
457 | If the | |
458 | .B \-t | |
459 | option is given, then its value is used; | |
460 | otherwise the tag is the basename of the | |
461 | .I command | |
462 | (i.e., the part following the last | |
463 | .RB ` / ', | |
464 | if any). | |
465 | Let | |
466 | .I tag | |
467 | denote the tag so chosen. | |
468 | .hP 6. | |
469 | If | |
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.) | |
473 | .hP 7. | |
474 | If | |
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.) | |
478 | .hP 8. | |
479 | No configuration file could be found, | |
480 | so a default configuration is constructed, as follows. | |
481 | Let | |
482 | .I nntp-server | |
afaf8da0 | 483 | be the value of the |
b3370918 MW |
484 | .B NNTPSERVER |
485 | environment variable; | |
486 | if it is not set, then a fatal error is reported. | |
487 | The default configuration is as follows. | |
488 | .RS | |
489 | .IP | |
490 | .BI [ nntp-server ] | |
491 | .RE | |
492 | . | |
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.) | |
498 | .PP | |
499 | The runtime directory is chosen as follows. | |
500 | .hP 1. | |
501 | If the | |
502 | .B \-d | |
503 | option is present, then its value is used. | |
e365c82b MW |
504 | Otherwise, if the configuration file specifies |
505 | a value for the global | |
506 | .B rundir | |
507 | parameter then that it used. | |
b3370918 MW |
508 | .hP 2. |
509 | If the environment variable | |
510 | .B XDG_RUNTIME_DIR | |
511 | is set, then let | |
512 | .I run | |
513 | denote its value; | |
514 | then | |
515 | .IB run /with-authinfo-kludge | |
516 | is used as the runtime directory. | |
d9c763dc | 517 | .hP 3 |
b3370918 MW |
518 | If the environment variable |
519 | .B TMPDIR | |
520 | is set, then let | |
521 | .I tmp | |
522 | be its value; | |
523 | otherwise, let | |
524 | .I tmp | |
525 | be | |
526 | .BR /tmp . | |
d9c763dc MW |
527 | Let |
528 | .I uid | |
529 | be the current effective uid, in decimal, | |
530 | without leading zeroes | |
531 | (if the superuser is foolish enough to run this program then | |
532 | .I uid | |
533 | is | |
534 | .BR 0 ). | |
b3370918 | 535 | If |
d9c763dc | 536 | .IB tmp/ with-authinfo-kludge- uid |
b3370918 MW |
537 | exists, |
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. | |
d9c763dc | 543 | .hP 4. |
b3370918 MW |
544 | The user's home directory is determined, as follows. |
545 | If the environment variable | |
546 | .B HOME | |
547 | is set, then its value is used. | |
b3370918 MW |
548 | Let |
549 | .I home | |
550 | be the home directory so determined, if any. | |
d9c763dc | 551 | .hP 5. |
b3370918 MW |
552 | A `cache home' directory is determined, as follows. |
553 | If the environment variable | |
554 | .B XDG_CACHE_HOME | |
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. | |
560 | Let | |
561 | .I cache-home | |
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). | |
d9c763dc | 565 | .hP 6. |
b3370918 MW |
566 | Let |
567 | .I hostname | |
568 | be the local machine's hostname, | |
569 | as reported by | |
570 | .BR gethostname (2). | |
e365c82b | 571 | Then |
b3370918 | 572 | .IB cache-home /with-authinfo-kludge. hostname |
e365c82b MW |
573 | is used as the runtime directory. |
574 | .PP | |
575 | If the directory chosen by the above procedure does not exist, | |
b3370918 MW |
576 | then it is created as a directory, |
577 | with mode 0700 (and modified by the umask). | |
b3370918 MW |
578 | (If it exists, but is not in fact a directory, |
579 | then later operations will fail.) | |
580 | .PP | |
581 | The runtime directory contains a number of other directories, | |
582 | named | |
583 | .IR tag . pid \fR. | |
584 | Each such directory corresponds to a running | |
585 | (or failed) | |
586 | instance of | |
587 | .BR with-authinfo-kludge ; | |
588 | the | |
589 | .I pid | |
590 | is its process-id (possibly useful for diagnostic purposes), | |
591 | and the | |
592 | .I tag | |
593 | is the tag summarizing its purpose | |
594 | (as determined in step 5 of the procedure | |
595 | for finding a configuration file). | |
596 | .PP | |
597 | The contents of the instance directory are as follows. | |
598 | .TP | |
599 | .B client.pid | |
600 | The process-id of the client command run by | |
601 | .BR with-authinfo-kludge . | |
602 | .TP | |
603 | .B lock | |
604 | An empty file. | |
605 | A | |
606 | running | |
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. | |
611 | .TP | |
612 | .B noip/ | |
613 | A directory containing Unix-domain sockets, | |
614 | maintained by the | |
615 | .B noip | |
616 | library. | |
617 | .TP | |
618 | .B ssh.pid | |
619 | The process-id of the SSH process started to satisfy a | |
620 | .B via | |
621 | server parameter. | |
622 | . | |
623 | .\"-------------------------------------------------------------------------- | |
624 | .SH BUGS | |
625 | . | |
626 | The program is probably too complicated for many uses, | |
627 | but the author finds the various bells and whistles useful. | |
628 | .PP | |
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. | |
b3370918 MW |
634 | . |
635 | .\"-------------------------------------------------------------------------- | |
636 | .SH SEE ALSO | |
637 | . | |
638 | .BR authinfo-kludge (1), | |
639 | .BR noip (1). | |
640 | .PP | |
641 | S. Barber, | |
642 | .IR "RFC2980, Common NNTP Extensions", | |
643 | .if !t \{\ | |
644 | .br | |
645 | \h'5m'\c | |
646 | .\} | |
647 | .BR "https://www.ietf.org/rfc/rfc2980.txt" . | |
648 | . | |
649 | .SH AUTHOR | |
650 | Mark Wooding, | |
651 | <mdw@distorted.org.uk> | |
652 | . | |
653 | .\"----- That's all, folks -------------------------------------------------- |