Added the `ratequeue' program.
[ashd.git] / doc / userplex.doc
... / ...
CommitLineData
1userplex(1)
2===========
3
4NAME
5----
6userplex - User directory multiplexer for ashd(7)
7
8SYNOPSIS
9--------
10*userplex* [*-hIs*] [*-g* 'GROUP'] [*-m* 'MIN-UID'] [*-d* 'PUBDIR'] ['PROGRAM' ['ARGS'...]]
11
12DESCRIPTION
13-----------
14
15The *userplex* handler serves user-defined content by logging in as
16the requested user and running a request handler on that user's
17behalf, running as that user.
18
19*userplex* is a persistent handler, as defined in *ashd*(7), and the
20handlers it starts for individual users must also be persistent
21handlers. The same request handler will be reused for each individual
22user as long as it does not exit.
23
24When handling a request, *userplex* strips off the leading part of the
25rest string, up until the first slash, and treats the stripped-off
26part as a user name. If the user name is found on the system and
27matches the criteria specified by the command-line options (see
28OPTIONS below), and a request handler is not already running for that
29user, *userplex* starts a request handler logged in as the user in
30question (see LOGIN below) .
31
32If the user has an executable file named `~/.ashd/handler` in his home
33directory, it will be started and used as the request handler for that
34user. Otherwise, a default handler is used. If the 'PROGRAM' argument
35was given to *userplex*, it will be started as the handler program
36(searching the *PATH* environment variable if it contains no
37slashes). 'ARGS' will be passed to it as command-line arguments. If
38'PROGRAM' was not given, the *dirplex*(1) program will be started by
39default, with 'PUBDIR' passed as its only command-line
40argument. 'PUBDIR' defaults to `htpub` if no 'PROGRAM' was specified.
41
42If 'PUBDIR' was given (either by being specified explicitly, or
43implicitly if no 'PROGRAM' argument was given), it is checked for
44existence. If it does not exist, *userplex* returns a 404 response to
45the client.
46
47If there exists a file named `~/.ashd/error` in the user's home
48directory, it will be opened in append mode and connected to the
49request handler's standard error. If it does not exist, `/dev/null`
50will be opened and connected to standard error instead. In the same
51manner, `~/.ashd/output` will be opened and connected to the request
52handler's standard output if it exists.
53
54OPTIONS
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
97LOGIN
98-----
99
100As 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
115Note that no shell is actually spawned, and that no profile scripts or
116similar will therefore be run. If it is important that your personal
117environment variables are set properly, a useful trick is to install a
118simple shell script as `~/.ashd/handler`, containing the following two
119lines:
120
121--------
122#!/bin/sh -l
123exec dirplex htpub
124--------
125
126The standard *-l* switch to the shell (see *sh*(1)) will make it run
127its normal login procedure, and then *exec*(2) the *dirplex*(1)
128handler to serve files normally. Of course, the second line can be
129replaced by whatever other handler one might wish to use.
130
131AUTHOR
132------
133Fredrik Tolf <fredrik@dolda2000.com>
134
135SEE ALSO
136--------
137*dirplex*(1), *patplex*(1) (the EXAMPLES section), *ashd*(7)