| 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* should return a 404 |
| 45 | response to the client (but see BUGS below). |
| 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 | * The UID, GID and auxiliary groups of the new process are changed |
| 103 | accordingly. For testing purposes, *userplex* may be running as a |
| 104 | user other than root, and the child process will, then, simply exit |
| 105 | if it is not running as the requested user. |
| 106 | |
| 107 | * The child process will change directory to the user's home |
| 108 | directory. |
| 109 | |
| 110 | * The *HOME*, *SHELL*, *USER* and *LOGNAME* environment variables are |
| 111 | set appropriately. |
| 112 | |
| 113 | Note that no shell is actually spawned, and that no profile scripts or |
| 114 | similar will therefore be run. If it is important that your personal |
| 115 | environment variables are set properly, a useful trick is to install a |
| 116 | simple shell script as `~/.ashd/handler`, containing the following two |
| 117 | lines: |
| 118 | |
| 119 | -------- |
| 120 | #!/bin/sh -l |
| 121 | exec dirplex htpub |
| 122 | -------- |
| 123 | |
| 124 | The standard *-l* switch to the shell (see *sh*(1)) will make it run |
| 125 | its normal login procedure, and then *exec*(2) the *dirplex*(1) |
| 126 | handler to serve files normally. Of course, the second line can be |
| 127 | replaced by whatever other handler one might wish to use. |
| 128 | |
| 129 | BUGS |
| 130 | ---- |
| 131 | |
| 132 | Currently, *userplex* does not, in fact, return a 404 response to the |
| 133 | client if the 'PUBDIR' directory does not exist. |
| 134 | |
| 135 | AUTHOR |
| 136 | ------ |
| 137 | Fredrik Tolf <fredrik@dolda2000.com> |
| 138 | |
| 139 | SEE ALSO |
| 140 | -------- |
| 141 | *dirplex*(1), *patplex*(1) (the EXAMPLES section), *ashd*(7) |