Migration Manual · RealNAS

RealNAS keeps the data plane and replaces the management plane. The data plane is your ZFS pool, datasets, snapshots, SMB/NFS data, and file ownership. The management plane is the WebUI, middleware daemon, update path, schedules, alerting, service configuration, and local orchestration state.

The recommended migration is a fresh FreeBSD install, RealNAS packages, explicit bootstrap, and a middleware-driven pool import. Do not restore a TrueNAS or zVault configuration database wholesale unless you understand the schema and follow-on convergence work.

Before You Begin

Back up data you cannot afford to lose. Keep the old system, encryption keys, recovery keys, and configuration export intact until RealNAS import, share access, user mapping, snapshots, and reboot behavior are verified.

What Carries Over

ZFS data carries over because RealNAS uses OpenZFS directly. Management configuration usually needs to be recreated or deliberately translated.

Area	Migration Behavior
Pool layout	Imported as a normal ZFS pool if compatible with the target FreeBSD/OpenZFS version.
Datasets and snapshots	Remain on the pool and appear after import.
ZFS properties	Properties such as compression, atime, recordsize, quotas, reservations, mountpoints, and native encryption metadata remain with the datasets.
File ownership	Numeric UIDs and GIDs remain on disk. Recreate users and groups with matching numbers.
SMB/NFS shares	Recreate in RealNAS. Share definitions are management state, not portable pool data.
Snapshot and replication schedules	Recreate or deliberately translate. Existing snapshots remain; schedules do not automatically become RealNAS tasks.
Alerts, SMART, scrub schedules, SMTP	Recreate from your inventory.
Plugins, jails, HA, support/cloud integrations	Not part of the default RealNAS install. Treat these as separate projects.

Inventory the Old System

Collect enough information to rebuild users, shares, permissions, schedules, and alerting. Keep a copy of the old configuration export for reference, but do not expect RealNAS to import it as a product-level restore.

Pool names, disk identifiers, vdev topology, and encryption type.
Dataset paths, mountpoints, ZFS properties, quotas, reservations, ACL modes, and encryption roots.
SMB share names, paths, guest settings, ACL behavior, auxiliary parameters, and previous-version behavior.
NFS exports, allowed hosts/networks, root mapping, read-only flags, and security flavors.
Local users and groups, especially numeric UIDs and GIDs.
Snapshot, scrub, SMART, replication, and alert schedules.
SMTP relay settings and alert recipients.
SSH authorized keys and administrator access model.
Any workload-specific service configuration that lives outside ZFS.

zpool list
zpool status -v
zfs list -o name,used,available,mountpoint,compression,atime,recordsize,quota,reservation,encryption
zfs list -t snapshot -r
zfs get -r all tank | tee zfs-properties.txt
showmount -e
pw usershow -a
pw groupshow -a
service samba_server status 2>/dev/null || service smbd status 2>/dev/null
testparm -s 2>/dev/null

Check Encryption Type

Native OpenZFS encryption and legacy GELI encryption are different migration cases.

Native OpenZFS encryption: Encryption is a ZFS dataset property. The pool can appear in import discovery, then locked datasets are unlocked after import with dataset keys or passphrases.
Legacy GELI encryption: Encryption is below ZFS at the provider layer. Raw providers may need to be attached with GELI key material before the pool appears to ZFS import discovery.

Keep old key files, passphrases, recovery keys, and screenshots or exports of encryption configuration until the RealNAS import and read-back are complete.

Recommended Path

Step 1. Export the Pool Cleanly

Stop services with open files on the pool, then export the pool on the old host.

service samba_server stop 2>/dev/null || service smbd stop 2>/dev/null
service nfsd stop 2>/dev/null || true
service mountd stop 2>/dev/null || true
zpool export tank

If export reports the pool is busy, identify open files and stop the owning service before trying again.

fstat -f /tank
zpool export tank

Step 2. Install FreeBSD

Install FreeBSD 15.x on the boot device. Do not create a new data pool over the old disks. Use a separate boot device when practical.

freebsd-update fetch
freebsd-update install
pkg update

Step 3. Install and Bootstrap RealNAS

pkg install realnas-middleware realnas-webui
/usr/local/sbin/realnas-bootstrap
sysrc realnas_webui_enable=YES
service realnas_webui start

Bootstrap starts and enables realnasd. The WebUI listens at https://<host>:4200/ by default. The first certificate is self-signed.

service realnasd status
service realnas_webui status
curl -k https://127.0.0.1:4200/api/docs/
midclt call system.info

Step 4. Import the Pool Through Middleware

Connect the drives to the new host. Prefer middleware import over hand-running zpool import so RealNAS can converge datastore and dataset state.

midclt call pool.import_find
zpool import

For ordinary unencrypted pools, import from Storage → Pools → Import. After import, verify the pool through both RealNAS and ZFS.

midclt call pool.query
zpool status -v
zfs list

Encrypted Pools

Native OpenZFS Encrypted Pools

Native OpenZFS encrypted pools are the covered encrypted import path. RealNAS imports the pool, detects locked encrypted datasets after import, validates key or passphrase material, and unlocks through the normal dataset unlock flow.

midclt call pool.import_find
midclt call pool.dataset.encryption_summary tank
midclt call pool.dataset.unlock tank/secure '{"recursive": true}'

Verify read-back from a known dataset after unlock. Do not delete old key material until you have completed import, unlock, share access, and reboot verification.

Legacy GELI Encrypted Pools

Legacy GELI encrypted pools from FreeNAS and older CORE-era systems are supported as an in-place import landing state. This is not the same as native OpenZFS encryption.

