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 it 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 implemented 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
 238 .IR command 's
 239 name containing an
 240 .RB ` = '
 241 or, less plausibly, beginning with
 242 .RB ` + ',
 243 an argument consisting of a
 244 .RB ` + '
 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.
 248 If there is a
 249 .RB ` + '
 250 marker, but no server configurations,
 251 then the configuration file is read,
 252 or the default configuration is used,
 253 as usual.
 254 .
 255 .SS "Configuration file"
 256 The
 257 .B with-authinfo-kludge
 258 program reads configuration from a standard-ish
 259 .RB ` .ini '-format
 260 file.
 261 The file consists of parameter settings of the form
 262 .IP
 263 .I param
 264 .B =
 265 .I value
 266 .PP
 267 divided into sections by headers of the form
 268 .IP
 269 .BI [ name ]
 270 .PP
 271 Whitespace around the
 272 .IR name ,
 273 .I param
 274 and
 275 .I value
 276 strings is discarded.
 277 A section
 278 .I name
 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.
 282 .PP
 283 The file may also contain blank lines,
 284 and comment lines whose first non-whitespace character is either
 285 .RB ` # '
 286 or
 287 .RB ` ; '.
 288 All such lines are ignored.
 289 .PP
 290 Parameter settings apply to the section named in the most recent
 291 setion header.
 292 Settings appearing before the first section header apply to
 293 the special section named
 294 .BR @GLOBAL ,
 295 just as if a line
 296 .IP
 297 .B [@GLOBAL]
 298 .PP
 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;
 302 in this case,
 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,
 305 in the same order.
 306 If the same parameter is assigned more than once,
 307 then only the
 308 .I last
 309 assignment has any effect.
 310 .PP
 311 With the exception of the
 312 .B @GLOBAL
 313 section,
 314 each section header should name an NNTP server.
 315 .PP
 316 The following server parameters are recognized.
 317 .TP
 318 .BI local= host\fR[ : port \fR]
 319 Sets the NNTP server address which the newsreader command
 320 expects to connect to.
 321 This does
 322 .I not
 323 have to be an address local to the machine on which
 324 .B with-authinfo-kludge
 325 runs.
 326 It defaults to the
 327 .I server
 328 name from the section heading
 329 (which must therefore be in the appropriate format),
 330 and may be equal to the
 331 .I remote
 332 address (below) without causing difficulty.
 333 Note that
 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,
 338 e.g., by setting the
 339 .B NNTPSERVER
 340 environment variable appropriately.
 341 .TP
 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
 346 .B NNTPAUTH
 347 environment variable.
 348 .TP
 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.
 353 It defaults to the
 354 .I server
 355 name from the section heading
 356 (which must therefore be in the appropriate format).
 357 .TP
 358 .BI sshbind= host\fR[ : port\fR]
 359 Change the address and port number
 360 of the local end of the SSH tunnel
 361 set up by the
 362 .B via
 363 parameter.
 364 The default is to use
 365 .\" FIXME Fuck you openssh
 366 127.1.0.1:119.
 367 It is
 368 .I not
 369 a problem for multiple servers to use the same address:
 370 .B with-authinfo-kludge
 371 uses the
 372 .BR noip (1)
 373 library to keep them
 374 separate.
 375 .TP
 376 .BI via= gateway
 377 Use SSH connection forwarding to reach the server.
 378 The
 379 .I gateway
 380 is passed to
 381 .BR ssh (1)
 382 as its hostname parameter,
 383 so may be a hostname or IP address,
 384 possibly prefixed by
 385 .IB user @
 386 to choose a different login name;
 387 or it may name a
 388 .BR ssh_config (1)
 389 stanza providing detailed configuration.
 390 Note that the local end of the tunnel will
 391 .I not
 392 be exposed to other users of the local machine,
 393 since this instance of SSH is run under the control of
 394 .BR noip (1).
 395 .PP
 396 The various parameters which take network addresses
 397 accept a common syntax:
 398 .IP
 399 .IR host \c
 400 .RB [ : \c
 401 .IR port ]
 402 .PP
 403 The
 404 .I host
 405 may be a hostname;
 406 an IPv4 address in dotted-quad notation; or
 407 an IPv6 address in hex-and-colons notation,
 408 which must contain at least
 409 .I two
 410 colons to be valid.
 411 Raw IP addresses may be surrounded by square brackets;
 412 this is necessary to disambiguate a trailing
 413 .BI : port
 414 following an IPv6 address because the IPv6 address syntax is stupid.
 415 .PP
 416 The
 417 .B @GLOBAL
 418 section may set the following parameters.
 419 .TP
 420 .BI rundir= dir
 421 Set the runtime directory to be
 422 .IR dir .
 423 This directory (but not its parent directories)
 424 will be created automatically if necessary.
 425 The default runtime directory is chosen in a complicated way;
 426 see below.
 427 .PP
 428 The configuration file is found as follows.
 429 .hP 1.
 430 If server configurations are provided on the command line,
 431 then they are used instead of any configuration file.
 432 .hP 2.
 433 If a
 434 .B \-f
 435 option is given, then it is read as a configuration file.
 436 A fatal error is reported if the file does not exist,
 437 or cannot be read for some other reason.
 438 .hP 3.
 439 The user's home directory is determined, as follows.
 440 If the environment variable
 441 .B HOME
 442 is set, then its value is used.
 443 Let
 444 .I home
 445 be the home directory so determined, if any.
 446 .hP 4.
 447 A `configuration home' directory is determined, as follows.
 448 If the environment variable
 449 .B XDG_CONFIG_HOME
 450 is set, then its value is used.
 451 Otherwise, the configuration home is
 452 .IB home /.config \fR;
 453 a fatal error is reported at this point
 454 if no home directory was determined.
 455 Let
 456 .I config-home
 457 denote the configuration home directory so determined.
 458 .\" FIXME XDG_CONFIG_DIRS too now
 459 .hP 5.
 460 A `tag' is chosen, as follows.
 461 If the
 462 .B \-t
 463 option is given, then its value is used;
 464 otherwise the tag is the basename of the
 465 .I command
 466 (i.e., the part following the last
 467 .RB ` / ',
 468 if any).
 469 Let
 470 .I tag
 471 denote the tag so chosen.
 472 .hP 6.
 473 If
 474 .IB config-home /with-authinfo-kludge/ tag .conf
 475 exists, then it is read as a configuration file.
 476 (If it can't be read, then a fatal error is reported.)
 477 .hP 7.
 478 If
 479 .IB config-home /with-authinfo-kludge/@default.conf
 480 exists, then it is read as a configuration file.
 481 (If it can't be read, then a fatal error is reported.)
 482 .hP 8.
 483 No configuration file could be found,
 484 so a default configuration is constructed, as follows.
 485 Let
 486 .I nntp-server
 487 be the value of the
 488 .B NNTPSERVER
 489 environment variable;
 490 if it is not set, then a fatal error is reported.
 491 The default configuration is as follows.
 492 .RS
 493 .IP
 494 .BI [ nntp-server ]
 495 .RE
 496 .
 497 .SS "The runtime directory"
 498 (This section is technical, and can safely be skipped by most users.
 499 It may be useful to know this stuff if
 500 .B with-authinfo-kludge
 501 is behaving confusingly and you're trying to understand why.)
 502 .PP
 503 The runtime directory is chosen as follows.
 504 .hP 1.
 505 If the
 506 .B \-d
 507 option is present, then its value is used.
 508 Otherwise, if the configuration file specifies
 509 a value for the global
 510 .B rundir
 511 parameter then that it used.
 512 .hP 2.
 513 If the environment variable
 514 .B XDG_RUNTIME_DIR
 515 is set, then let
 516 .I run
 517 denote its value;
 518 then
 519 .IB run /with-authinfo-kludge
 520 is used as the runtime directory.
 521 .hP 3
 522 If the environment variable
 523 .B TMPDIR
 524 is set, then let
 525 .I tmp
 526 be its value;
 527 otherwise, let
 528 .I tmp
 529 be
 530 .BR /tmp .
 531 Let
 532 .I uid
 533 be the current effective uid, in decimal,
 534 without leading zeroes
 535 (if the superuser is foolish enough to run this program then
 536 .I uid
 537 is
 538 .BR 0 ).
 539 If
 540 .IB tmp/ with-authinfo-kludge- uid
 541 exists,
 542 is a directory (and not a symbolic link),
 543 is owned by the current effective uid,
 544 and has no permissions for group or others;
 545 or if it does not exist but can be created with the above properties;
 546 then it is used as the runtime directory.
 547 .hP 4.
 548 The user's home directory is determined, as follows.
 549 If the environment variable
 550 .B HOME
 551 is set, then its value is used.
 552 Let
 553 .I home
 554 be the home directory so determined, if any.
 555 .hP 5.
 556 A `cache home' directory is determined, as follows.
 557 If the environment variable
 558 .B XDG_CACHE_HOME
 559 is set, then its value is used.
 560 Otherwise, the configuration home is
 561 .IB home /.cache \fR;
 562 a fatal error is reported at this point
 563 if no home directory was determined.
 564 Let
 565 .I cache-home
 566 denote the cache home directory so determined.
 567 If the cache home directory does not exist,
 568 then it is created with mode 0777 (as modified by the umask).
 569 .hP 6.
 570 Let
 571 .I hostname
 572 be the local machine's hostname,
 573 as reported by
 574 .BR gethostname (2).
 575 Then
 576 .IB cache-home /with-authinfo-kludge. hostname
 577 is used as the runtime directory.
 578 .PP
 579 If the directory chosen by the above procedure does not exist,
 580 then it is created as a directory,
 581 with mode 0700 (and modified by the umask).
 582 (If it exists, but is not in fact a directory,
 583 then later operations will fail.)
 584 .PP
 585 The runtime directory contains a number of other directories,
 586 named
 587 .\" FIXME junk, new, naming
 588 .\" session dirs now entirely different
 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 .
 641 .\"--------------------------------------------------------------------------
 642 .SH SEE ALSO
 643 .
 644 .BR authinfo-kludge (1),
 645 .BR noip (1).
 646 .PP
 647 S. Barber,
 648 .IR "RFC2980, Common NNTP Extensions",
 649 .if !t \{\
 650 .br
 651 \h'5m'\c
 652 .\}
 653 .BR "https://www.ietf.org/rfc/rfc2980.txt" .
 654 .
 655 .SH AUTHOR
 656 Mark Wooding,
 657 <mdw@distorted.org.uk>
 658 .
 659 .\"----- That's all, folks --------------------------------------------------