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 [-hi]	[-n jailname] [-J jid_file] [-s	securelevel]
	  [-l -u username | -U username] path hostname [ip[,..]] command ...

     The jail utility imprisons	a process and all future descendants.

     The options are as	follows:

     -h		  Resolve hostname and add all IP addresses returned by	the
		  resolver to the list of ip-addresses for this	prison.	 This
		  may affect default address selection for outgoing IPv4 con-
		  nections of prisons.	The address first returned by the re-
		  solver for each address family will be used as primary ad-
		  dress.  See ip-addresses further down	for details.

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

     -n	jailname  Assign and administrative name to the	jail that can be used
		  for management or auditing purposes.	The system will	not
		  enforce the name to be unique.

     -J	jid_file  Write	a jid_file file, containing jail identifier, path,
		  hostname, IP and command used	to start the 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.

     -s	securelevel
		  Sets the kern.securelevel sysctl variable to the specified
		  value	inside the newly created jail.

     -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.

		  None,	one or more IPv4 and IPv6 addresses assigned to	the
		  prison.  The first address of	each address family that was
		  assigned to the jail will be used as the source address in
		  case source address selection	on unbound sockets cannot find
		  a better match.  It is only possible to start	multiple jails
		  with the same	IP address, if none of the jails has more than
		  this single overlapping IP address assigned to itself	for
		  the address family in	question.

     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
     To	set up a jail directory	tree containing	an entire FreeBSD distribu-
     tion, the following sh(1) command script can be used:

     cd	/usr/src
     mkdir -p $D
     make world	DESTDIR=$D
     make distribution DESTDIR=$D
     mount -t devfs devfs $D/dev

     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.  A simple devfs ruleset
     for jails is available as ruleset #4 in /etc/defaults/devfs.rules.

     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 if the jail did not bind the port.  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 example.
     Daemons that run out of inetd(8) can be easily set	to use only the	speci-
     fied host IP address.  Other daemons will need to be manually config-
     ured--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   Configure /etc/resolv.conf so that name resolution within the
	       jail will work correctly
	   +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   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.

     It	is possible to have jails started at boot time.	 Please	refer to the
     "jail_*" variables	in rc.conf(5) for more information.  The rc(8) jail
     script provides a flexible	system to start/stop jails:

     /etc/rc.d/jail start
     /etc/rc.d/jail stop
     /etc/rc.d/jail start myjail
     /etc/rc.d/jail stop myjail

   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 conjunction
     with the one of the kill(1) commands above.

     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:


     You can also list/kill processes based on their jail ID.  To show pro-
     cesses and	their jail ID, use the following command:

	   ps ax -o pid,jid,args

     To	show and then kill processes in	jail number 3 use the following	com-

	   pgrep -lfj 3
	   pkill -j 3

	   killall -j 3

   Jails and File Systems
     It	is not possible	to mount(8) or umount(8) any file system inside	a jail
     unless the	file system is marked jail-friendly.  See
     security.jail.mount_allowed in the	Sysctl MIB Entries section.

     Multiple jails sharing the	same file system can influence each other.
     For example a user	in one jail can	fill the file system also leaving no
     space for processes in the	other jail.  Trying to use quota(1) to prevent
     this will not work	either as the file system quotas are not aware of
     jails but only look at the	user and group IDs.  This means	the same user
     ID	in two jails share the same file system	quota.	One would need to use
     one file system per jail to make this working.

   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 flag changes how	IPv4 source address selection works and	can
	  disable it for all prisons in	favour of forcing the primary IPv4 ad-
	  dress	of each	jail to	be used	for unbound outgoing connections.
	  Source address selection is enabled by default for all jails.

	  IPv6 equivalent to the security.jail.ip4_saddrsel option.

	  This MIB entry determines which information processes	in a jail are
	  able to get about mount-points.  It affects the behaviour of the
	  following syscalls: statfs(2), fstatfs(2), getfsstat(2) and
	  fhstatfs(2) (as well as similar compatibility	syscalls).  When set
	  to 0,	all mount-points are available without any restrictions.  When
	  set to 1, only mount-points below the	jail's chroot directory	are
	  visible.  In addition	to that, the path to the jail's	chroot direc-
	  tory is removed from the front of their pathnames.  When set to 2
	  (default), above syscalls can	operate	only on	a mount-point where
	  the jail's chroot directory is located.

	  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 constraints on

	  This MIB entry determines if a privileged user inside	a jail will be
	  able to mount	and unmount file system	types marked as	jail-friendly.
	  The lsvfs(1) command can be used to find file	system types available
	  for mount from within	a jail.	 This functionality is disabled	by de-
	  fault, but can be enabled by setting this MIB	entry to 1.

	  This MIB entry determines how	may address per	address	family a
	  prison may have. The default is 255.

     The read-only sysctl variable security.jail.jailed	can be used to deter-
     mine if a process is running inside a jail	(value is one) or not (value
     is	zero).

     The security.jail.list MIB	entry is read-only and it returns an array of
     struct xprison defined in <sys/jail.h>.  It is recommended	to use the
     jls(8) utility to see current active list of jails.

     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), lsvfs(1), newaliases(1), pgrep(1), pkill(1), ps(1), quota(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(8),
     named(8), reboot(8), rpcbind(8), sendmail(8), shutdown(8),	sysctl(8),
     syslogd(8), umount(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.

     Bjoern A. Zeeb added multi-IP jail	support	for IPv4 and IPv6 based	on a
     patch originally done by Pawel Jakub Dawidek for IPv4.

     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			       January 17, 2010				   BSD


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

home | help