Chapter 17. Jails and Containers

A thick jail is a traditional form of FreeBSD Jail. In a thick jail, a complete copy of the base system is replicated within the jail’s environment. This means that the jail has its own separate instance of the FreeBSD base system, including libraries, executables, and configuration files. The jail can be thought of as an almost complete standalone FreeBSD installation, but running within the confines of the host system. This isolation ensures that the processes within the jail are kept separate from those on the host and other jails.

Advantages of Thick Jails:

Disadvantages of Thick Jails:

A thin jail shares the base system from a template, using either OpenZFS snapshots or NullFS mounts. Only a minimal subset of the base system is duplicated for each thin jail, resulting in less resource consumption compared to a thick jail. The two mechanisms behave differently once the jails exist. With the OpenZFS method, each thin jail is created as a clone of a template snapshot: an independent copy-on-write copy that shares unchanged blocks with the template but diverges as it is modified. Later changes to the template do not propagate to existing clones, and each clone is maintained and updated individually, much like a thick jail. With the NullFS method, each thin jail mounts the template read-only at runtime, so the base system is shared live and updating the template updates every jail that mounts it. This shared, read-only base is also what gives NullFS thin jails less isolation and independence than thick jails, since changes in the shared components affect every jail using them simultaneously.

In summary, a FreeBSD Thin Jail is a type of FreeBSD Jail that replicates a substantial portion, but not all, of the base system within the isolated environment.

Advantages of Thin Jails:

Disadvantages of Thin Jails:

A service jail shares the complete filesystem tree directly with the host (the jail root path is /) and as such can access and modify any file on the host, and shares the same user accounts with the host. By default it has no access to the network or other resources which are restricted in jails, but they can be configured to re-use the network of the host and to remove some of the jail-restrictions. The use case for service jails is automatic confinement of services/daemons inside a jail with minimal configuration, and without any knowledge of the files needed by such service/daemon. Service jails are available since FreeBSD 15.0.

Advantages of Service Jails:

Disadvantages of Service Jails:

Most of the configuration of jails which is discussed below is not needed for service jails. To understand how jails work, it is recommended to understand those configuration possibilities. The details about what is needed to configure a service jail are in the Service Jails section.

A FreeBSD VNET jail is a virtualized environment that allows for the isolation and control of network resources for processes running within it. It provides a high level of network segmentation and security by creating a separate network stack for processes within the jail, ensuring that network traffic within the jail is isolated from the host system and other jails.

In essence, FreeBSD VNET jails add a network configuration mechanism. This means a VNET jail can be created as a Thick or Thin Jail.

A FreeBSD Linux Jail is a feature in the FreeBSD operating system that enables the use of Linux binaries and applications within a FreeBSD jail. This functionality is achieved by incorporating a compatibility layer that allows certain Linux system calls and libraries to be translated and executed on the FreeBSD kernel. The purpose of a Linux Jail is to facilitate the execution of Linux software on a FreeBSD system without needing a separate Linux virtual machine or environment.

The jail(8) utility manages jails.

To start jails when the system boots, run the following commands:

By default every jail with an entry in the configuration files is started at boot. To start only selected jails, list their names in jail_list:

The names in jail_list are separated by spaces and must match the jail names defined in /etc/jail.conf or /etc/jail.conf.d/. Only the listed jails are started at boot, and they are started in the order given, so any jail left out of jail_list has to be started by hand. When jail_list is left empty, all jails defined in the configuration files are started.

To stop the jails in the reverse of their jail_list order at shutdown, set jail_reverse_stop:

Networking for FreeBSD jails can be configured several different ways:

There is no specific place to put the files for the jails.

Some administrators use /jail, others /usr/jail, and still others /usr/local/jails. In this chapter /usr/local/jails will be used.

Apart from /usr/local/jails other directories will be created:

When using OpenZFS, execute the following commands to create datasets for these directories:

Creating a separate child dataset per jail is what later enables per-jail snapshots, clones, quotas, and dataset delegation. Because each jail directory is then its own dataset, OpenZFS can both cap and guarantee its disk use with the quota and reservation properties; see Jail Resource Limits.

When using UFS, execute the following commands to create the directories:

There are two ways to configure jails.

The first one is to add an entry for each jail to the file /etc/jail.conf. The other option is to create a file for each jail in the directory /etc/jail.conf.d/.

