mdw@git.distorted.org.uk Git - with-authinfo-kludge/blob - with-authinfo-kludge.1

   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 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.
 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 .\" FIXME Fuck you openssh
 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.
 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.
 456 .\" FIXME XDG_CONFIG_DIRS too now
 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
 485 be the value of the
 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.
 506 Otherwise, if the configuration file specifies
 507 a value for the global
 508 .B rundir
 509 parameter then that it used.
 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.
 519 .hP 3
 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 .
 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 ).
 537 If
 538 .IB tmp/ with-authinfo-kludge- uid
 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 4.
 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 Let
 551 .I home
 552 be the home directory so determined, if any.
 553 .hP 5.
 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).
 567 .hP 6.
 568 Let
 569 .I hostname
 570 be the local machine's hostname,
 571 as reported by
 572 .BR gethostname (2).
 573 Then
 574 .IB cache-home /with-authinfo-kludge. hostname
 575 is used as the runtime directory.
 576 .PP
 577 If the directory chosen by the above procedure does not exist,
 578 then it is created as a directory,
 579 with mode 0700 (and modified by the umask).
 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
 585 .\" FIXME junk, new, naming
 586 .\" session dirs now entirely different
 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.
 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 --------------------------------------------------