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)

     jail - imprison process and its descendants

     jail [-i] [-l -u username | -U username]
          path hostname ip-number command ...

     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.

     -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 your current environment.  The
                        environment variables from the login class capability
                        database for the target login are also set.

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

     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
     constrain a specific application (possibly running with privilege), or to
     create a ``virtual system image'' running a variety of daemons and
     services.  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 configuration steps necessary to support either of these
     steps, although the configuration steps may be refined based on local

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

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

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

     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
     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/, named for the jailed IP address.
     Substitute below as needed with your own directory, IP address, and

   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
     listen 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
     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 specified host IP address.  Other daemons will need to be manually
     configured--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 services must have their individual configuration
     files modified to limit the application to listening to a specific IP

     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
     services using rpc(3), such as rpcbind(8,) nfsd(8), and mountd(8).  In
     general, 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
     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 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
     interface 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
     particular 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
     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 (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
           +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
     application in the jail, substitute the command used to start the
     application 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 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
     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.  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 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 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
     following line to /etc/sysctl.conf:


   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 MIB entry determines whether or not processes within a jail are
          able to see data for all mountpoints.  When set to 1 (default), the
          getfsstat(2) system call returns only (when called by jailed
          processes) the data for the file system on which the jail's root
          vnode is located.  Note: this also has the effect of hiding other
          mounts inside a jail, such as /dev, /tmp, and /proc, but errs on the
          side of leaking less information.

          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 access to jails is given
          out to untrusted parties.

          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.

          This MIB entry determines whether or not processes within a jail
          have access to System V IPC primitives.  In the current jail
          implementation, 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
     settings.  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), 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)

     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.

     Jail currently lacks the ability 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 simplest answer is to
     minimize services offered on the host, possibly limiting it to services
     offered from inetd(8) which is easily configurable.

FreeBSD 11.0-PRERELEASE          April 8, 2003         FreeBSD 11.0-PRERELEASE


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

home | help