In case a host system has few jails, an entry for each jail can be added in the file /etc/jail.conf. If the host system has many jails, it is a good idea to have one configuration file for each jail in the /etc/jail.conf.d/ directory.

The files in /etc/jail.conf.d/ must have .conf as their extension and have to be included in /etc/jail.conf:

A typical jail entry would look like this:

In principle, a jail only needs a hostname, a root directory, an IP address, and a userland.

The userland for the jail can be obtained from the official FreeBSD download servers.

Execute the following command to download the userland:

Once the download is complete, it will be necessary to extract the contents into the jail directory.

Execute the following commands to extract the userland into the jail’s directory:

With the userland extracted in the jail directory, it will be necessary to copy the timezone and DNS server files:

With the files copied, the next thing to do is update to the latest patch level by executing the following command:

The last step is to configure the jail. It will be necessary to add an entry to the configuration file /etc/jail.conf or in jail.conf.d with the parameters of the jail.

An example would be the following:

Execute the following command to start the jail:

More information on how to manage jails can be found in the section Jail Management.

The fetch-and-extract procedure shown above is the traditional way to populate a jail’s root directory, but it is not the only one. The same userland can be installed with bsdinstall(8), from base-system packages, or from a locally built source tree.

bsdinstall(8) provides a dedicated jail target that sets up a new userland at the given directory for use with jail(8). It fetches and extracts the distribution sets without installing a kernel, skipping the disk partitioning and network steps of a normal installation, which makes it a one-command, scriptable alternative to the manual fetch and tar(1) sequence:

The jail target installs the base distribution (base.txz) by default. On FreeBSD 15.0 and later bsdinstall(8) can also populate the root from base-system packages with its pkgbase target; the pkg-based method is described next.

Starting with FreeBSD 15.0 the base system is also published as packages, so a jail userland can be installed entirely with pkg(8) from the FreeBSD-base repository. Point pkg(8) at the jail’s root directory with the global --rootdir option and install the jail variant of the base set:

Use FreeBSD-set-minimal-jail instead of FreeBSD-set-base-jail for a minimal userland. A jail installed this way is afterwards patched and upgraded with pkg(8) rather than freebsd-update(8); see Upgrading pkgbase Jails.

A userland built from a source tree can be installed into a jail’s root directory with the DESTDIR variable, which is the way to run a -STABLE or custom-built userland in a jail. After building the world, install it and the remaining distribution files into the jail directory:

make distribution installs the default configuration files under the jail’s /etc and is run only once, when populating the jail; repeating it during an update would overwrite the configuration inside the jail. To update such a jail from source, follow the same sequence as for the host: run installworld with the same DESTDIR, merge the configuration files with etcupdate -D pointed at the jail’s root directory, and remove obsolete files and libraries with make delete-old delete-old-libs, again with the same DESTDIR, rather than using freebsd-update(8). See Updating FreeBSD from Source for the complete source-update procedure.

Once a thick jail is fully configured, with packages installed, services enabled, and local configuration in place, it can serve as a template image: a template from which many identical jails are deployed almost instantly.

On OpenZFS this is done by snapshotting the configured jail’s dataset and cloning it. This requires the source jail to live on its own dataset, so create it with zfs create rather than the mkdir used in the classic-jail procedure above:

Stop the jail before snapshotting so the image is consistent, then snapshot and clone the dataset once for each new jail:

On a UFS host, copy the configured jail’s directory tree instead:

Each clone needs its own entry in /etc/jail.conf, or in jail.conf.d, with a unique name, path, and IP address. Because the path and host.hostname parameters in the example above are derived from the block name with ${name}, only the block name and the address differ:

A template-image clone differs from a thin jail (Thin Jails). A thin jail keeps sharing a read-only base and is maintained once at the template, whereas each template-image clone is a full, independently writable copy that is patched and upgraded on its own as described in Jail Upgrading. An OpenZFS clone starts as a space-efficient copy-on-write copy that shares blocks with the snapshot, and it keeps a dependency on that origin snapshot until zfs promote severs it. For a fully independent copy, or to replicate a jail to another pool or host, use zfs send piped to zfs receive instead of zfs clone.

Due to the good integration between FreeBSD and OpenZFS it is very easy to create new Thin Jails using OpenZFS Snapshots.

