Source: https://mayphus.org/a-tiny-freebsd-jail-doc-fix/
Title: A tiny FreeBSD jail doc fix
Metadata: {"date":"2026-05-29T00:00:00Z","kind":"article","language":"en","locale":"en","route":"/a-tiny-freebsd-jail-doc-fix/","slug":"a-tiny-freebsd-jail-doc-fix","tags":["freebsd","jails","docs"],"type":"article"}

I submitted a small FreeBSD Handbook patch for the NullFS thin-jail recipe. It addresses a specific problem: after following the documented layout, some relative symlinks inside the jail point at the wrong tree.

## Why the links break

The setup separates a reusable base from a per-jail skeleton. Most of the release can be shared, while local state lives in the skeleton. But files moved into that skeleton can still contain relative symlinks written for the normal FreeBSD filesystem layout.

For example, a certificate link under `/etc/ssl/certs` can contain the target `../../../usr/share/certs/...`. The target is resolved from the link’s containing directory, not from the filesystem root.

```text
Normal system
/etc/ssl/certs
  + ../../../usr/share/certs/...
  → /usr/share/certs/...

Thin-jail skeleton
/skeleton/etc/ssl/certs
  + ../../../usr/share/certs/...
  → /skeleton/usr/share/certs/...
```

The shared files are at `/usr/share`, not `/skeleton/usr/share`. A jail can therefore look mostly correct while containing broken certificate links, which can make basic operations such as package bootstrapping fail.

## A bridge back to the shared base

The patch leaves the existing relative links intact. It adds two bridge symlinks inside the skeleton instead:

```sh
cd /usr/local/jails/templates/...-RELEASE-skeleton/usr
ln -s ../../usr/share share
ln -s ../../usr/sbin sbin
```

Here `...-RELEASE-skeleton` is a placeholder for the release-specific skeleton directory from the recipe, not a literal directory name.

The resulting path is:

```text
/skeleton/usr/share
        → ../../usr/share
        → /usr/share
```

With that bridge, the certificate link reaches the shared base without being rewritten. The `sbin` bridge covers the same class of problem for paths such as `/etc/rmt`.

## Public patch record

- [FreeBSD bug 280339 — broken symlinks inside a thin NullFS jail](https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=280339)
- [Original patch attachment](https://bugs.freebsd.org/bugzilla/attachment.cgi?id=253021&action=edit)
- [Rebased patch attachment](https://bugs.freebsd.org/bugzilla/attachment.cgi?id=271170&action=edit)

This page records a submitted documentation contribution; it does not establish that the patch has been merged. The public bug and attachments are the references for the patch’s history and current disposition.

This is the kind of fix I like: small, boring, and close to the failure. Documentation commands are code too. If someone copies a Handbook recipe exactly, the result should be a working jail.