[ashd.git] / doc / userplex.doc

userplex(1)
===========

NAME
----
userplex - User directory multiplexer for ashd(7)

SYNOPSIS
--------
*userplex* [*-hIs*] [*-g* 'GROUP'] [*-m* 'MIN-UID'] [*-d* 'PUBDIR'] ['PROGRAM' ['ARGS'...]]

DESCRIPTION
-----------

The *userplex* handler serves user-defined content by logging in as
the requested user and running a request handler on that user's
behalf, running as that user.

*userplex* is a persistent handler, as defined in *ashd*(7), and the
handlers it starts for individual users must also be persistent
handlers. The same request handler will be reused for each individual
user as long as it does not exit.

When handling a request, *userplex* strips off the leading part of the
rest string, up until the first slash, and treats the stripped-off
part as a user name. If the user name is found on the system and
matches the criteria specified by the command-line options (see
OPTIONS below), and a request handler is not already running for that
user, *userplex* starts a request handler logged in as the user in
question (see LOGIN below) .

If the user has an executable file named `~/.ashd/handler` in his home
directory, it will be started and used as the request handler for that
user. Otherwise, a default handler is used. If the 'PROGRAM' argument
was given to *userplex*, it will be started as the handler program
(searching the *PATH* environment variable if it contains no
slashes). 'ARGS' will be passed to it as command-line arguments. If
'PROGRAM' was not given, the *dirplex*(1) program will be started by
default, with 'PUBDIR' passed as its only command-line
argument. 'PUBDIR' defaults to `htpub` if no 'PROGRAM' was specified.

If 'PUBDIR' was given (either by being specified explicitly, or
implicitly if no 'PROGRAM' argument was given), it is checked for
existence. If it does not exist, *userplex* should return a 404
response to the client (but see BUGS below).

If there exists a file named `~/.ashd/error` in the user's home
directory, it will be opened in append mode and connected to the
request handler's standard error. If it does not exist, `/dev/null`
will be opened and connected to standard error instead. In the same
manner, `~/.ashd/output` will be opened and connected to the request
handler's standard output if it exists.

OPTIONS
-------

*-h*::

	Print a brief help message to standard output and exit.

*-I*::

	If given, ignore any `~/.ashd/handler` file in a user's home
	directory and use only the default handler.

*-s*::

	If given, set the ASHD_USESYSLOG environment variable in all
	started children. If not given, *userplex* will actively clear
	the variable from its children instead. The presence of the
	variable indicates to the standard ashd programs to log
	messages to *syslog*(3) instead of printing them on standard
	error.

*-g* 'GROUP'::

	If given, only users that are members of the named 'GROUP'
	will be considered for serving. Requesting another user will
	return a 404 response to the client.

*-m* 'MIN-UID'::

	If given, only users that have a UID of at least 'MIN-UID'
	will be considered for serving. Requesting another user will
	return a 404 response to the client.

*-d* 'PUBDIR'::

	If given, 'PUBDIR' will be checked for existence before
	starting the default request handler for a requested user. If
	the 'PROGRAM' argument was not given to *userplex*, it will be
	passed as the single argument to *dirplex*(1), which is
	invoked by default. If neither the *-d* option nor the
	'PROGRAM' argument were given to *userplex*, 'PUBDIR'
	defaults to `htpub`.

LOGIN
-----

As part of the login procedure, *userplex* does the following:

 * The UID, GID and auxiliary groups of the new process are changed
   accordingly. For testing purposes, *userplex* may be running as a
   user other than root, and the child process will, then, simply exit
   if it is not running as the requested user.

 * The child process will change directory to the user's home
   directory.

 * The *HOME*, *SHELL*, *USER* and *LOGNAME* environment variables are
   set appropriately.

Note that no shell is actually spawned, and that no profile scripts or
similar will therefore be run. If it is important that your personal
environment variables are set properly, a useful trick is to install a
simple shell script as `~/.ashd/handler`, containing the following two
lines:

--------
#!/bin/sh -l
exec dirplex htpub
--------

The standard *-l* switch to the shell (see *sh*(1)) will make it run
its normal login procedure, and then *exec*(2) the *dirplex*(1)
handler to serve files normally. Of course, the second line can be
replaced by whatever other handler one might wish to use.

BUGS
----

Currently, *userplex* does not, in fact, return a 404 response to the
client if the 'PUBDIR' directory does not exist.

AUTHOR
------
Fredrik Tolf <fredrik@dolda2000.com>

SEE ALSO
--------
*dirplex*(1), *patplex*(1) (the EXAMPLES section), *ashd*(7)
Commit	Line	Data
	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)