User Manual

This manual assumes you are running RealNAS on FreeBSD 15.x and have shell access to the host. Most operations have a webui equivalent and a shell equivalent; both are listed where they meaningfully differ. RealNAS does not hide the shell.

1. Installation

RealNAS is a set of FreeBSD packages. On a fresh FreeBSD install:

# become root
su -

# bootstrap pkg if you have not already
pkg bootstrap

# install
pkg install realnas-middleware realnas-webui

# enable and start
sysrc realnasd_enable=YES
sysrc realnas_proxy_enable=YES
service realnasd start
service realnas_proxy start

The webui is then reachable at https://<host>:4443/. The proxy serves a self-signed certificate on first start; replace it once you have a real one (see §12).

2. First login

Default credentials are root with a randomly-generated password written to /var/log/realnas/initial-root-password. The webui will refuse to load past the login screen until you change it. After login, work through the System → Settings page: set the hostname, the timezone, the SMTP relay, and the SSH key for root.

3. Storage: Pools

Storage → Pools. Two common operations:

Create a pool

Pick the disks, pick the topology (mirror, raidz1, raidz2, raidz3, striped mirrors), pick the pool name. The UI calls zpool create. The pool name is not constrained to any reserved list; you can name it anything that ZFS would accept.

Import an existing pool

Storage → Pools → Import. The UI runs zpool import and asks you to confirm. Pools created on another ZFS system (including bare FreeBSD or any other vendor’s system) are valid candidates as long as feature flags are compatible.

Maintenance

Scrubs, replace, expand, attach, detach: all surfaced in the UI, all backed by the corresponding zpool subcommand. Manual zpool work on the host shell is fully supported; the UI reads the live state of the pool, it does not assume the UI is the only thing changing it.

4. Storage: Datasets

Storage → Datasets. Create child datasets under any imported pool. Properties are surfaced in the UI: compression, recordsize, atime, quotas, reservation, encryption, and the usual ZFS family. Property changes are written via zfs set on the live dataset.

ZFS encryption is supported. Use it for datasets that hold material you would not want to leak if the drives walked out the door: financial records, household documents, anything covered by a regulatory regime. Pick a passphrase and write it down somewhere not on the array.

5. Storage: Snapshots

One-off and periodic. One-off is a button on the dataset; periodic is a schedule with naming convention, retention, and recursion settings.

# equivalent on the shell:
zfs snapshot tank/home@manual-2026-06-21
zfs list -t snapshot -r tank/home

Snapshots are visible in the UI, in zfs list -t snapshot, and in .zfs/snapshot/ on the mounted dataset if you have the snapdir property set to visible. Rollback is a single click in the UI or a single zfs rollback on the shell.

6. Sharing: SMB

Sharing → SMB. Create a share by pointing it at a dataset path and giving it a name. Set the access semantics: which user/group owns it, whether guests are permitted, what the default file mode is, whether shadow copies (snapshot-backed previous versions) are exposed.

RealNAS writes its share definitions to an include file at /usr/local/etc/smb4.d/realnas.conf and references it from smb4.conf. The base smb4.conf stays editable; manual additions survive UI changes.

# inspect what RealNAS emitted:
cat /usr/local/etc/smb4.d/realnas.conf

# verify Samba is happy:
testparm -s /usr/local/etc/smb4.conf

7. Sharing: NFS

Sharing → NFS. Pick a dataset, list the networks or hosts permitted, choose options (read-only, all_squash, sec, etc.). The UI writes to /etc/exports.d/realnas.exports and signals mountd.

# inspect what is exported right now:
showmount -e

8. Accounts: Users & Groups

Accounts → Users. Create local users with UIDs you control. The UI calls pw useradd. When importing a pool from another system, make sure UIDs/GIDs match what the data on disk expects; the UI lets you set the numeric UID directly when creating a user.

SSH keys for a user are managed under the user’s page; they are written to the user’s home directory under ~/.ssh/authorized_keys with appropriate permissions.

9. System: Alerts

System → Alerts. Set the SMTP relay and the destination addresses. Choose which alert classes to email. The defaults are conservative: pool degradation, SMART failures, scrub errors, replication failure, disk near-full.

Local syslog is always written, regardless of email configuration. Pipe it where you want.

10. System: SMART

System → SMART. The UI schedules short and long tests, surfaces the device list, and shows the last-known status. Underneath, this is smartctl from smartmontools in the FreeBSD ports tree.

11. System: Boot environments

System → Boot Environments. A boot environment is a ZFS-cloned snapshot of the root filesystem that you can boot from instead of the current one. Take one before a risky change; activate it from the UI; if the change goes wrong, reboot back into the previous environment from the loader.

# equivalent on the shell:
bectl list
bectl create pre-upgrade
bectl activate pre-upgrade

12. System: Updates

The update workflow has three steps and uses two stock FreeBSD tools.

# 1. take a boot environment before changing anything
bectl create snapshot-$(date +%Y%m%d)

# 2. update the base system
freebsd-update fetch
freebsd-update install

# 3. update packages, including RealNAS itself
pkg update
pkg upgrade

# reboot if the kernel changed
shutdown -r now

There is no “RealNAS update channel.” The OS uses the official FreeBSD update infrastructure; the packages use the configured pkg repository. If you trust the FreeBSD project to update your kernel, you can trust them to keep working tomorrow.

13. System: Certificates

The webui will use whatever certificate you point it at. There is no built-in ACME client; the operator runs acme.sh, certbot, or whatever fits their setup, and the UI reads the certificate from the configured path. The default self-signed certificate is for first-boot only and is meant to be replaced.

14. Console

Everything described above is doable on the shell with standard FreeBSD tools. Specifically:

ZFS

zpool, zfs: create, destroy, snapshot, send/receive, set/get properties.

Sharing

smbcontrol, net (Samba), showmount, exports(5).

Users

pw, vipw, passwd.

Services

service, sysrc.

Boot environments and updates

bectl, freebsd-update, pkg.

Health

smartctl, zpool status, periodic, syslogd.

Anything you change at the shell is visible to the UI on the next refresh. Anything the UI changes is visible at the shell immediately. The two are not separate sources of truth; the OS is the source of truth, and both surfaces read it.