Building from source

The build produces an installable ISO from the same sources the project maintains. It is the supported way to get an image at the moment, since no release has been published yet.

Build host

The build host must run the same FreeBSD version as the target. This is not a stylistic preference — ignoring it produced three kernel panics during development. The customisation stage chroots into the target root and runs zpool there, which autoloads openzfs.ko from inside the chroot: the freshly built module for one FreeBSD version gets loaded into the running kernel of another, and the vnode operation vector layout does not match.

Practical requirements, measured rather than guessed:

FreeBSD	stable/15, matching the target
CPU	24 cores is comfortable; fewer works, slower
RAM	40 GB. Rust alone will exhaust 16 GB
Disk	320 GB. 120 GB is not enough
Swap	16 GB on a real partition

About the disk: each make release leaves roughly 1.3 GB behind in _BE/release and nothing removes it. When the partition filled during development, the build failed after 4 hours 50 minutes on seven apparently unrelated ports — the real cause was a single ENOSPC, visible only in dmesg. Use tools/prune-builds.sh and check df -h / before starting.

Building

pkg install -y git gmake
git clone https://github.com/bsdnas/core-build.git
cd core-build
git checkout bsdnas
make bootstrap-pkgs
make checkout
make release

make checkout pulls the other repositories — the FreeBSD base fork, the middleware, the web interface — at the branches pinned in build/profiles/freenas/repos.pyd. The ports tree is not forked: the quarterly branch from FreeBSD upstream is used directly, with the NAS-specific ports overlaid from the middleware repository.

A complete build takes a few hours. The result is an ISO in freenas/_BE/objs/.

Repository layout

repository	what it is
core-build	the build system, profiles, tooling, documentation
os	FreeBSD base with the NAS patch set, rebased onto stable/15
middleware	middleware, installer, NAS ports
webui	the web interface

Keeping up with upstream

The point of the project is that the fork does not fall behind, so the tooling for that is part of the repository rather than someone's habit:

tools/watch-upstream.sh          report what moved upstream
tools/watch-upstream.sh --ack    mark the current state as reviewed
tools/prune-builds.sh --apply    remove old build artefacts
tools/acceptance.sh install      install in a VM and verify through the API

The watcher tracks four things: new commits on FreeBSD stable/15 under the patch set, FreeBSD security advisories, the opening of the next quarterly ports branch, and OpenZFS releases. It reports; a human decides. It deliberately does not open pull requests — conflict resolution during a rebase is not something to automate, and getting it wrong once already cost a build.