Design
Design Rules
RealNAS is a storage manager for FreeBSD, not a FreeBSD replacement. These rules define what RealNAS may own and what must remain ordinary FreeBSD state.
Many NAS appliances hide the operating system. The web interface becomes the product, and the image, updater, recovery path, package set, and service model belong to the vendor. That can simplify support, but it also makes the host harder to inspect and recover.
RealNAS keeps the boundary simple. The host is FreeBSD. RealNAS is installed on it.
Why FreeBSD
FreeBSD is not a default. It is the right operating system for serious storage, and RealNAS is built on it on purpose. NAS hosts want predictable kernels, mature networking, native ZFS, lightweight isolation, and an operator interface built around plain files in documented places. FreeBSD ships all of that as one coherent system, in the same source tree, under the same release engineering. RealNAS is the management layer that sits on top.
ZFS is part of the operating system
FreeBSD ships OpenZFS in the base system from 13.0 onward. Root-on-ZFS, boot environments through bectl, native send/receive, ARC tuning through sysctl, snapshot composition with boot environments, and pool import/export are part of how the OS works. The OpenZFS codebase is unified across platforms today, but on FreeBSD it is treated as a base-system citizen rather than a kernel module clipped onto an unrelated host. That shows up in the small things: how pools mount during boot, how snapshots compose with boot environments, how the shell treats ZFS as a first-class storage object rather than an add-on.
One operating system, not a stack of parts
ZFS, NFS, jails, pf, the rc system, the base networking stack, and the handbook all live in the same source tree and ship together. Services configure in rc.conf. Daemons start with service. Updates run through freebsd-update and pkg. The handbook documents the result. That coherence is the load-bearing reason FreeBSD is good for storage work, and it is why RealNAS does not need to invent platform abstractions to sit on top of the host.
Boring on purpose
A NAS wants predictable storage and predictable networking. It does not need a fast-moving application platform underneath it. FreeBSD changes slowly, breaks rarely, and keeps the operator close to documented files. RealNAS treats that as a feature.
Networking pedigree
NFS, SMB through Samba, iSCSI, VLANs, LAGG/LACP, routing, and packet filtering with pf are long-running strengths of FreeBSD. The kernel APIs that NAS protocols sit on have been hardened over decades of server use. The data moves through code that has had time to get boring.
Jails for adjacent services
Storage hosts often run a few contained services next to the data, such as replication helpers, monitoring agents, and lightweight tools. Jails are the BSD answer: low overhead, no external orchestrator, native to the operating system, and inspectable with standard tools. RealNAS does not ship its own container layer because FreeBSD already has one that fits the job.
Operational simplicity
Base OS, packages, ZFS, rc scripts, plain config files in documented places. The mental model an operator needs to run a RealNAS host is the FreeBSD mental model. There is no separate appliance vocabulary to learn, and the shell is always there.
Reviving the BSD roots of NAS
NAS work started as a BSD story. The operational habits that make storage work well are still BSD habits: slow kernels, careful update paths, clean rc, base-system ZFS, plain files. RealNAS is an attempt to continue that path. The management layer is designed for FreeBSD on purpose, and the rest of the system stays the rest of the system.
Design Rules
1. FreeBSD owns the host
The kernel, base system, and packages are managed by freebsd-update, pkg, and the standard ports/pkg tooling. Boot environments are managed by bectl. Services are enabled in rc.conf with sysrc. RealNAS can expose these operations in the UI, but the FreeBSD tools still do the work.
2. Use the expected files
RealNAS uses sysrc for service settings, Samba-supported generated configuration for SMB, middleware-owned generated exports for NFS, and documented include/drop-in paths only where the target service has a safe contract. Base files are not disposable templates.
3. Manual edits are allowed
An administrator can make a change at the console and keep it when the file is FreeBSD-owned or has a documented preserving drop-in. Generated RealNAS files are different: use the owning UI/API, an auxiliary field, or a documented include path.
4. Use the tools FreeBSD already has
RealNAS calls service, sysrc, bectl, pkg, freebsd-update, pw, zfs, zpool, smartctl, geli, geom, nvmecontrol, and other documented tools where those tools are the right interface. High-risk mutations go through named adapters with structured arguments.
5. Make removal possible
The system remains understandable if RealNAS is stopped or removed. ZFS pools import with zpool import. Local users remain local users. Generated service configuration can be inspected, and the underlying services are ordinary FreeBSD services.
6. Keep the core small
The default runtime covers storage, sharing, local identity, alerts, reporting, updates, boot environments, and WebUI management. Optional adjacent services such as HA, VM, jail/plugin, KMIP, VMware, Fibre Channel, and hardware-health stacks belong in explicit packages or tranches.
Operational Boundaries
| Question | Rule |
|---|---|
| Does FreeBSD already own this? | Use the FreeBSD tool or native binding, then tolerate out-of-band FreeBSD changes where possible. |
| Is this NAS orchestration state? | Store it in RealNAS SQLite state and render generated service config from that state. |
| Does a generated file have a safe include path? | Document and preserve the include/drop-in. If not, make the file explicitly RealNAS-owned. |
| Is the feature absent from default install? | Return a truthful disabled/degraded compatibility answer only if callers still need the namespace, and document it as deferred. |
Boundaries
RealNAS is not any of these things:
- A custom appliance image. There is no RealNAS installer ISO.
- A kernel fork. RealNAS runs on the FreeBSD kernel published by the FreeBSD project.
- A FreeBSD distribution. The project ships a daemon, a web UI, and supporting packages.
- A managed service. The default deployment runs on hardware you control.
Why this matters
Storage outlives projects. Hardware gets old, maintainers move on, vendors change priorities, and support windows close. If the NAS layer is the only practical way to update, recover, or inspect the host, that risk lands on the administrator.
RealNAS keeps the management layer separate from the data. If RealNAS is not running, FreeBSD still boots. If RealNAS is removed, ZFS still imports the pool.
If a feature makes the host harder to administer as FreeBSD, it needs a better reason to exist.