.\" -*-nroff-*-
.TH chrootsh 8 "20 April 1999" "Local tools"
.SH NAME
chrootsh \- logs a user into a safe chrooted environment
.SH SYNOPSIS
.B chrootsh
.SH USAGE
Set a user's shell to the
.B chrootsh
program's path.
.PP
When run, 
.B chrootsh
ensures that the current user has his or her shell set to be
.BR chrootsh .
If not, an error is raised and the program exits.
.PP
Assuming things check out OK, the user's home directory is examined.  It
should be of the form
.IB gaoldir /./ homedir
where
.I gaoldir
is the path to the chroot gaol in which the user is to be imprisoned,
and
.I homedir
is the path from the root of the gaol to the user's actual home
directory.  (This is for the benefit of users outside the gaol;
.B chrootsh
uses information from the gaol's
.B /etc/passwd
file to work this out.  You'd do yourself a favour to make sure the two
are consistent.)
.PP
Once the new root directory is set,
.B chrootsh
drops all of its privileges, and re-reads the user's information
(presumably from a local version of the
.B /etc/passwd
file) to find the appropriate shell and home directory.  It sets
appropriate values in the environment, and invokes the user's shell.
.SH EXAMPLE
Suppose
.B /home/gaol
is a carefully set-up environment for users to run in, with a minimal
set of tools installed.  To set up a user
.B fred
within the gaol, make a directory
.B /home/gaol/home/fred
for the user, setting the access permissions as required.  Then add a
line like
.PP
.RS 5
.nf
.ft B
fred:*:1042:1042:Fred:/home/gaol/./home/fred:/usr/bin/chrootsh
.ft R
.fi
.RE
.PP
to the main password database (wherever that is).  Then, put a line
.PP
.RS 5
.nf
.ft B
fred:*:1042:1042:Fred:/home/fred:/bin/sh
.ft R
.fi
.RE
.PP
in the gaol's password file
.BR /home/gaol/etc/passwd .
Finally, set a sensible password for
.B fred
in the main password database, and everything ought to work.
.PP
The
.B chrootsh
program makes entries in the system log whenever a user logs in, or when
something goes wrong.  Every call ought to make at least one log entry.
Logging is done to the
.B LOG_DAEMON
facility, because the idea is that users with shells like this get used
to run `daemon'-like services.
.SH BUGS
The
.B chrootsh
program must be installed 
.RB setuid- root .
While the author has made a fair effort to avoid security holes, he
might have missed something.  There's no substitute for thorough
auditing.  If you find a security problem, please report it to the
author as a serious bug.
.SH SEE ALSO
.BR banned (8),
.BR ushell (1).
.SH AUTHOR
Mark Wooding (mdw@nsict.org)