RealNAS

Technical

Architecture

RealNAS is two daemons, a web interface, a SQLite database, and a small set of Python bindings to the underlying operating system. Everything below that line is stock FreeBSD.

The control plane is intentionally boring. There is no orchestrator, no container runtime, no proprietary clustering layer, no message bus. A single Python daemon coordinates the work; a reverse proxy fronts a web UI; the system calls beneath are documented FreeBSD interfaces. The result is a system small enough to reason about and conservative enough to deploy on infrastructure people depend on.

Every piece in the stack below is independently maintained, independently deployed at production scale by organizations unrelated to this project, and independently documented in its own upstream. OpenZFS holds petabytes in production across operating systems and industries. Samba serves file shares for departments, hospitals, universities, and broadcasters. The FreeBSD NFS server has been load-bearing in research and engineering environments for decades. Python is Python. Nothing in the data path is an experiment.

Component map

flowchart TB Browser(["Web browser · operator"]) subgraph RealNAS [" RealNAS userspace "] direction TB Proxy["realnas-proxy
HTTP + WebSocket bridge
/api · /websocket"] WebUI["realnas-webui
Angular SPA
served as static files"] Daemon["realnasd · middlewared
Python daemon
plugins · event bus · SQLite"] end subgraph BSD [" FreeBSD "] direction TB PyBSD["py-bsd bindings
ZFS · devinfo · syscalls"] Tools["userspace utilities
zfs · zpool · pw · samba
nfsd · smartctl · bectl
pkg · freebsd-update"] Kernel(["FreeBSD kernel"]) end Browser -- "HTTPS / WebSocket" --> Proxy Proxy -- "static" --> WebUI Proxy -- "JSON-RPC + DDP" --> Daemon Daemon -- "ctypes" --> PyBSD Daemon -- "subprocess" --> Tools PyBSD --> Kernel Tools --> Kernel classDef edge fill:#ffffff,stroke:#d8d3c8,stroke-width:1px,color:#1a1a1a; classDef accent fill:#ffffff,stroke:#8a2424,stroke-width:1.5px,color:#1a1a1a; classDef kernel fill:#f4f0e6,stroke:#8a2424,stroke-width:1px,color:#1a1a1a,font-style:italic; class Browser edge; class Proxy,Daemon accent; class WebUI edge; class PyBSD,Tools edge; class Kernel kernel;
Request flow: browser to proxy, proxy to daemon, daemon to system

Pieces in detail

realnasd: the middleware daemon

A long-running Python process that owns the management API. It is a standard FreeBSD service, started by /usr/local/etc/rc.d/realnasd and enabled with sysrc realnasd_enable=YES. Its job is to register plugins (one per management domain: pool, dataset, snapshot, share, user, alert, etc.), expose them over a JSON-RPC and DDP-flavored WebSocket interface, persist non-OS state to a SQLite database, and emit events on configuration change.

Plugins are deliberately thin. A typical pool plugin issues zpool create, parses its output, updates a row in the local SQLite database, and emits an event. It does not maintain a parallel state machine of what the pool “should” look like. zpool already knows.

realnas-webui: the operator interface

An Angular single-page application served as static files. It speaks to the middleware over a WebSocket carrying JSON-RPC / DDP messages and is otherwise a thin presentation layer. The UI never reaches around the middleware to manipulate the OS directly.

realnas-proxy: the front door

A small HTTP reverse proxy that terminates TLS, serves the static SPA, and bridges the browser’s WebSocket and HTTP traffic to the middleware. It is the only component that listens on a public network port by default.

py-bsd: system call bindings

A Cython library that exposes FreeBSD-specific interfaces (ZFS via libzfs, devinfo, the kqueue family, etc.) to Python. Where a stable binding does not exist, RealNAS uses a small command-backed shim that calls the documented userspace tool and parses its output. The shim approach is deliberate: it favors using interfaces FreeBSD already commits to keeping stable.

State storage

A SQLite database stores configuration that has no natural home in the OS: share definitions before they are emitted into smb4.conf includes, alert rules, user-defined snapshot schedules, the audit log. Configuration that belongs to the OS lives in the OS: rc.conf for service toggles, passwd for users, ZFS dataset properties for dataset metadata.

State ownership

This is the most important table on this page.

Domain Source of truth Where it lives
Service enablement FreeBSD rc.conf /etc/rc.conf, written via sysrc
ZFS dataset properties ZFS itself On-pool, read via zfs get
Local users / groups FreeBSD pw /etc/master.passwd, /etc/group
SMB shares Samba Include file at /usr/local/etc/smb4.d/, referenced from smb4.conf
NFS exports mountd /etc/exports.d/realnas.exports
Boot environments bectl ZFS boot dataset
Snapshot schedules RealNAS SQLite (no natural home in base FreeBSD)
Alert rules RealNAS SQLite
UI sessions RealNAS SQLite
Rule

If FreeBSD has a canonical place to store something, that is where RealNAS stores it. The SQLite database is reserved for state with no good home in the OS.

API surface

RealNAS exposes a single conceptual API with two transports. The web interface uses a WebSocket at /websocket that carries a JSON-RPC and DDP-flavored protocol: subscriptions, call/response, and pushed events on a single connection. Programmatic clients and scripts can use the HTTP endpoint at /api, which speaks ordinary JSON-RPC.

The same plugin code handles both. There is no “internal” vs “public” API; what the UI calls is what a script can call.

Process model

One daemon, started by service realnasd start. Restart by service realnasd restart. Logs to syslog. Configuration changes do not require a restart in the common cases; the daemon emits events on its own internal bus and plugins react.

There is no init-system entanglement beyond the standard FreeBSD rc.d conventions. No supervisor of supervisors, no separate worker pool, no required helper services. Where helper processes exist (the proxy, for example), they are independent rc.d services with their own enable knob.

What it does not do

  • No image-based updates. Updates flow through freebsd-update, pkg upgrade, and bectl.
  • No proprietary licensing daemon. There is nothing to phone home to.
  • No remote telemetry. The daemon does not initiate outbound connections to any host other than those the operator explicitly configures (SMTP, syslog, replication targets, package mirrors).
  • No mandatory cloud account. There is no concept of a RealNAS account; authentication is local by default.
  • No hidden state. Every configuration that affects behavior is discoverable via either an OS tool or a single SQLite database.