Source: https://mayphus.org/systems-freebsd-jails/
Title: Understanding a FreeBSD jail's boundaries
Metadata: {"kind":"page","language":"en","route":"/systems-freebsd-jails/","tags":["systems","learning","freebsd","jails"],"type":"page"}

Understanding a FreeBSD jail's boundaries

## Goal and environment

Learn to draw the boundary between a FreeBSD host and a jail, then check which parts of that drawing are supported by observations. Start with [reading a FreeBSD system](/systems-freebsd-base/) and the [systems guide](/understanding-computer-systems/).

This chapter targets **FreeBSD 15.1-RELEASE**. The [official support table](https://www.freebsd.org/security/) and current FreeBSD manuals were checked on 8 October 2026. **The exercises are proposed and unexecuted on FreeBSD.** No jail was created or tested while preparing this chapter. Use a disposable VM you control; an ordinary fresh VM with no jails is a valid starting point. No administrator privileges are required to complete the reasoning exercise. If inspection is denied, stop that command and record the restriction.

## Draw the kernel boundary first

A jail groups processes under restrictions enforced by the host's kernel. It does not boot an independent guest kernel as a conventional virtual machine does. Its userland files can look like a whole operating system while kernel responsibility remains on the host. A jail therefore does not remove the need to maintain and secure the host. Permissions, exposed devices and delegated capabilities affect the boundary. The [`jail(8)` manual](https://man.freebsd.org/cgi/man.cgi?format=html&query=jail&sektion=8) describes those controls.

For a drawing, put the kernel below two columns: host processes and jail processes. Add the jail's filesystem root and network configuration, but do not draw a second kernel. Then write three questions: who updates the shared kernel, which host files are exposed, and what traffic can reach the jail? A diagram that cannot answer those questions is not yet an operating plan.

## Separate storage layout from networking

A thick jail has its own installed userland tree. A thin layout shares some base files while retaining separate writable state. That storage choice is independent of VNET: VNET supplies a separate network stack, and can accompany either layout. A shared-stack jail and a VNET jail therefore need different network reasoning. Consult the [Handbook's jail types and networking sections](https://docs.freebsd.org/en/books/handbook/jails/).

Do not infer Internet exposure from the word “jail.” Interface attachment, routes, firewall rules, application listeners and host forwarding determine reachability. Likewise, a separate filesystem root does not tell you whether a directory is backed by a private dataset or a shared mount. These are configuration questions, not properties you can establish from a hostname.

## Exercise: identify the view you are observing

**FreeBSD 15.1, read-only, ordinary account:**

```sh
uname -s
freebsd-version -u
sysctl -n security.jail.jailed
jls -h jid name path
```

The first two commands identify the OS and installed userland. The `security.jail.jailed` value normally distinguishes an unjailed process (`0`) from a jailed one (`1`). `jls` requests a header and the visible active jails' identifier, name and root path. Its parameters and selection behavior are documented in [`jls(8)`](https://man.freebsd.org/cgi/man.cgi?format=html&query=jls&sektion=8).

On a fresh host with no active jails, expect no jail rows. That is a successful observation; do not create a jail just to fill the table. An inspection inside a jail has a restricted perspective and is not an inventory of the whole host. Existing paths and names can reveal private deployment details, so keep the raw output local.

Record whether the observation came from a host or jail. For each visible row, explain that the JID identifies a running jail instance and the path describes its filesystem root from the reporting context. Do not assume a numeric JID is a permanent application identity. If the commands fail, preserve the error category and consult that VM's local manual rather than copying commands for a different release.

## Exercise: trace a relative path on paper

My [small Handbook documentation fix](/a-tiny-freebsd-jail-doc-fix/) concerned certificate symlinks in a NullFS thin-jail layout. Moving a directory into a skeleton changed where existing relative targets resolved. The published note explains the specific layout and patch; it does not establish that every thin jail has that problem.

Without changing files, draw these two locations:

```text
/etc/ssl/certs
/skeleton/etc/ssl/certs
```

Now resolve the same illustrative target, `../../../usr/share/certs`, relative to each containing directory. Walk up three levels before walking down into `usr/share/certs`. The first reaches `/usr/share/certs`; the second reaches `/skeleton/usr/share/certs`. Expected observation: unchanged link text can refer to a different place after its containing directory moves.

This paper exercise tests path reasoning, not certificate validation or a running jail. Actual mounts and additional symlinks can change the final destination. Do not apply the historical patch blindly to a newer recipe; inspect the current layout first.

## Lifecycle includes data and dependencies

Think through creation, start, operation, stop and removal as separate events. Stopping processes does not mean application data has been deleted. Removing a filesystem is a different, potentially destructive action. A usable plan must also cover service startup, mounted data, backup restoration, and matching host/userland compatibility. This chapter intentionally supplies no production creation or removal commands.

Before any later disposable build, write down the VM snapshot or recovery method, the intended jail release, where writable data will live, which network boundary is intended, and what result would justify proceeding. A shared kernel means release compatibility must be checked in official documentation, not inferred from a working shell prompt. Memory and CPU consumption also need explicit consideration; isolation is not an unlimited resource budget.

The finished exercise is an annotated boundary diagram and a short evidence record, including unknowns. Continue to [hardware and boot](/systems-hardware-boot/) for the layers below the kernel. Nothing here claims a completed FreeBSD-on-NanoPi R2S experiment or a security certification for an application deployed in a jail.