To create a Thin Jail using OpenZFS Snapshots the first step is to create the jail directory tree by following the instructions in Setting Up the Jail Directory Tree.

Next, create a template. Templates will only be used to create new jails. For this reason they are created in "read-only" mode so that jails are created with an immutable base.

To create the dataset for the template, execute the following command:

Then execute the following command to download the userland:

Once the download is complete, it will be necessary to extract the contents in the template directory by executing the following command:

With the userland extracted in the templates directory, it will be necessary to copy the timezone and DNS server files to the template directory by executing the following command:

The next thing to do is update to the latest patch level by executing the following command:

Once the update is finished, the template is ready.

To create an OpenZFS Snapshot from the template, execute the following command:

Once the OpenZFS Snapshot has been created, infinite jails can be created using the OpenZFS clone function.

To create a Thin Jail named thinjail, execute the following command:

The last step is to configure the jail. It will be necessary to add an entry to the configuration file /etc/jail.conf or in jail.conf.d with the parameters of the jail.

An example would be the following:

Execute the following command to start the jail:

More information on how to manage jails can be found in the section Jail Management.

A jail can be created with reduced duplication of system files by using the Thin Jail technique and using NullFS to selectively share specific directories from the host system into the jail.

The first step is to create the dataset to save the template, execute the following command if using OpenZFS:

Or this one if using UFS:

Then execute the following command to download the userland:

Once the download is complete, it will be necessary to extract the contents in the template directory by executing the following command:

Once the userland is extracted in the templates directory, it will be necessary to copy the timezone and DNS server files to the template directory by executing the following command:

With the files moved to the template, the next thing to do is update to the latest patch level by executing the following command:

In addition to the base template, it is also necessary to create a directory where the skeleton will be located. Some directories will be copied from the template to the skeleton.

Execute the following command to create the dataset for the skeleton in case of using OpenZFS:

Or this one in case of using UFS:

Then create the skeleton directories. The skeleton directories will hold the local directories of the jails.

Execute the following commands to create the directories:

The next step is to create the symlinks to the skeleton by executing the following commands:

With the skeleton ready, it will be necessary to copy the data to the jail directory.

In case of using OpenZFS, OpenZFS snapshots can be used to easily create as many jails as necessary by executing the following commands:

In case of using UFS the cp(1) program can be used by executing the following command:

Then create the directory in which the base template and the skeleton will be mounted:

Add a jail entry in /etc/jail.conf or a file in jail.conf.d as follows:

Then create the /usr/local/jails/thinjail-nullfs-base.fstab file as follows:

The fstab file controls how mount_nullfs(8) presents the base template and the skeleton inside the jail. The base template is mounted read-only (ro) so that every NullFS jail shares one immutable copy of the base system. The per-jail skeleton is mounted read-write (rw), which is where each jail keeps its own writable /etc, /var, /usr/local, and other local directories. Because all jails share that single read-only base template, updating the one template updates every NullFS jail at once, in contrast to independent OpenZFS clones which must each be updated separately.

Execute the following command to start the jail:

Wiring up an epair and attaching it to the bridge by hand in exec.prestart and exec.poststop, as shown above, becomes tedious across many jails. The base system ships a helper script, /usr/share/examples/jails/jib, that performs the same plumbing automatically.

Reference it from the jail’s hooks instead of the five hand-rolled ifconfig(8) lines:

jib addm creates an epair whose host side is named e0a_<name> and whose jail side is e0b_<name>, then attaches the host side to a bridge that it creates automatically, named after the member interface (for em0 the bridge is em0bridge). Name that jail side in vnet.interface. When the jail stops, jib destroy removes the epair. The script also provides a jib show subcommand to list the interfaces it manages.

The third networking mode mentioned in the Networking overview uses netgraph(4) instead of bridge(4) and epair. The base system ships a second helper, /usr/share/examples/jails/jng, that builds an ng_bridge connected to an ng_eiface for each jail:

jng bridge creates the netgraph nodes and a jail-side interface named ng0_<name>, which is named in vnet.interface; jng shutdown tears the topology down when the jail stops. The result is functionally equivalent to the epair-and-bridge setup, but built on netgraph nodes rather than bridge(4).

Because devfs_ruleset = 5 exposes /dev/pf, a VNET jail can run its own firewall. Enable it inside the jail exactly as on any host, with pf_enable="YES" in the jail’s /etc/rc.conf and its own /etc/pf.conf.

