htparser: Add a `Server' header if none previously present.
[ashd.git] / 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* [*-hI*] [*-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 *-g* 'GROUP'::
67
68         If given, only users that are members of the named 'GROUP'
69         will be considered for serving. Requesting another user will
70         return a 404 response to the client.
71
72 *-m* 'MIN-UID'::
73
74         If given, only users that have a UID of at least 'MIN-UID'
75         will be considered for serving. Requesting another user will
76         return a 404 response to the client.
77
78 *-d* 'PUBDIR'::
79
80         If given, 'PUBDIR' will be checked for existence before
81         starting the default request handler for a requested user. If
82         the 'PROGRAM' argument was not given to *userplex*, it will be
83         passed as the single argument to *dirplex*(1), which is
84         invoked by default. If neither the *-d* option nor the
85         'PROGRAM' argument were given to *userplex*, 'PUBDIR'
86         defaults to `htpub`.
87
88 LOGIN
89 -----
90
91 As part of the login procedure, *userplex* does the following:
92
93  * The UID, GID and auxiliary groups of the new process are changed
94    accordingly. For testing purposes, *userplex* may be running as a
95    user other than root, and the child process will, then, simply exit
96    if it is not running as the requested user.
97
98  * The child process will change directory to the user's home
99    directory.
100
101  * The *HOME*, *SHELL*, *USER* and *LOGNAME* environment variables are
102    set appropriately.
103
104 Note that no shell is actually spawned, and that no profile scripts or
105 similar will therefore be run. If it is important that your personal
106 environment variables are set properly, a useful trick is to install a
107 simple shell script as `~/.ashd/handler`, containing the following two
108 lines:
109
110 --------
111 #!/bin/sh -l
112 exec dirplex htpub
113 --------
114
115 The standard *-l* switch to the shell (see *sh*(1)) will make it run
116 its normal login procedure, and then *exec*(2) the *dirplex*(1)
117 handler to serve files normally. Of course, the second line can be
118 replaced by whatever other handler one might wish to use.
119
120 BUGS
121 ----
122
123 Currently, *userplex* does not, in fact, return a 404 response to the
124 client if the 'PUBDIR' directory does not exist.
125
126 AUTHOR
127 ------
128 Fredrik Tolf <fredrik@dolda2000.com>
129
130 SEE ALSO
131 --------
132 *dirplex*(1), *patplex*(1) (the EXAMPLES section), *ashd*(7)