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] [-l -u username | -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.

     -l		  Run program in the clean environment.	 The environment is
		  discarded except for HOME, SHELL, TERM and USER.  HOME and
		  SHELL	are set	to the target login's default values.  USER is
		  set to the target login.  TERM is imported from the current
		  environment.	The environment	variables from the login class
		  capability database for the target login are also set.

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

     -U	username  The user name	from jailed environment	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.

     Jails are typically set up	using one of two philosophies: either to con-
     strain a specific application (possibly running with privilege), or to
     create a "virtual system image" running a variety of daemons and ser-
     vices.  In	both cases, a fairly complete file system install of FreeBSD
     is	required, so as	to provide the necessary command line tools, daemons,
     libraries,	application configuration files, etc.  However,	for a virtual
     server configuration, a fair amount of additional work is required	so as
     to	configure the "boot" process.  This manual page	documents the configu-
     ration steps necessary to support either of these steps, although the
     configuration steps may be	refined	based on local requirements.

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

   Setting up a	Jail Directory Tree
     This example shows	how to set up 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

     NOTE: It is important that	only appropriate device	nodes in devfs be ex-
     posed to a	jail; access to	disk devices in	the jail may permit processes
     in	the jail to bypass the jail sandboxing by modifying files outside of
     the jail.	See devfs(8) for information on	how to use devfs rules to
     limit access to entries in	the per-jail devfs.

     In	many cases this	example	would put far more in the jail than needed.
     In	the other extreme case a jail might contain only one file: the exe-
     cutable 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-

   Setting up the Host Environment
     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".  Since 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.  If a	network	service	is
     present in	the host environment that binds	all available IP addresses
     rather than specific IP addresses,	it may service requests	sent to	jail
     IP	addresses.  This means changing	inetd(8) to only listen	on the appro-
     priate 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 necessary	to modify per-application configuration	files,
     or	to recompile the applications.	The following frequently deployed ser-
     vices must	have their individual configuration files modified to limit
     the application to	listening to a specific	IP address:

     To	configure sshd(8), it is necessary to modify /etc/ssh/sshd_config.

     To	configure sendmail(8), it is necessary to modify

     For named(8), it is necessary to modify /etc/namedb/named.conf.

     In	addition, a number of services must be recompiled in order to run them
     in	the host environment.  This includes most applications providing ser-
     vices using rpc(3), such as rpcbind(8,) nfsd(8), and mountd(8).  In gen-
     eral, applications	for which it is	not possible to	specify	which IP ad-
     dress to bind should not be run in	the host environment unless they
     should also service requests sent to jail IP addresses.  Attempting to
     serve NFS from the	host environment may also cause	confusion, and cannot
     be	easily reconfigured to use only	specific IPs, as some NFS services are
     hosted directly from the kernel.  Any third-party network software	run-
     ning in the host environment should also be checked and configured	so
     that it does not bind all IP addresses, which would result	in those ser-
     vices' also appearing 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.).

   Configuring the Jail
     Start any jail 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.	 Some of these steps apply only	if you intend to run a full
     virtual server inside the jail; others apply both for constraining	a par-
     ticular application or for	running	a virtual server.

     Start a shell in the jail:

	   jail	/data/jail/ testhostname /bin/sh

     Assuming no errors, you will end up with a	shell prompt within the	jail.
     You can now run /usr/sbin/sysinstall and do the post-install configura-
     tion to set various configuration options,	or perform these actions manu-
     ally by editing /etc/rc.conf, etc.

	   o   Create an empty /etc/fstab to quell startup warnings about
	       missing fstab (virtual server only)
	   o   Disable the port	mapper (/etc/rc.conf: rpcbind_enable="NO")
	       (virtual	server only)
	   o   Run newaliases(1) to quell sendmail(8) warnings.
	   o   Disable interface configuration to quell	startup	warnings about
	       ifconfig(8) (network_interfaces="") (virtual server only)
	   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 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.  If you are not using a virtual server, you may wish to
     modify syslogd(8) in the host environment to listen on the	syslog socket
     in	the jail environment; in this example, the syslog socket would be
     stored in /data/jail/

     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.  If	you are	running	a single ap-
     plication in the jail, substitute the command used	to start the applica-
     tion for /etc/rc in the examples below.  To start a virtual server	envi-
     ronment, /etc/rc is run to	launch various daemons and services.  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	sysctl variable	to 0.  Please see the
     management	discussion later in this document as to	why this may be	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 prison root is allowed to
	  create raw sockets.  Setting this MIB	to 1 allows utilities like
	  ping(8) and traceroute(8) to operate inside the prison.  If this MIB
	  is set, the source IP	addresses are enforced to comply with the IP
	  address bound	to the jail, regardless	of whether or not the
	  IP_HDRINCL flag has been set on the socket.  Since raw sockets can
	  be used to configure and interact with various network subsystems,
	  extra	caution	should be used where privileged	access to jails	is
	  given	out to untrusted parties.  As such, by default this option is

	  This MIB entry determines whether or not processes within a jail are
	  able to see data for all mountpoints.	 When set to 1 (default), the
	  getfsstat(2) system call returns only	(when called by	jailed pro-
	  cesses) the data for the file	system on which	the jail's root	vnode
	  is located.  Note: this also has the effect of hiding	other mounts
	  inside a jail, such as /dev, /tmp, and /proc,	but errs on the	side
	  of leaking less information.

	  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.

	  This MIB entry determines how	a privileged user inside a jail	will
	  be treated by	chflags(2).  If	zero, such users are treated as	un-
	  privileged, and are unable to	set or clear system file flags;	if
	  non-zero, such users are treated as privileged, and may manipulate
	  system file flags subject to the usual constaints on

     There are currently two MIB related variables that	have per-jail set-
     tings.  Changes to	these variables	by a jailed process do not effect the
     host environment, only the	jail environment.  The variables are
     kern.securelevel and kern.hostname.

     killall(1), newaliases(1),	ps(1), chroot(2), jail(2), jail_attach(2),
     procfs(5),	rc.conf(5), sysctl.conf(5), devfs(8), 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 simplest 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