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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
JAIL(8)			FreeBSD	System Manager's Manual		       JAIL(8)

NAME
     jail -- imprison process and its descendants

SYNOPSIS
     jail [-i] [-u username] path hostname ip-number command ...

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

     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 are available.  However,
     for a virtual server configuration, a fair	amount of additional work is
     required so as to configure the "boot" process.  This man page documents
     the configuration steps necessary to support either of these steps,
     althoguh the configuration	steps may be refined based on local require-
     ments.

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

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

     D=/here/is/the/jail
     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
     exposed to	a jail;	access to disk devices in the jail may permit pro-
     cesses in the jail	to bypass the jail sandboxing by modifying files out-
     side 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 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/192.168.11.100, named for the jailed IP address.
     Substitute	below as needed	with your own directory, IP address, and host-
     name.

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

	   sendmail_enable="NO"
	   inetd_flags="-wW -a 192.168.11.23"
	   rpcbind_enable="NO"

     192.168.11.23 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 application.  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
     /etc/mail/sendmail.cf.

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

     Start a shell in the jail:

	   jail	/data/jail/192.168.11.100 testhostname 192.168.11.100 /bin/sh

     You will end up with a shell prompt, assuming no errors, 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-
	       tem
	   +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/192.168.11.100/var/run/log.

     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
     application in the	jail, substitute the command used to start the appli-
     cation for	/etc/rc	in the examples	below.	To start a virtual server
     environment, /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 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 192.168.11.100/32
	   mount -t procfs proc	/data/jail/192.168.11.100/proc
	   jail	/data/jail/192.168.11.100 testhostname 192.168.11.100 \
		   /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
     address 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
     default, modified from within the jail, so	the /proc status entry is
     unreliable	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 follow-
     ing line to /etc/sysctl.conf:

	   security.jail.set_hostname_allowed=0

   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.

     security.jail.set_hostname_allowed
	  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
	  accuracy 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.

     security.jail.socket_unixiproute_only
	  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
	  domains: 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.

     security.jail.sysvipc_allowed
	  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.

     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.

SEE ALSO
     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)

HISTORY
     The jail utility appeared in FreeBSD 4.0.

AUTHORS
     The jail feature was written by Poul-Henning Kamp for R&D Associates
     http://www.rndassociates.com/ 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.

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

FreeBSD	9.2			 April 8, 2003			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=jail&sektion=8&manpath=FreeBSD+5.2-RELEASE>

home | help