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

FreeBSD Manual Pages

  
 
  

home | help
JAIL(8)			    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.

       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 en-
       tire 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

       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 ad-
       dress.  Substitute below	as needed with your own	directory, IP address,
       and hostname.

       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
       listen 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"
	     rpcbind_enable="NO"

       192.168.11.23 is	the native IP address for the host system, in this ex-
       ample.  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
       configured--for some this is possible through the rc.conf(5) flags  en-
       tries,  for  others it is not possible without munging the per-applica-
       tion configuration 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
       configuration files, in most cases it is	easier to simply run the  dae-
       mons  in	 jails	only,  and not in the host environment.	 Attempting to
       serve NFS from the host environment may also cause confusion, and  can-
       not  be	easily reconfigured to use only	specific IPs, as some NFS ser-
       vices 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  re-
       sult  in	 those services	also appearing to be offered by	the jail envi-
       ronments.

       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  re-
       duce  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  in-
       terface	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  con-
       figuration  to  set various configuration options, or perform these ac-
       tions manually by editing /etc/rc.conf, etc.

	     	 Create	an empty /etc/fstab to quell  startup  warnings	 about
		 missing fstab
	     	 Disable the port mapper (/etc/rc.conf:	rpcbind_enable="NO")
	     	 Run newaliases(1) to quell sendmail(8)	warnings.
	     	 Disable  interface  configuration  to	quell startup warnings
		 about ifconfig(8) (network_interfaces="")
	     	 Configure /etc/resolv.conf so that name resolution within the
		 jail will work	correctly
	     	 Set a root password, probably different from  the  real  host
		 system
	     	 Set the timezone
	     	 Add accounts for users	in the jail environment
	     	 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
       reasons	why  this  is a	good idea.  If you do decide to	set this vari-
       able, 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
       processes  running  within  the jail using ps(1), with the `J' flag ap-
       pearing 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 host-
       name or IP address of the jailed	environment, and log in	using the  ac-
       counts 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.  To
       kill processes from outside the jail, use the jexec(8) utility in  con-
       juction	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 vari-
       able 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:

	     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 disabled in environments where	privileged ac-
	    cess to jails is given out to untrusted parties.

       security.jail.socket_unixiproute_only
	    The	jail functionality binds an IPv4 address  to  each  jail,  and
	    limits  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,  processes	 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 im-
	    plementation, 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
       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)

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  in-
       formation  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 facili-
       tate building a safe host environment such that host daemons do not im-
       pose  on	 services  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.

GNU				 April 8, 2003			       JAIL(8)

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

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=jail&manpath=FreeBSD+5.1-RELEASE>

home | help