14.3. Creating and Controlling Jails

14.3. Creating and Controlling Jails
Prev	Chapter 14. Jails	Next

Some administrators divide jails into the following two types: “complete” jails, which resemble a real FreeBSD system, and “service” jails, dedicated to one application or service, possibly running with privileges. This is only a conceptual division and the process of building a jail is not affected by it. When creating a “complete” jail there are two options for the source of the userland: use prebuilt binaries (such as those supplied on an install media) or build from source.

14.3.1. Installing a Jail

14.3.1.1. To install a Jail from the Internet

The bsdinstall(8) tool can be used to fetch and install the binaries needed for a jail. This will walk through the picking of a mirror, which distributions will be installed into the destination directory, and some basic configuration of the jail:

# bsdinstall jail /here/is/the/jail

Once the command is complete, the next step is configuring the host to run the jail.

14.3.1.2. To install a Jail from an ISO

To install the userland from installation media, first create the root directory for the jail. This can be done by setting the DESTDIR variable to the proper location.

Start a shell and define DESTDIR:

# sh
# export DESTDIR=/here/is/the/jail

Mount the install media as covered in mdconfig(8) when using the install ISO:

# mount -t cd9660 /dev/`mdconfig -f cdimage.iso` /mnt
# cd /mnt/usr/freebsd-dist/

Extract the binaries from the tarballs on the install media into the declared destination. Minimally, only the base set needs to be extracted, but a complete install can be performed when preferred.

To install just the base system:

# tar -xf base.txz -C $DESTDIR

To install everything except the kernel:

# for set in base ports; do tar -xf $set.txz -C $DESTDIR ; done

14.3.1.3. To build and install a Jail from source

The jail(8) manual page explains the procedure for building a jail:

# setenv D /here/is/the/jail
# mkdir -p $D      
# cd /usr/src
# make buildworld  
# make installworld DESTDIR=$D  
# make distribution DESTDIR=$D  
# mount -t devfs devfs $D/dev

	Selecting a location for a jail is the best starting point. This is where the jail will physically reside within the file system of the jail's host. A good choice can be `/usr/jail/jailname`, where `jailname` is the hostname identifying the jail. Usually, `/usr/` has enough space for the jail file system, which for “complete” jails is, essentially, a replication of every file present in a default installation of the FreeBSD base system.
	If you have already rebuilt your userland using `make world` or `make buildworld`, you can skip this step and install your existing userland into the new jail.
	This command will populate the directory subtree chosen as jail's physical location on the file system with the necessary binaries, libraries, manual pages and so on.
	The `distribution` target for make installs every needed configuration file. In simple words, it installs every installable file of `/usr/src/etc/` to the `/etc` directory of the jail environment: `$D/etc/`.
	Mounting the devfs(8) file system inside a jail is not required. On the other hand, any, or almost any application requires access to at least one device, depending on the purpose of the given application. It is very important to control access to devices from inside a jail, as improper settings could permit an attacker to do nasty things in the jail. Control over devfs(8) is managed through rulesets which are described in the devfs(8) and devfs.conf(5) manual pages.

14.3.2. Configuring the Host

Once a jail is installed, it can be started by using the jail(8) utility. The jail(8) utility takes four mandatory arguments which are described in the Section 14.1, “Synopsis”. Other arguments may be specified too, e.g., to run the jailed process with the credentials of a specific user. The command argument depends on the type of the jail; for a virtual system, /etc/rc is a good choice, since it will replicate the startup sequence of a real FreeBSD system. For a service jail, it depends on the service or application that will run within the jail.

Jails are often started at boot time and the FreeBSD rc mechanism provides an easy way to do this.

Configure jail parameters in jail.conf:

www {
    host.hostname = www.example.org;           # Hostname
    ip4.addr = 192.168.0.10;                   # IP address of the jail
    path = "/usr/jail/www";                    # Path to the jail
    devfs_ruleset = "www_ruleset";             # devfs ruleset
    mount.devfs;                               # Mount devfs inside the jail
    exec.start = "/bin/sh /etc/rc";            # Start command
    exec.stop = "/bin/sh /etc/rc.shutdown";    # Stop command
}

Configure jails to start at boot time in rc.conf:

jail_enable="YES"   # Set to NO to disable starting of any jails

The default startup of jails configured in jail.conf(5), will run the /etc/rc script of the jail, which assumes the jail is a complete virtual system. For service jails, the default startup command of the jail should be changed, by setting the exec.start option appropriately.

Note:

For a full list of available options, please see the jail.conf(5) manual page.

service(8) can be used to start or stop a jail by hand, if an entry for it exists in jail.conf:

# service jail start www
# service jail stop www

Jails can be shut down with jexec(8). Use jls(8) to identify the jail's JID, then use jexec(8) to run the shutdown script in that jail.

# jls
   JID  IP Address      Hostname                      Path
     3  192.168.0.10    www                           /usr/jail/www
# jexec 3 /etc/rc.shutdown

More information about this can be found in the jail(8) manual page.

Prev	Up	Next
14.2. Terms Related to Jails	Home	14.4. Fine Tuning and Administration