Ruleset 5 does not expose /dev/bpf, however. A VNET jail that obtains its address over DHCP, for example with ifconfig_e0b_myjail="SYNCDHCP" in its /etc/rc.conf, runs dhclient(8), which needs bpf and therefore fails under ruleset 5. Following the recipe in Devfs Rulesets, define a custom ruleset in /etc/devfs.rules that starts from devfsrules_jail_vnet and additionally unhides the bpf devices:

After running service devfs restart on the host, point the jail at the new ruleset with devfs_ruleset = 101;.

To list the jails that are running on the host system, the command jls(8) can be used:

The output should be similar to the following:

jls(8) supports the --libxo argument, which through the libxo(3) library allows other types of formats to be displayed, such as JSON, HTML, etc.

For example, execute the following command to get the JSON output:

The output should be similar to the following:

The default listing is only a small part of what jls(8) can report. Add the -v flag for a verbose, multi-line summary of each jail that includes its state and its assigned cpuset ID:

Use -h to print a header line with the field names above the values of the requested parameters:

To query specific parameters of a single jail, name it with -j and list the parameters to print:

The output should be similar to the following:

Add -d to include jails that are shutting down, which are otherwise hidden while in the dying state:

service(8) is used to start, reboot, or stop a jail on the host.

For example, to start a jail, run the following command:

Change the start argument to restart or stop to perform other actions on the jail.

Stopping a jail is more than killing the processes inside it. When a jail is stopped, jail(8) first runs the commands in its exec.stop parameter — typically /bin/sh /etc/rc.shutdown — inside the jail so that its services shut down cleanly. It then sends SIGTERM to any processes still running in the jail and waits up to stop.timeout seconds (10 by default) for them to exit. Once that time has passed, the jail is removed, which kills whatever remains with SIGKILL. If stop.timeout is set to zero, no SIGTERM is sent and the jail is removed immediately. This is why a jail with a slow-stopping daemon can appear to hang for ten seconds while it stops; raise stop.timeout in /etc/jail.conf for a jail that runs a database or another service that needs longer to shut down gracefully.

Destroying a jail is not as simple as stopping the jail using service(8) and removing the jail directory and /etc/jail.conf entry.

FreeBSD takes system security very seriously. For this reason there are certain files that not even the root user can delete. This functionality is known as File Flags. On a jail whose files live on a UFS file system, these flags must be cleared before the jail directory can be removed.

The first step is to stop the desired jail executing the following command:

The second step is to remove these flags with chflags(1) by executing the following command, in which classic is the name of the jail to remove:

The third step is to delete the directory where the jail was:

The two steps above apply to a jail stored on a UFS file system. A jail backed by its own ZFS dataset — as created in Setting Up the Jail Directory Tree — is removed by destroying the dataset instead. Dataset destruction is not blocked by file flags, so the chflags(1) step is unnecessary in this case:

Add -r to also destroy any snapshots the dataset holds.

Finally, in either case, remove the jail entry in /etc/jail.conf or in /etc/jail.conf.d. For a NullFS thin jail, also delete its .fstab file and its now-empty mountpoint directory.

The pkg(8) tool supports the -j argument in order to handle packages installed inside the jail.

For example, to install www/nginx-lite in the jail, the next command can be executed from the host:

For more information on working with packages in FreeBSD, see Installing Applications: Packages and Ports.

Services inside a jail can be enabled and controlled from the host without first entering the jail with jexec(8). Both service(8) and sysrc(8) accept a -j argument that names the target jail by ID or name and operates on that jail’s rc(8) configuration.

Continuing the package example above, enable and start nginx in the classic jail directly from the host:

These commands have the same effect as running sysrc(8) and service(8) through jexec(8), but they keep host-side administration and scripting uniform with an unjailed system.

While it has been stated above that it is best to manage jails from the host system, a jail can be entered with jexec(8).

The jail can be entered by running jexec(8) from the host:

The -u flag selects the user to run as, resolving the name against the host password database. To resolve the user against the jail’s own password database instead, use -U. When no command is given, as here, jexec(8) starts that user’s login shell inside the jail. Add -l to run it in a clean login environment that keeps only HOME, SHELL, TERM, and USER, resets PATH to /bin:/usr/bin, and behaves like a fresh login; -d sets the working directory, which defaults to the jail root.

