[shells] / chrootsh.8

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