[shells] / chrootsh.8

.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)
Commit	Line	Data
ed36b0a2	1	.TH chrootsh 8 "20 April 1999" "Local tools"
	2	.SH NAME
	3	chrootsh \- logs a user into a safe chrooted environment
	4	.SH SYNOPSIS
	5	.B chrootsh
	6	.SH USAGE
	7	Set a user's shell to the
	8	.B chrootsh
	9	program's path.
	10	.PP
	11	When run,
	12	.B chrootsh
	13	ensures that the current user has his or her shell set to be
	14	.BR chrootsh .
	15	If not, an error is raised and the program exits.
	16	.PP
	17	Assuming things check out OK, the user's home directory is examined. It
	18	should be of the form
	19	.IB gaoldir /./ homedir
	20	where
	21	.I gaoldir
	22	is the path to the chroot gaol in which the user is to be imprisoned,
	23	and
	24	.I homedir
	25	is the path from the root of the gaol to the user's actual home
	26	directory. (This is for the benefit of users outside the gaol;
	27	.B chrootsh
	28	uses information from the gaol's
	29	.B /etc/passwd
	30	file to work this out. You'd do yourself a favour to make sure the two
	31	are consistent.)
	32	.PP
	33	Once the new root directory is set,
	34	.B chrootsh
	35	drops all of its privileges, and re-reads the user's information
	36	(presumably from a local version of the
	37	.B /etc/passwd
	38	file) to find the appropriate shell and home directory. It sets
	39	appropriate values in the environment, and invokes the user's shell.
	40	.SH EXAMPLE
	41	Suppose
	42	.B /home/gaol
	43	is a carefully set-up environment for users to run in, with a minimal
	44	set of tools installed. To set up a user
	45	.B fred
	46	within the gaol, make a directory
	47	.B /home/gaol/home/fred
	48	for the user, setting the access permissions as required. Then add a
	49	line like
	50	.PP
	51	.RS 5
	52	.nf
	53	.ft B
	54	fred:*:1042:1042:Fred:/home/gaol/./home/fred:/usr/bin/chrootsh
	55	.ft R
	56	.fi
	57	.RE
	58	.PP
	59	to the main password database (wherever that is). Then, put a line
	60	.PP
	61	.RS 5
	62	.nf
	63	.ft B
	64	fred:*:1042:1042:Fred:/home/fred:/bin/sh
65	.ft R
66	.fi
67	.RE
68	.PP
69	in the gaol's password file
70	.BR /home/gaol/etc/passwd .
71	Finally, set a sensible password for
72	.B fred
73	in the main password database, and everything ought to work.
cf60a621	74	.PP
	75	The
	76	.B chrootsh
	77	program makes entries in the system log whenever a user logs in, or when
	78	something goes wrong. Every call ought to make at least one log entry.
	79	Logging is done to the
	80	.B LOG_DAEMON
	81	facility, because the idea is that users with shells like this get used
	82	to run `daemon'-like services.
ed36b0a2	83	.SH BUGS
	84	The
	85	.B chrootsh
	86	program must be installed
	87	.RB setuid- root .
	88	While the author has made a fair effort to avoid security holes, he
	89	might have missed something. There's no substitute for thorough
	90	auditing. If you find a security problem, please report it to the
	91	author as a serious bug.
	92	.SH SEE ALSO
	93	.BR banned (8),
	94	.BR ushell (1).
	95	.SH AUTHOR
	96	Mark Wooding (mdw@nsict.org)