Design
Philosophy
FreeBSD is the operating system. RealNAS is a management layer that runs on top of it. The distinction matters, and every architectural choice the project makes follows from it.
Most storage software disagrees with this division of labor. The conventional approach is to treat the underlying operating system as a substrate to be hidden, owned, and ideally replaced with a single managed image. The user interacts with the appliance; the appliance interacts with the kernel; the boundary between “the device” and “the OS” is intentionally blurry. That model has real engineering virtues. It also produces well-known pathologies: configuration files that get clobbered on upgrade, package managers that refuse to coexist with the host’s, recovery paths that demand vendor tools, and a steady drift away from anything resembling a general-purpose computer.
RealNAS refuses that trade. The operating system underneath is a real FreeBSD install, behaving like a real FreeBSD install, administrable with the documented FreeBSD toolchain. RealNAS is what you install onto it.
Five principles
1. FreeBSD owns the OS
Kernel, base system, and package set are managed by freebsd-update, pkg, and the standard ports/pkg infrastructure, not by RealNAS. The boot environment is managed by bectl. Services are enabled in rc.conf with sysrc. None of these tools are wrapped or shadowed. If you can administer FreeBSD, you can administer the host RealNAS runs on, because it is a host RealNAS runs on.
2. Manage, do not appropriate
Configuration files belong to the operator. RealNAS does not rewrite /etc/rc.conf; it adds keys with sysrc. It does not own smb4.conf; it writes an include file in a documented directory and references it. It does not own /etc/exports; it appends a stanza in a documented place. Where a templated drop-in pattern is impossible, the file is regenerated only after reading and re-emitting the operator’s changes.
3. Manual edits survive
An administrator who wants to make a quick change at the console should be able to do so, and the change should still be there after the next service restart, the next configuration save, and the next system update. The webui is a convenience for the common cases; it is not the only legitimate way to operate the system. A configuration that can be set only through the UI is a defect, not a feature.
4. Use what FreeBSD already has well
service, bectl, pkg, pw, zfs, zpool, smartmontools, ipfw, geom, nvmecontrol, periodic: these tools exist, they are tested, they are documented, and FreeBSD administrators know them. RealNAS wraps them where wrapping helps and stays out of the way where it does not. It does not reimplement what the base system already does.
5. Reversible by hand
Everything RealNAS does should be undoable from a console session using documented FreeBSD commands. If a feature requires a proprietary recovery tool, it is the wrong feature. If a configuration cannot be inspected with cat, zfs get, or ifconfig, the storage of that configuration is wrong.
6. Boring on purpose
Storage software that people depend on should be uneventful. The architectural choices that make RealNAS pleasant for a home operator (standard ZFS, standard Samba and NFS, standard FreeBSD service model, standard update workflow) are the same choices that make it suitable for production deployments serving teams, departments, and regulated workloads. There is no “home edition.” There is no “enterprise edition.” There is one piece of software, designed to be durable, predictable, and inspectable at any scale.
What this rules out
RealNAS is not, and will not become:
- An appliance. No custom installer, no signed image trains, no requirement that the host be set up a particular way before installation.
- A kernel fork. RealNAS runs on the FreeBSD kernel that FreeBSD publishes. There is no patched kernel, no out-of-tree driver shipped as the default storage path, no GPL workaround.
- An operating system distribution. RealNAS does not ship a base system. It ships a daemon, a UI, and a small handful of supporting packages.
- A managed service. The default deployment is on hardware the operator owns, on a network the operator controls. Any hosted offering will be additive and clearly labeled.
Why the discipline matters
Software that respects the OS underneath it is software you can keep running. When the project that maintains an appliance loses interest, drops support for your hardware, or pivots in a direction you cannot follow, the OS is locked to a single vendor's release schedule and the data above it is locked to that OS. The drives spin and the bits are intact; the management plane is silent. The data is fine; the door is closed.
The opposite posture (FreeBSD owns the OS, RealNAS is a tenant) means RealNAS’s health and your storage’s health are two separate questions. If RealNAS stalls, FreeBSD still updates. If RealNAS is removed entirely, zpool import still works, smbd still serves, and nfsd still exports. The management layer earns its keep by being convenient. It does not earn its keep by being indispensable.
If a design decision can be defended only by “but appliances do it this way,” it is the wrong decision for RealNAS.