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.

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

docs.sk

comprehensive documentation repository

In section

See also