home | help
JAIL(8) 		     System Manager's Manual			 JAIL(8)

NAME
     jail -- imprison process and its descendants

SYNOPSIS
     jail path hostname ip-number command ...

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

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

EXAMPLES
   Setting up a Jail Directory Tree
     This shows how to setup a jail directory tree:

     D=/here/is/the/jail
     cd /usr/src
     make hierarchy DESTDIR=$D
     make obj
     make depend
     make all
     make install DESTDIR=$D
     cd etc
     make distribution DESTDIR=$D NO_MAKEDEV=yes
     cd $D/dev
     sh MAKEDEV jail
     cd $D
     ln -sf dev/null kernel

   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 listen
     on all local IP addresses for a service.  This means changing inetd 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"
	   syslogd_flags="-ss"

     192.169.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  config-
     ured--for	some  this is possible through the rc.conf(5) flags entries, for
     others it is not possible without munging the per-application 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
     syslogd(8), sendmail(8), named(8),  and  portmap(8).   While  sendmail  and
     named can be configured to listen only on a specific IP using their config-
     uration  files,  in  most	cases  it is easier to simply run the daemons in
     jails only, and not in the host environment.  Syslogd cannot be  configured
     to bind only a single IP, but can be configured to not bind a network port,
     using the ``-ss'' argument.  Attempting to serve NFS from the host environ-
     ment  may	also  cause  confusion, and cannot be easily reconfigured to use
     only specific IPs, as some NFS services are hosted directly from  the  ker-
     nel.   Any  third	party  network	software running in the host environment
     should also be checked and configured so that it does not bind all  IP  ad-
     dresses,  which would result in those services 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.)

     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 rc.conf, etc.

	   *   Create  an empty /etc/fstab to quell startup warnings about miss-
	       ing fstab
	   *   Disable the port mapper (rc.conf: portmap_enable="NO")
	   *   Run newaliases(1) to quell sendmail warnings.
	   *   Disable interface configuration to quell startup  warnings  about
	       ifconfig (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'd
     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  de-
     cide  to  set  this variable, it must be set before starting any jails, and
     once each boot.

	   # ifconfig ed0 inet alias 192.168.11.100 netmask 255.255.255.255
	   # 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 vari-
     ables cannot be set from within the jail, as they	are  global  across  all
     jails and the host environment.  However, it should all work properly.  You
     should  be  able  to  see inetd(8), syslogd(8), and other processes running
     within the jail using ps(1), with the  "J"  flag  appearing  beside  jailed
     processes.  You should also be able to telnet to the hostname or IP address
     of  the jailed environment, and log in using the acounts you created previ-
     ously.

   Managing the jail
     Normal machine shutdown commands, such as	halt(8),  reboot(8),  and  shut-
     down(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 "TERM" or "KILL" 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.  Currently 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 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) com-
     mand 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 unreliably by default.  To disable the setting of the host-
     name from within a jail, set the "jail.set_hostname_allowed"  sysctl  vari-
     able  in  the  host environment to 0, which will affect all jails.  You can
     have this sysctl set each boot using sysctl.conf(5).  Just add the  follow-
     ing line to sysctl.conf:

	   jail.set_hostname_allowed=0

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

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), send-
     mail(8), shutdown(8), sysctl(8), syslogd(8)

HISTORY
     The jail() function call 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 spe-
     cific 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 listen-
     ing  on all IPs (INADDR_ANY) will not bind on that address, which would fa-
     cilitate 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  ser-
     vices offered from inetd which is easily configurable.

FreeBSD 4.0			 April 28, 1999 			 JAIL(8)

home | help