When gaining access to the jail, the message configured in motd(5) will be displayed.

To execute a command from the host system in a jail the jexec(8) can be used.

For example, to stop a service that is running inside a jail, the command will be executed:

From the host, the processes and sockets of every jail are visible and can be filtered by jail.

ps(1) accepts -J to restrict its output to a single jail, given by JID or name:

The output should be similar to the following, where the J in the STAT column marks a process that is running in a jail:

Use ps -J 0 to show only the host’s own processes. The jail and jid keywords can also be added to the -o output format to show which jail each process belongs to. For example, to list every process on the host together with its jail:

top(1) takes -J to filter its live display to one jail, which implies -j and adds the JID column:

sockstat(1) lists the sockets belonging to a jail with -j, which is the natural way to check which ports a jail’s daemons have actually bound after starting a service in it:

From inside a jail the picture is reversed: a jailed process sees only its own jail’s processes and sockets, never those of the host or of other jails.

The service(8) wrapper shown above is the usual way to run jails at boot, but jail(8) can also create, modify, and remove jails directly, which is useful for scripting and for testing a configuration without the rc framework.

Create a configured jail by name:

Remove a running jail; this also removes any child jails it created and kills the processes inside it:

The -m flag modifies the parameters of an already-running jail without restarting it. For example, to add a second IPv4 address to a running jail:

jail(8) notes that "Some parameters may not be changed on a running jail"; in practice this includes path and vnet, which require the jail to be restarted.

Finally, -e exhibits all configured non-wildcard jails and their parameters without creating, modifying, or removing anything, which is handy for verifying a configuration file. It takes a string used to separate the parameters:

A jail is largely self-contained, so backing one up or moving it to another host is mostly a matter of copying its files and its configuration.

Stop the jail first for a consistent copy; a ZFS-backed jail can instead be snapshotted while running. For a jail on its own ZFS dataset, take a recursive snapshot and stream it to the destination host:

The full mechanics of zfs-send(8) and zfs-receive(8), including incremental transfers, are covered in Replication.

For a jail on a UFS file system, use tar(1) with -p so that ownership, permissions, and file flags are preserved:

Extract the archive as root on the destination host with tar -xpf so the flags survive. dump(8) and restore(8) are an alternative when a jail occupies a dedicated UFS file system of its own; they operate on whole file systems, so they do not apply to the layout used in this chapter, where all jails are directories within one shared file system.

Finally, copy the jail’s block from /etc/jail.conf — or its file in /etc/jail.conf.d — to the new host, adjust any host-specific parameters such as interface, ip4.addr, or the bridge used by a VNET jail, and start the jail there.

Jails must be updated from the host operating system. The default behavior in FreeBSD is to disallow the use of chflags(1) in a jail. This will prevent the update of some files so updating from within the jail will fail.

To update the jail to the latest patch release of the version of FreeBSD it is running, execute the following commands on the host:

To upgrade the jail to a new major or minor version, first upgrade the host system as described in Performing Major and Minor Version Upgrades. Once the host has been upgraded and rebooted, the jail can then be upgraded.

For example, to upgrade the classic jail to 15.1-RELEASE, execute the following commands on the host:

Then, if it was a major version upgrade, reinstall all installed packages and restart the jail again. This is required because the ABI version changes when upgrading between major versions of FreeBSD.

From the host:

The thin jails created in Creating a Thin Jail Using OpenZFS Snapshots are OpenZFS clones of a template snapshot, but a clone is independent of that template once it exists. Refreshing the template does not update jails that were already cloned from it, and updating a clone does not update the template. There are therefore two ways to keep these jails current.

The first option is to update each clone in place with freebsd-update(8), exactly as for a classic jail, as described in Upgrading a Classic Jail or a Thin Jail using OpenZFS Snapshots. This is the simplest approach for a handful of jails, but every clone that is patched diverges from the template snapshot: the changed blocks are duplicated per jail, which erodes the space savings, and a major upgrade rewrites so much of the userland that most of the sharing is lost.

The second option keeps the sharing intact by refreshing the template and re-cloning. Update the template to the latest patch level on the host:

Then take a new snapshot and clone future jails from it:

