Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
JAIL(8)			  BSD System Manager's Manual		       JAIL(8)

     jail -- imprison process and its descendants

     jail path hostname	ip-number command ...

     The jail command imprisons	a process and all future decendants.

     Please see	the jail(2) man	page for further details.

   Setting up a	Jail Directory Tree
     This shows	how to setup a jail directory tree:

     cd	/usr/src
     make hierarchy DESTDIR=$D
     make obj
     make depend
     make all
     make install DESTDIR=$D
     cd	etc
     make distribution DESTDIR=$D NO_MAKEDEV=yes
     cd	$D/dev
     sh	MAKEDEV	jail
     cd	$D
     ln	-sf dev/null kernel

   Setting Up a	Jail
     Do	what was described in Setting Up a Jail	Directory Tree to build	the
     jail directory tree.  For the sake	of this	example, we will assume	you
     built it in /data/jail/, named for the jailed IP address.
     Substitute	below as needed	with your own directory, IP address, and host-

     First, you	will want to set up your real system's environment to be
     "jail-friendly." For consistency, we will refer to	the parent box as the
     "host environment," and to	the jailed virtual machine as the "jail
     environment." Because jail	is implemented using IP	aliases, one of	the
     first things to do	is to disable IP services on the host system that lis-
     ten on all	local IP addresses for a service.  This	means changing inetd
     to	only listen on the appropriate IP address, and so forth.  Add the fol-
     lowing to /etc/rc.conf in the host	environment:

	   inetd_flags="-wW -a"
	   syslogd_flags="-ss" is the native IP address for	the host system, in this exam-
     ple.  Daemons that	run out	of inetd(8) can	be easily set to use only the
     specified host IP address.	 Other daemons will need to be manually	con-
     figured--for some this is possible	through	the rc.conf(5) flags entries,
     for others	it is not possible without munging the per-application config-
     uration files, or even recompiling.  For those applications that cannot
     specify the IP they run on, it is better to disable them, if possible.

     A number of daemons ship with the base system that	may have problems when
     run from outside of a jail	in a jail-centric environment.	This includes
     syslogd(8), sendmail(8), named(8),	and portmap(8).	 While sendmail	and
     named can be configured to	listen only on a specific IP using their con-
     figuration	files, in most cases it	is easier to simply run	the daemons in
     jails only, and not in the	host environment.  Syslogd cannot be config-
     ured to bind only a single	IP, but	can be configured to not bind a	net-
     work port,	using the ``-ss'' argument.  Attempting	to serve NFS from the
     host environment may also cause confusion,	and cannot be easily reconfig-
     ured to use only specific IPs, as some NFS	services are hosted directly
     from the kernel.  Any third party network software	running	in the host
     environment should	also be	checked	and configured so that it does not
     bind all IP addresses, which would	result in those	services also appear-
     ing to be offered by the jail environments.

     Once these	daemons	have been disabled or fixed in the host	environment,
     it	is best	to reboot so that all daemons are in a known state, to reduce
     the potential for confusion later (such as	finding	that when you send
     mail to a jail, and its sendmail is down, the mail	is delivered to	the
     host, etc.)

     Start any jails for the first time	without	configuring the	network	inter-
     face so that you can clean	it up a	little and set up accounts.  As	with
     any machine (virtual or not) you will need	to set a root password,	time
     zone, etc.	 Before	beginning, you may want	to copy	sysinstall(8) into the
     tree so that you can use it to set	things up easily.  Do this using:

	   # mkdir /data/jail/
	   # cp	/stand/sysinstall /data/jail/

     Now start the jail:

	   # jail /data/jail/ testhostname	/bin/sh

     You will end up with a shell prompt, assuming no errors, within the jail.
     You can now run /stand/sysinstall and do the post-install configuration
     to	set various configuration options, or perform these actions manually
     by	editing	rc.conf, etc.

	   +o   Create an empty /etc/fstab to quell startup warnings about
	       missing fstab
	   +o   Disable the port	mapper (rc.conf: portmap_enable="NO")
	   +o   Run newaliases(1) to quell sendmail warnings.
	   +o   Disable interface configuration to quell	startup	warnings about
	       ifconfig	(network_interfaces="")
	   +o   Configure /etc/resolv.conf so that name resolution within the
	       jail will work correctly
	   +o   Set a root password, probably different from the	real host sys-
	   +o   Set the timezone
	   +o   Add accounts for	users in the jail environment
	   +o   Install any packages that you think the environment requires

     You may also want to perform any package-specific configuration (web
     servers, SSH servers, etc), patch up /etc/syslog.conf so it logs as you'd
     like, etc.

     Exit from the shell, and the jail will be shut down.

   Starting the	Jail
     You are now ready to restart the jail and bring up	the environment	with
     all of its	daemons	and other programs.  To	do this, first bring up	the
     virtual host interface, and then start the	jail's /etc/rc script from
     within the	jail.

     NOTE: If you plan to allow	untrusted users	to have	root access inside the
     jail, you may wish	to consider setting the	jail.set_hostname_allowed to
     0.	 Please	see the	management reasons why this is a good idea.  If	you do
     decide to set this	variable, it must be set before	starting any jails,
     and once each boot.

	   # ifconfig ed0 inet alias netmask
	   # mount -t procfs proc /data/jail/
	   # jail /data/jail/ testhostname	\
		   /bin/sh /etc/rc

     A few warnings will be produced, because most sysctl(8) configuration
     variables cannot be set from within the jail, as they are global across
     all jails and the host environment.  However, it should all work prop-
     erly.  You	should be able to see inetd(8),	syslogd(8), and	other pro-
     cesses running within the jail using ps(1), with the "J" flag appearing
     beside jailed processes.  You should also be able to telnet to the	host-
     name or IP	address	of the jailed environment, and log in using the
     acounts you created previously.

   Managing the	jail
     Normal machine shutdown commands, such as halt(8),	reboot(8), and
     shutdown(8), cannot be used successfully within the jail.	To kill	all
     processes in a jail, you may log into the jail and, as root, use one of
     the following commands, depending on what you want	to accomplish:

	   +o   kill -TERM -1
	   +o   kill -KILL -1

     This will send the	"TERM" or "KILL" signals to all	processes in the jail
     from within the jail.  Depending on the intended use of the jail, you may
     also want to run /etc/rc.shutdown from within the jail.  Currently	there
     is	no way to insert new processes into a jail, so you must	first log into
     the jail before performing	these actions.

     To	kill processes from outside the	jail, you must individually identify
     the PID of	each process to	be killed.  The	/proc/pid/status file con-
     tains, as its last	field, the hostname of the jail	in which the process
     runs, or "-" to indicate that the process is not running within a jail.
     The ps(1) command also shows a "J"	flag for processes in a	jail.  How-
     ever, the hostname	for a jail may be, by default, modified	from within
     the jail, so the /proc status entry is unreliably by default.  To disable
     the setting of the	hostname from within a jail, set the
     "jail.set_hostname_allowed" sysctl	variable in the	host environment to 0,
     which will	affect all jails.  You can have	this sysctl set	each boot us-
     ing sysctl.conf(5).  Just add the following line to sysctl.conf:


     In	a future version of FreeBSD, the mechanisms for	managing jails will be
     more refined.

     newaliases(1), ps(1), chroot(2), jail(2), procfs(5), rc.conf(5),
     sysctl.conf(5), halt(8), inetd(8),	named(8), portmap(8), reboot(8),
     sendmail(8), shutdown(8), sysctl(8), syslogd(8)

     The jail()	function call appeared in FreeBSD 4.0.

     The jail feature was written by Poul-Henning Kamp for R&D Associates
     "" who contributed it	to FreeBSD.

     Robert Watson wrote the extended documentation, found a few bugs, added a
     few new features, and cleaned up the userland jail	environment.

     Jail currently lacks strong management functionality, such	as the ability
     to	deliver	signals	to all processes in a jail, and	to allow access	to
     specific jail information via ps(1) as opposed to procfs(5).  Similarly,
     it	might be a good	idea to	add an address alias flag such that daemons
     listening on all IPs (INADDR_ANY) will not	bind on	that address, which
     would facilitate building a safe host environment such that host daemons
     do	not impose on services offered from within jails.  Currently, the sim-
     plist answer is to	minimize services offered on the host, possibly	limit-
     ing it to services	offered	from inetd which is easily configurable.

FreeBSD	4.0			April 28, 1999			   FreeBSD 4.0


Want to link to this manual page? Use this URL:

home | help