doc/userplex.doc

   1 userplex(1)
   2 ===========
   3
   4 NAME
   5 ----
   6 userplex - User directory multiplexer for ashd(7)
   7
   8 SYNOPSIS
   9 --------
  10 *userplex* [*-hIs*] [*-g* 'GROUP'] [*-m* 'MIN-UID'] [*-d* 'PUBDIR'] ['PROGRAM' ['ARGS'...]]
  11
  12 DESCRIPTION
  13 -----------
  14
  15 The *userplex* handler serves user-defined content by logging in as
  16 the requested user and running a request handler on that user's
  17 behalf, running as that user.
  18
  19 *userplex* is a persistent handler, as defined in *ashd*(7), and the
  20 handlers it starts for individual users must also be persistent
  21 handlers. The same request handler will be reused for each individual
  22 user as long as it does not exit.
  23
  24 When handling a request, *userplex* strips off the leading part of the
  25 rest string, up until the first slash, and treats the stripped-off
  26 part as a user name. If the user name is found on the system and
  27 matches the criteria specified by the command-line options (see
  28 OPTIONS below), and a request handler is not already running for that
  29 user, *userplex* starts a request handler logged in as the user in
  30 question (see LOGIN below) .
  31
  32 If the user has an executable file named `~/.ashd/handler` in his home
  33 directory, it will be started and used as the request handler for that
  34 user. Otherwise, a default handler is used. If the 'PROGRAM' argument
  35 was given to *userplex*, it will be started as the handler program
  36 (searching the *PATH* environment variable if it contains no
  37 slashes). 'ARGS' will be passed to it as command-line arguments. If
  38 'PROGRAM' was not given, the *dirplex*(1) program will be started by
  39 default, with 'PUBDIR' passed as its only command-line
  40 argument. 'PUBDIR' defaults to `htpub` if no 'PROGRAM' was specified.
  41
  42 If 'PUBDIR' was given (either by being specified explicitly, or
  43 implicitly if no 'PROGRAM' argument was given), it is checked for
  44 existence. If it does not exist, *userplex* returns a 404 response to
  45 the client.
  46
  47 If there exists a file named `~/.ashd/error` in the user's home
  48 directory, it will be opened in append mode and connected to the
  49 request handler's standard error. If it does not exist, `/dev/null`
  50 will be opened and connected to standard error instead. In the same
  51 manner, `~/.ashd/output` will be opened and connected to the request
  52 handler's standard output if it exists.
  53
  54 OPTIONS
  55 -------
  56
  57 *-h*::
  58
  59         Print a brief help message to standard output and exit.
  60
  61 *-I*::
  62
  63         If given, ignore any `~/.ashd/handler` file in a user's home
  64         directory and use only the default handler.
  65
  66 *-s*::
  67
  68         If given, set the ASHD_USESYSLOG environment variable in all
  69         started children. If not given, *userplex* will actively clear
  70         the variable from its children instead. The presence of the
  71         variable indicates to the standard ashd programs to log
  72         messages to *syslog*(3) instead of printing them on standard
  73         error.
  74
  75 *-g* 'GROUP'::
  76
  77         If given, only users that are members of the named 'GROUP'
  78         will be considered for serving. Requesting another user will
  79         return a 404 response to the client.
  80
  81 *-m* 'MIN-UID'::
  82
  83         If given, only users that have a UID of at least 'MIN-UID'
  84         will be considered for serving. Requesting another user will
  85         return a 404 response to the client.
  86
  87 *-d* 'PUBDIR'::
  88
  89         If given, 'PUBDIR' will be checked for existence before
  90         starting the default request handler for a requested user. If
  91         the 'PROGRAM' argument was not given to *userplex*, it will be
  92         passed as the single argument to *dirplex*(1), which is
  93         invoked by default. If neither the *-d* option nor the
  94         'PROGRAM' argument were given to *userplex*, 'PUBDIR'
  95         defaults to `htpub`.
  96
  97 LOGIN
  98 -----
  99
 100 As part of the login procedure, *userplex* does the following:
 101
 102  * A new session is entered (with *setsid*(2)).
 103
 104  * The UID, GID and auxiliary groups of the new process are changed
 105    accordingly. For testing purposes, *userplex* may be running as a
 106    user other than root, and the child process will, then, simply exit
 107    if it is not running as the requested user.
 108
 109  * The child process will change directory to the user's home
 110    directory.
 111
 112  * The *HOME*, *SHELL*, *USER* and *LOGNAME* environment variables are
 113    set appropriately.
 114
 115 Note that no shell is actually spawned, and that no profile scripts or
 116 similar will therefore be run. If it is important that your personal
 117 environment variables are set properly, a useful trick is to install a
 118 simple shell script as `~/.ashd/handler`, containing the following two
 119 lines:
 120
 121 --------
 122 #!/bin/sh -l
 123 exec dirplex htpub
 124 --------
 125
 126 The standard *-l* switch to the shell (see *sh*(1)) will make it run
 127 its normal login procedure, and then *exec*(2) the *dirplex*(1)
 128 handler to serve files normally. Of course, the second line can be
 129 replaced by whatever other handler one might wish to use.
 130
 131 AUTHOR
 132 ------
 133 Fredrik Tolf <fredrik@dolda2000.com>
 134
 135 SEE ALSO
 136 --------
 137 *dirplex*(1), *patplex*(1) (the EXAMPLES section), *ashd*(7)