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

DESCRIPTION
     The jail command imprisons	a process and all future descendants.

     The options are as	follows:

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

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 -DNO_MAKEDEV_RUN
     cd	$D/dev
     sh	MAKEDEV	jail
     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/192.168.11.100, named for the jailed IP address.
     Substitute	below as needed	with your own directory, IP address, and host-
     name.

     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:

	   sendmail_enable="NO"
	   inetd_flags="-wW -a 192.168.11.23"
	   portmap_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 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	portmap(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/192.168.11.100/stand
	   cp /stand/sysinstall	/data/jail/192.168.11.100/stand

     Now start 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 /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: portmap_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-
	       tem
	   +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	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 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.  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 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:

	   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.  Cur-
     rently 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 unreliable 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	on each	boot
     using sysctl.conf(5).  Just add the following line	to /etc/sysctl.conf:

	   jail.set_hostname_allowed=0

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

   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.

     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.

     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.

     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.

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

HISTORY
     The jail command 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 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(8) which is easily configurable.

FreeBSD	9.3		       December	12, 2001		   FreeBSD 9.3

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+4.9-RELEASE>

home | help