From 49ae1f48b931ee42a4c3986093d1728357738cde Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Mon, 4 Jun 2018 00:23:59 +0100 Subject: [PATCH] with-authinfo-kludge.1: Fix the various lies in the manual. --- with-authinfo-kludge.1 | 157 +++++++++++++++++++++++++++++++++++-------------- 1 file changed, 114 insertions(+), 43 deletions(-) diff --git a/with-authinfo-kludge.1 b/with-authinfo-kludge.1 index 5a67856..da2d0e6 100644 --- a/with-authinfo-kludge.1 +++ b/with-authinfo-kludge.1 @@ -362,8 +362,10 @@ set up by the .B via parameter. The default is to use -.\" FIXME Fuck you openssh -127.1.0.1:119. +127.1.0.1:1119, +because OpenSSH refuses to try to listen on low-numbered ports +rather than trying it and seeing whether it would work +(which it would, in this case). It is .I not a problem for multiple servers to use the same address: @@ -436,26 +438,31 @@ option is given, then it is read as a configuration file. A fatal error is reported if the file does not exist, or cannot be read for some other reason. .hP 3. -The user's home directory is determined, as follows. -If the environment variable -.B HOME -is set, then its value is used. Let .I home -be the home directory so determined, if any. +be the value of the environment variable +.BR HOME ; +if this variable is not set, then +.I home +is not defined. .hP 4. -A `configuration home' directory is determined, as follows. +A `configuration path' is built, as follows. If the environment variable .B XDG_CONFIG_HOME -is set, then its value is used. -Otherwise, the configuration home is +is set, then its value is the first entry in the path; +otherwise the first entry is .IB home /.config \fR; a fatal error is reported at this point if no home directory was determined. -Let -.I config-home -denote the configuration home directory so determined. -.\" FIXME XDG_CONFIG_DIRS too now +If the environment variable +.B XDG_CONFIG_DIRS +is defined, +then the +.RB ` : '-separated +entries in its value are appended to the path; +otherwise, the single entry +.B /etc/xdg +is appended. .hP 5. A `tag' is chosen, as follows. If the @@ -470,14 +477,20 @@ Let .I tag denote the tag so chosen. .hP 6. -If -.IB config-home /with-authinfo-kludge/ tag .conf -exists, then it is read as a configuration file. +A search is made for a file +.IB dir /with-authinfo-kludge/ tag .conf +for each directory +.I dir +in the configuration path established in step 4, +in order. +If such a file exists exists, +then it is read as a configuration file. (If it can't be read, then a fatal error is reported.) .hP 7. -If -.IB config-home /with-authinfo-kludge/@default.conf -exists, then it is read as a configuration file. +A similar search is made for +.IB dir /with-authinfo-kludge/@default.conf \fR. +If such a file exists, +then it is read as a configuration file. (If it can't be read, then a fatal error is reported.) .hP 8. No configuration file could be found, @@ -545,13 +558,13 @@ and has no permissions for group or others; or if it does not exist but can be created with the above properties; then it is used as the runtime directory. .hP 4. -The user's home directory is determined, as follows. -If the environment variable -.B HOME -is set, then its value is used. Let .I home -be the home directory so determined, if any. +be the value of the environment variable +.BR HOME ; +if this variable is not set, then +.I home +is not defined. .hP 5. A `cache home' directory is determined, as follows. If the environment variable @@ -582,25 +595,68 @@ with mode 0700 (and modified by the umask). (If it exists, but is not in fact a directory, then later operations will fail.) .PP -The runtime directory contains a number of other directories, -named -.\" FIXME junk, new, naming -.\" session dirs now entirely different -.IR tag . pid \fR. -Each such directory corresponds to a running +The runtime directory contains a number of other directories. +There are a small number of shared directories, +and zero or more +.I session +directories, +each one corresponding to a running (or failed) instance of -.BR with-authinfo-kludge ; -the +.BR with-authinfo-kludge . +.PP +The shared directories are as follows. +.TP +.B new/ +This is the `nursery' directory: +new session directories are created and populated in here. +Subdirectories have names of the form +.BI n. time . pid . rand / +where +.I time +is the time +(seconds since the POSIX epoch) +at which the directory was created; .I pid -is its process-id (possibly useful for diagnostic purposes), -and the +is the creator's process id; and +.I rand +is a random number chosen to minimize conflicts. +Directories in the nursery older than 300 seconds +may be deleted. +The creation protocol is to +create a directory with an appropriate name; +create a file within it named +.BR lock ; +take out a +.BR fcntl (2)-style +exclusive lock on this file; +and then move the directory to be a direct child +of the runtime directory. +.TP +.B junk/ +Session and nursery directories are deleted in two stages: +the first stage is to make them be subdirectories of +.BR junk/ . +Once there, any process may delete them. +Note that nursery directories can be junked +even if they're locked: +moving them to +.B junk/ +prevents them from being promoted to proper sessions. +.PP +Session directories are named +.BI s. tag . pid / +where the .I tag is the tag summarizing its purpose (as determined in step 5 of the procedure -for finding a configuration file). +for finding a configuration file), and +the +.I pid +is the creator's process-id, +which distinguishes this session from others with the same tag. .PP -The contents of the instance directory are as follows. +The contents of a session directory are as follows. .TP .B client.pid The process-id of the client command run by @@ -611,17 +667,32 @@ An empty file. A running .B with-authinfo-kludge -process holds a lock on this file. +process holds a +.BR fcntl (2)-style +lock on this file. It is used simply to tell other processes that the directory is still in use and shouldn't be cleaned up. .TP -.B noip/ -A directory containing Unix-domain sockets, -maintained by the +.B noip-client/ +A directory containing Unix-domain sockets created by +.BR with-authinfo-kludge ; +the .B noip -library. +library arranges for the client program +to connect to these Unix-domain sockets +rather than to the real remote NNTP servers. +.TP +.BR noip-ssh. server / +This directory also contains Unix-domain sockets ; +they are created by +.BR ssh (1) +and +.B authinfo-kludge +connects to them, +both under the influence of +.BR noip . .TP -.B ssh.pid +.BI ssh- server .pid The process-id of the SSH process started to satisfy a .B via server parameter. -- 2.11.0