Migration Manual

ZFS pools are portable across compatible systems. The migration path is a fresh FreeBSD install, RealNAS installed with pkg, and a clean zpool import of the existing data pool.

---

Recommended path

Step 1. Inventory the current system

Record the settings you will need to recreate:

• Pool names and the disk identifiers each pool uses.
• Dataset paths that are shared.
• SMB share names, ACL behavior, and guest settings.
• NFS exports and any host or network restrictions.
• Local users and groups, including numeric UIDs and GIDs.
• Snapshot schedules and retention policies.
• Scrub and SMART schedules.
• SMTP relay settings and alert destinations.
• SSH authorized keys.
• Non-default ZFS properties such as compression, atime, recordsize, quota, reservation, and encryption.

# inventory commands on the old system
zpool list
zpool status
zfs list -o name,used,available,mountpoint,compression,atime
zfs list -t snapshot | head -50
showmount -e
pw usershow -a
pw groupshow -a

Step 2. Export the pool cleanly

Stop services that have files open on the pool, then export it:

service smbd stop
service nfsd stop
service mountd stop
zpool export tank

If zpool export says the pool is busy, find the process with fstat -f /tank and stop it before trying again.

Step 3. Install FreeBSD 15.x

Install FreeBSD on the boot device. Do not create the data pool during installation; you will import the existing pool later.

After the first boot, bring up networking and update the system:

freebsd-update fetch
freebsd-update install
pkg update

Step 4. Install RealNAS

pkg install realnas-middleware realnas-webui
sysrc realnasd_enable=YES
sysrc realnas_proxy_enable=YES
service realnasd start
service realnas_proxy start

Log in at https://<host>:4443/ with the temporary password from /var/log/realnas/initial-root-password, then change it.

Step 5. Import the data pool

Connect the drives to the new host. Import from the web UI or from the shell:

zpool import
# inspect the listed candidate pools, then import the one you want:
zpool import tank

Datasets, snapshots, and ZFS properties come with the pool. The data is not copied to a new format.

Step 6. Recreate users and groups

File ownership on disk is numeric. Recreate users and groups with the same UIDs and GIDs they had on the old host. The UI exposes the numeric UID field; from the shell, use matching numeric IDs:

pw groupadd staff -g 1001
pw useradd alice -u 1001 -g staff -d /home/alice -m -s /bin/sh

Step 7. Recreate shares

SMB and NFS shares are management configuration, not ZFS pool data. Recreate them in the web UI under Sharing → SMB and Sharing → NFS.

Step 8. Recreate schedules and alerts

Recreate snapshot schedules, scrub schedules, SMART tests, alert routing, and SMTP settings. Use the inventory from step 1 as the checklist.

Step 9. Verify before cutover

• Mount each share from a client and confirm read/write behavior.
• Create a test file and verify ownership and permissions.
• Take a snapshot and confirm it appears in the UI and in zfs list -t snapshot.
• Trigger a test alert and confirm delivery.
• Reboot the host and confirm pools, shares, and services return correctly.

After verification, point clients at the new host. Keep the old system powered off and unchanged until you are done with it as a fallback.

---

What changes

Updates

Use freebsd-update for the base system, pkg upgrade for packages, and bectl before risky changes.

Manual edits to /etc

They remain valid. RealNAS writes share configuration to include files under /usr/local/etc/smb4.d/ and /etc/exports.d/.

Service enablement

Service state lives in /etc/rc.conf and can be changed with sysrc. The UI reads that state.

Boot environments

Boot environments are managed by bectl and shown in the UI under System → Boot Environments.

Telemetry and registration

RealNAS has no telemetry, diagnostic upload, support registration, or anonymous statistics flow.

---

Caveats

• In-place upgrade is not supported. RealNAS does not import another product's configuration database. The supported path is fresh install, pool import, and manual recreation of management settings.
• Vendor-specific ZFS user properties may remain. They should not harm the pool. Clean them up with zfs inherit if needed.
• Replication relationships must be recreated. The data remains on the pool, but schedules and credentials live in management configuration.
• Disk paths may change. ZFS identifies devices by label and should still import the pool, but external automation that used old controller paths may need updating.