Home / 2026-05-29

I made a small FreeBSD Handbook patch for the NullFS thin-jail recipe. It is not a big patch, but it fixes a real footgun: after following the documented layout, some relative symlinks inside the jail point at the wrong tree.

The thin-jail setup splits a reusable base from a per-jail skeleton. That is the useful part: most of the release can be shared, while local state lives in the skeleton. The problem appears when files moved into the skeleton still contain relative symlinks that were written for the normal FreeBSD filesystem layout.

One example is under /etc/ssl/certs. Certificate links can point toward paths like:

../../../usr/share/certs/...

In a normal system that is fine. In the thin-jail skeleton, the path is resolved from inside /skeleton/etc/ssl/certs, so it lands under:

/skeleton/usr/share/...

But the shared files are really in /usr/share, not /skeleton/usr/share. The result is a jail that looks mostly correct but has broken certificate links, which can make basic things like package bootstrapping fail.

My patch does not rewrite all of those links. Instead it adds small bridge symlinks inside the skeleton:

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

That makes /skeleton/usr/share resolve back to the shared base /usr/share, so existing relative links keep working. The sbin link covers the same class of problem for paths such as /etc/rmt.

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.