Existing clones keep the base they were created from until they are re-created from the new snapshot. For a major or minor version upgrade, create a fresh template dataset for the new release following Creating a Thin Jail Using OpenZFS Snapshots, rather than upgrading the existing template in place, and clone new jails from its @base snapshot.

Since Thin Jails that use NullFS share the majority of system directories, they are very easy to update. It is enough to update the template. This allows updating multiple jails at the same time.

To update the template to the latest patch release of the version of FreeBSD it is running, execute the following commands on the host:

To upgrade the template to a new major or minor version, first upgrade the host system as described in Performing Major and Minor Version Upgrades. Once the host has been upgraded and rebooted, the template can then be upgraded.

Because the host was upgraded first, freebsd-update(8) with -b would otherwise detect the host’s new release rather than the template’s older one: -b reads the running version from the host’s uname -r, unlike -j, which detects the jail’s own userland. Pass --currently-running <template-release> so the template is patched from its actual release. The following example upgrades a template running 14.2-RELEASE to 14.3-RELEASE; substitute the releases that apply:

Jails installed from base packages, available from FreeBSD 15.0, are upgraded with pkg(8) against the FreeBSD-base repository rather than with freebsd-update(8).

The FreeBSD-base repository is defined in /etc/pkg/FreeBSD.conf but is disabled by default on FreeBSD 15.0, so enable it before upgrading.

From the host, point pkg(8) at the jail’s root directory with -r (--rootdir):

The same upgrade can be run from inside the jail with jexec(8) and a plain pkg upgrade:

pkg(8) performs a three-way merge on tagged configuration files under /etc. When a merge cannot be completed automatically it leaves the new version as <file>.pkgnew, and when it takes over a file that was not previously packaged it saves the old copy as <file>.pkgsave. Review /etc after an upgrade and reconcile any such files by hand. Do not run etcupdate(8) on a pkgbase system; pkg(8) handles configuration merging itself. See Updating and Upgrading FreeBSD for the host-side base-package workflow.

rctl(8) with pcpu caps how much CPU time a jail may consume, but it does not tie the jail to particular cores; cpuset(1) assigns specific cores instead.

Restrict a running jail to a set of CPUs by its name or JID:

Query the cores a jail is currently allowed to use with -g:

The assigned set is also reported in the cpuset column of jls -v. There is no jail.conf parameter for CPU affinity, so pin the jail at start time by running cpuset(1) from an exec.created or exec.poststart hook, both of which run in the host environment:

rctl(8) has no resource for filesystem space. When each jail lives in its own ZFS dataset, cap and guarantee its disk usage with ZFS quotas and reservations instead:

This requires the jail to be a dataset of its own. The ZFS thin jails created earlier already are, but the Classic Jail procedure creates the jail directory with mkdir inside the shared containers dataset, so create it with zfs create first for these commands to apply. See Setting Up the Jail Directory Tree for the dataset layout and zfs-set(8) for the quota and reservation properties.

The allow.* parameters are booleans that hand individual privileges to the jail. Per jail(8), "With the exception of allow.set_hostname and allow.reserved_ports, these boolean parameters are off by default", so a jail starts locked down and each capability must be granted explicitly.

Weigh each relaxation against what it exposes: allow.raw_sockets lets jailed processes forge packets, allow.chflags lets jailed root clear the immutable and append-only flags the host relies on, and allow.mount opens up the filesystem namespace.

Running an NFS server inside a jail, highlighted in the FreeBSD 14.0 release notes, needs allow.nfsd set, a VNET jail whose root directory is itself a filesystem mount point, and enforce_statfs not set to 0.

Databases and other software that rely on System V shared memory, semaphores, and message queues are controlled per module with the sysvmsg, sysvsem, and sysvshm parameters. Each takes one of three values: inherit makes all of the host’s IPC objects visible to the jail, new gives the jail its own private key namespace, and disable makes the related system calls fail.

For the classic case of running PostgreSQL in a jail, new is the right choice, giving the database its own shared-memory namespace without exposing the host’s:

The older allow.sysvipc parameter is deprecated. It is equivalent to setting all three module parameters to inherit, which shares the host-wide IPC namespace with the jail, so prefer the per-module parameters above.