GELI sits below ZFS, so the pool may not appear in pool.import_find until providers are attached. RealNAS discovers unused GELI ZFS providers, uploads the GELI key to the decrypt path, attaches providers with the FreeBSD GELI adapter, refreshes import discovery, and imports through pool.import_pool with legacy_geli_devices. Failed imports should detach providers attached by the job and leave middleware state unchanged.

After in-place import, keep the old source intact until read-back is verified. Conversion from legacy GELI to native OpenZFS encryption is separate migration work. The current backend has a dry-run planner, pool.legacy_geli_migration_plan, and a confirmed copy job, pool.legacy_geli_migrate, that copies into a separate native encrypted destination dataset and keeps the legacy source available for rollback. WebUI orchestration and broader real-world migration evidence remain open work.

Legacy GELI

Do not advertise legacy GELI import as one-click native encryption conversion. The supported landing state is in-place import; native conversion requires a separate destination and explicit operator review.

Recreate Users and Groups

File ownership is numeric. Recreate users and groups with the same UIDs and GIDs they had on the old host before exposing shares to clients.

pw groupadd staff -g 1001
pw useradd alice -u 1001 -g staff -d /home/alice -m -s /bin/sh
midclt call user.sync_builtin

You can create users in the WebUI if the UI exposes the needed numeric fields. For large migrations, script the account creation from the inventory and then run user.sync_builtin.

Recreate Shares

SMB

Recreate SMB shares under Sharing → SMB. Point each share at the existing dataset path, then review ownership and ACL behavior from a client.

RealNAS uses stock FreeBSD Samba. It does not depend on iX-only VFS modules such as ixnas, zfs_core, aio_fbsd, or shadow_copy_zfs. Standalone shares use standard Samba functionality such as zfsacl and shadow_copy2. Re-test any Active Directory or idmap-dependent deployment before cutover.

testparm -s /usr/local/etc/smb4.conf
net groupmap list verbose
midclt call sharing.smb.query
midclt call smb.synchronize_group_mappings

NFS

Recreate NFS exports under Sharing → NFS. Use the inventory to restore host/network restrictions, read-only settings, root mapping, and security flavor.

showmount -e
midclt call sharing.nfs.query

Recreate Schedules and Alerts

Existing snapshots remain on disk, but snapshot schedules, replication tasks, scrub schedules, SMART tests, SMTP settings, and alert routing are management state. Recreate them deliberately and verify each class of scheduled work.

zfs list -t snapshot -r tank
midclt call pool.snapshottask.query
midclt call replication.query
midclt call pool.scrub.query
midclt call smart.test.query
midclt call alert.list

Config Translation Notes

Users and groups: TrueNAS-style account tables are close to RealNAS middleware tables, but recreating through the UI or shell is safer for most sites. If you import SQL rows manually, include users, groups, and memberships in the right order, then run midclt call user.sync_builtin.
SMB shares: Most share fields map conceptually, but the Samba runtime is stock FreeBSD Samba. Review VFS modules, idmap behavior, auxiliary parameters, and snapshot previous-version behavior.
NFS exports: The share model is similar, but generated NFS exports are RealNAS-owned middleware output. Use the UI/API rather than editing generated exports in place.
Snapshots and replication: Replication uses the vendored/pinned zettarepl stack. Recreate tasks and credentials; do not assume schedules are pool data.
Updates: Appliance update trains are gone. RealNAS uses a single atomic update.update middleware transaction over bectl, freebsd-update, and pkg, with paired boot-environment and database rollback on any failure. See the manual for the full six-step contract.

In-Place Upgrade Path

An in-place upgrade from an appliance-style TrueNAS/zVault boot environment to vanilla FreeBSD plus RealNAS is an advanced recovery project, not the recommended production path. Appliance rc.d state, package metadata, old update tooling, jails, custom generated files, and middleware database assumptions can collide with RealNAS ownership rules.

Use fresh install plus pool import unless you have console access, rollback boot environments, a full backup, and a precise reason to preserve the old boot environment.

Verify Before Cutover

Reboot the RealNAS host and confirm the pool imports, services start, and the WebUI returns.
Mount every SMB and NFS share from representative clients.
Create, read, modify, and delete test files as normal users.
Verify ownership with ls -ln so UID/GID mismatches are visible.
Take a manual snapshot and confirm it appears in the WebUI and zfs list -t snapshot.
Run or schedule a scrub and verify the task state.
Run SMART status checks for each disk.
Send a test alert or verify SMTP delivery through a controlled alert.
For encrypted pools, reboot and verify unlock/read-back again.
Keep the old system powered off and unchanged until the new host has survived normal workload testing.

shutdown -r now
service realnasd status
service realnas_webui status
zpool status -v
zfs snapshot tank/migrated@test-cutover
zfs list -t snapshot tank/migrated@test-cutover
ls -ln /tank/migrated

Default-Install Gaps to Plan Around

These are not automatic migration targets in the default install:

HA/failover. Single-node default install; failover is a deferred optional tranche.
TrueCommand and iX support tooling. Removed or stubbed because RealNAS does not phone home to iX services.
Apps, Docker, Kubernetes. Not part of the FreeBSD RealNAS default install.
Jails/plugins. Deferred optional package work, not a default runtime promise.
KMIP, VMware, Fibre Channel, enclosure health. Deferred or hardware-specific optional surfaces.
Directory services. AD/LDAP/Kerberos/idmap surfaces expose disabled or degraded states until configured and tested in your environment.

Result

The migration moves management to RealNAS. The ZFS data stays on the existing pool, and anything outside ZFS must be inventoried, recreated, or deliberately translated.