jail(8)

NAME

jail - imprison process and its descendants

SYNOPSIS

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

DESCRIPTION

The jail utility imprisons a process and all future descen

dants.

The options are as follows:

-i Output the jail identifier of the newly

created jail.

-J jid_file Write a JidFile, like a PidFile, contain

ing jailid,

path, hostname, ip and command used to

start the 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 lo

gin's default
values. USER is set to the target login.

TERM is
imported from the current environment.

The environment variables from the login class capa

bility
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 privi

lege), or to
create a ``virtual system image'' running a variety of dae

mons 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 docu

ments the configuration steps necessary to support either of these steps,

although 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 set up a jail directory tree con

taining an
entire FreeBSD distribution:

D=/here/is/the/jail
cd /usr/src
mkdir -p $D
make world DESTDIR=$D
make distribution DESTDIR=$D
mount_devfs devfs $D/dev

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 modify

ing 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 work

ing, 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 ad

dress, and hostname.

Setting up the Host Environment

First, you will want to set up your real system's environ

ment 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:

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

uration files,
or to recompile the applications. The following frequently

deployed services must have their individual configuration files modi

fied 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 or

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

tempting to
serve NFS from the host environment may also cause confu

sion, 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 con

figured so
that it does not bind all IP addresses, which would result

in those services' also appearing to be offered by the jail environ

ments.

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 deliv

ered 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 ac

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

straining a particular application or for running a virtual server.

Start a shell in the jail:

jail /data/jail/192.168.11.100 testhostname

192.168.11.100 /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 warn

ings about

missing fstab (virtual server only)

+o Disable the port mapper (/etc/rc.conf: rpcbind_en

able="NO")

(virtual server only)

+o Configure /etc/resolv.conf so that name resolution

within the

jail will work correctly

+o Run newaliases(1) to quell sendmail(8) warnings.
+o Disable interface configuration to quell startup

warnings about

ifconfig(8) (network_interfaces="") (virtual serv

er only)

+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 configura

tion (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 envi

ronment 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 virtu

al 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 ac

cess 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 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) con

figuration
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 host

name or IP
address of the jailed environment, and log in using the ac

counts you created previously.

It is possible to have jails started at boot time. Please

refer to the
``jail_*'' variables in rc.conf(5) for more information.

The rc(8) jail
script provides a flexible system to start/stop jails:

/etc/rc.d/jail start
/etc/rc.d/jail stop
/etc/rc.d/jail start myjail
/etc/rc.d/jail stop myjail

Managing the Jail

Normal machine shutdown commands, such as halt(8), re

boot(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 accom

plish:

kill -TERM -1
kill -KILL -1

This will send the SIGTERM or SIGKILL signals to all pro

cesses 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

conjunction
with the one of the kill(1) commands above.

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 host

name 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:

security.jail.set_hostname_allowed=0

You can also list/kill processes based on their jail ID. To

show processes and their jail ID, use the following command:

ps ax -o pid,jid,args

To show and then kill processes in jail number 3 use the

following commands:

pgrep -lfj 3
pkill -j 3

or:

killall -j 3

Sysctl MIB Entries

Certain aspects of the jail containments environment may be

modified from
the host environment using sysctl(8) MIB variables. Cur

rently, these
variables affect all jails on the system, although in the

future this
functionality may be finer grained.

security.jail.allow_raw_sockets

This MIB entry determines whether or not prison root is

allowed to
create raw sockets. Setting this MIB to 1 allows util

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

security.jail.enforce_statfs

This MIB entry determines which information processes

in a jail are
able to get about mount-points. It affects the be

haviour of the
following syscalls: statfs(2), fstatfs(2), getfsstat(2)

and
fhstatfs(2) (as well as similar compatibility

syscalls). When set
to 0, all mount-points are available without any re

strictions. When
set to 1, only mount-points below the jail's chroot di

rectory are
visible. In addition to that, the path to the jail's

chroot directory is removed from the front of their pathnames.

When set to 2
(default), above syscalls can operate only on a mount

point where
the jail's chroot directory is located.

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 rely

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

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 de

fault, 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 sock

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

terfere with)
processes outside of the jail, and in other jails. As

such, this
functionality is disabled by default, but can be en

abled by setting
this MIB entry to 1.

security.jail.chflags_allowed

This MIB entry determines how a privileged user inside

a jail will
be treated by chflags(2). If zero, such users are

treated as
unprivileged, and are unable to set or clear system

file flags; if
non-zero, such users are treated as privileged, and may

manipulate
system file flags subject to the usual constraints on
kern.securelevel.

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.

SEE ALSO

killall(1), newaliases(1), pgrep(1), pkill(1), ps(1), ch

root(2), jail(2),
jail_attach(2), procfs(5), rc.conf(5), sysctl.conf(5), de

vfs(8), halt(8),
inetd(8), jexec(8), jls(8), mount_devfs(8), named(8), re

boot(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 environ

ment.

BUGS

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

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.

BSD August 7, 2005

BSD