allow.mount lets a jail mount filesystems, and a family of child parameters selects which types: allow.mount.devfs, allow.mount.fdescfs, allow.mount.fusefs, allow.mount.nullfs, allow.mount.procfs, allow.mount.linprocfs, allow.mount.linsysfs, allow.mount.tmpfs, and allow.mount.zfs. Per jail(8), each child "is effective only together with allow.mount and only when enforce_statfs is set to a value lower than 2". The convenience parameters mount.devfs, mount.fdescfs, and mount.procfs mount those filesystems for the jail automatically, and mount.fstab points at an fstab file of additional mounts.

The enforce_statfs parameter controls both which mount points a jail can see and, through the rule above, whether the allow.mount.* permissions take effect. It takes three values:

Because the allow.mount.* permissions require a value lower than 2, a jail that must mount its own filesystems is typically configured with enforce_statfs = 1.

The securelevel parameter sets the jail’s kern.securelevel and raises the kernel’s immutable-flag and device protections inside the jail. Per jail(8), "A jail never has a lower securelevel than its parent system, but by setting this parameter it may have a higher one". A network-facing jail can therefore run at a hardened securelevel = 3 while the host stays at its default.

A jail may itself create child jails, which is how nested or hierarchical jail hierarchies are built. The children.max parameter sets how many child jails a jail may create; it defaults to 0, meaning no child jails are allowed, and the read-only children.cur reports how many currently exist. A child can never exceed the privileges of its parent: per jail(8), "Jailed processes are not allowed to confer greater permissions than they themselves are given". This makes it possible to run a jail manager inside a jail.

By default a jail exists only while it has running processes; when its last process exits, the jail disappears. Setting the persist parameter, in the words of jail(8), "allows a jail to exist without any processes". This is what keeps a jail alive after it has been created empty and before anything is populated into it, and what anchors a VNET jail that only holds network state. A jail can be created empty and kept alive for experimentation:

Clear the flag with nopersist to let the jail be removed once idle again.

A jail’s userland may be older than the host kernel, but tools inside it still read the host’s version through uname(1) unless told otherwise. The osrelease parameter sets the string reported by the jail’s kern.osrelease and uname -r, and osreldate sets the number reported by kern.osreldate and uname -K. Setting them so that an older userland reports its own release keeps uname(1), sysctl(8) consumers, and version-sniffing build tooling behaving correctly, including freebsd-update(8) run inside the jail. Package management is unaffected either way, because pkg(8) derives its ABI from the ELF notes of the jail’s own binaries rather than from uname(1). This complements the rule that a jail’s userland can never be newer than the host kernel; see Jail Upgrading.

This method works on all supported releases of FreeBSD.

On the host, create the dataset to delegate and mark it as jailed:

Setting the jailed property tells ZFS that the dataset will be managed from inside a jail, so the host stops mounting it automatically.

Next, allow the jail to mount ZFS filesystems and attach the dataset when the jail is created. Add the following to the jail’s section in /etc/jail.conf:

The allow.mount.zfs permission takes effect only together with allow.mount and an enforce_statfs value below 2; see More Jail Options for the mount permissions and how they interact with enforce_statfs. Because a delegated dataset is detached when the jail stops, the exec.created hook re-attaches it on every start, where ${name} expands to the jail name. The same attachment can be performed against an already running jail with zfs jail <jid|name> zroot/jails/data.

Inside the jail, mount the delegated datasets and manage them like any other:

The jailed root user can create, snapshot, clone, and roll back datasets under the delegated tree, but the quota property of the delegated dataset can only be set from the host.

Starting with FreeBSD 15.0, jail(8) can attach datasets on its own, removing the need for the manual jailed and zfs jail steps. List the datasets to delegate in the zfs.dataset parameter:

jail(8) attaches each listed dataset when the jail starts, so the exec.created hook shown above is no longer needed. The parameter requires allow.mount.zfs to be set.

For unmaintained jail managers that do not yet understand zfs.dataset, the rc.d/jail startup script also honors the legacy variable jail_<jailname>_zfs_dataset in /etc/rc.conf.

The zfs.mount_snapshot parameter, available on FreeBSD 14.x and 15.x, lets jailed users reach snapshot contents without delegating a whole dataset. When set to 1, jailed users may read the contents of a filesystem’s snapshots under its .zfs/snapshot directory:

This is convenient for restoring individual files from host-taken snapshots. If allow.mount.zfs is also set, the snapshots may additionally be mounted inside the jail. The dataset’s snapdir property controls whether the .zfs directory is visible.