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 [-i] [-u username] path hostname ip-number command ...

     The jail utility imprisons	a process and all future descendants.

     The options are as	follows:

     -i		  Output the jail identifier of	the newly created jail.

     -u	username  The user name	as whom	the command should run.

     path	  Directory which is to	be the root of the prison.

     hostname	  Hostname of the prison.

     ip-number	  IP number assigned to	the prison.

     command	  Pathname of the program which	is to be executed.

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

   Setting up a	Jail Directory Tree
     This example shows	how to setup a jail directory tree containing an en-
     tire FreeBSD distribution:

     cd	/usr/src
     mkdir -p $D
     make world	DESTDIR=$D
     cd	etc
     make distribution DESTDIR=$D
     mount_devfs devfs $D/dev
     cd	$D
     ln	-sf dev/null kernel

     In	many cases this	example	would put far more stuff in the	jail than is
     needed.  In the other extreme case	a jail might contain only one single
     file: the executable to be	run in the jail.

     We	recommend experimentation and caution that it is a lot easier to start
     with a "fat" jail and remove things until it stops	working, than it is to
     start with	a "thin" jail and add things until it works.

   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(8) to only listen on	the appropriate	IP address, and	so forth.  Add
     the following to /etc/rc.conf in the host environment:

	   inetd_flags="-wW -a"
	   rpcbind_enable="NO" 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
     sendmail(8), named(8), and	rpcbind(8).  While sendmail(8) and named(8)
     can be configured to listen only on a specific IP using their configura-
     tion files, in most cases it is easier to simply run the daemons in jails
     only, and not in the host environment.  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	/etc/rc.conf, etc.

	   +o   Create an empty /etc/fstab to quell startup warnings about
	       missing fstab
	   +o   Disable the port	mapper (/etc/rc.conf: rpcbind_enable="NO")
	   +o   Run newaliases(1) to quell sendmail(8) warnings.
	   +o   Disable interface configuration to quell	startup	warnings about
	       ifconfig(8) (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
     would 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
     security.jail.set_hostname_allowed	to 0.  Please see the management rea-
     sons 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
	   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.  To see an active	list of	jails, use the jls(8)
     utility.  You should also be able to telnet(1) to the hostname or IP ad-
     dress of the jailed environment, and log in using the accounts you	cre-
     ated 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:

	   kill	-TERM -1
	   kill	-KILL -1

     This will send the	SIGTERM	or SIGKILL 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.  To kill
     processes from outside the	jail, use the jexec(8) utility in conjuction
     with the one of the kill(1) commands above, or use	the killall(1) utility
     with the -j option.

     The /proc/pid/status file contains, 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.  However,	the hostname for a jail	may be,	by de-
     fault, modified from within the jail, so the /proc	status entry is	unre-
     liable by default.	 To disable the	setting	of the hostname	from within a
     jail, set the security.jail.set_hostname_allowed sysctl variable in the
     host environment to 0, which will affect all jails.  You can have this
     sysctl set	on each	boot using sysctl.conf(5).  Just add the following
     line to /etc/sysctl.conf:


   Sysctl MIB Entries
     Certain aspects of	the jail containments environment may be modified from
     the host environment using	sysctl(8) MIB variables.  Currently, these
     variables affect all jails	on the system, although	in the future this
     functionality may be finer	grained.

	  This MIB entry determines whether or not processes within a jail are
	  allowed to change their hostname via hostname(1) or sethostname(3).
	  In the current jail implementation, the ability to set the hostname
	  from within the jail can impact management tools relying on the ac-
	  curacy of jail information in	/proc.	As such, this should be	dis-
	  abled	in environments	where privileged access	to jails is given out
	  to untrusted parties.

	  The jail functionality binds an IPv4 address to each jail, and lim-
	  its access to	other network addresses	in the IPv4 space that may be
	  available in the host	environment.  However, jail is not currently
	  able to limit	access to other	network	protocol stacks	that have not
	  had jail functionality added to them.	 As such, by default, pro-
	  cesses within	jails may only access protocols	in the following do-
	  mains: PF_LOCAL, PF_INET, and	PF_ROUTE, permitting them access to
	  UNIX domain sockets, IPv4 addresses, and routing sockets.  To	enable
	  access to other domains, this	MIB variable may be set	to 0.

	  This MIB entry determines whether or not processes within a jail
	  have access to System	V IPC primitives.  In the current jail imple-
	  mentation, System V primitives share a single	namespace across the
	  host and jail	environments, meaning that processes within a jail
	  would	be able	to communicate with (and potentially interfere with)
	  processes outside of the jail, and in	other jails.  As such, this
	  functionality	is disabled by default,	but can	be enabled by setting
	  this MIB entry to 1.

     killall(1), newaliases(1),	ps(1), chroot(2), jail(2), jail_attach(2),
     procfs(5),	rc.conf(5), sysctl.conf(5), halt(8), inetd(8), jexec(8),
     jls(8), mount_devfs(8), named(8), reboot(8), rpcbind(8), sendmail(8),
     shutdown(8), sysctl(8), syslogd(8)

     The jail utility 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 the ability to allow access to specific jail infor-
     mation 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	build-
     ing a safe	host environment such that host	daemons	do not impose on ser-
     vices offered from	within jails.  Currently, the simplist answer is to
     minimize services offered on the host, possibly limiting it to services
     offered from inetd(8) which is easily configurable.

BSD				 April 8, 2003				   BSD


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

home | help