Moving your apps, VMs and data to a different machine — including changing your pool layout
(for example, from a 2-drive mirror to RAIDZ2).
Warning: This is an advanced guide. Most of this work happens in the TrueNAS interface behind HexOS, not in the Command Deck. If you only need to move drives between machines without changing the pool layout, you can usually just move the physical disks — this guide is for the case where the new server has a different pool layout, so the data has to be copied across.
Take your time, and don't erase anything on the old server until the new one is fully verified.
| Thing | How it moves |
|---|---|
| Your files (shares/folders) | ZFS replication, dataset by dataset |
| Apps and their settings | Replicate the ix-apps dataset, then point Apps at the new pool |
| App data stored in folders | ZFS replication, like any other dataset |
| Virtual machines | Replicate the zvols; the VM definitions either come back with a config restore or get recreated by hand |
| Users, shares, network settings | Either recreate them by hand, or restore a config backup — see Step 6 |
| Your HexOS license | Follows your account — but only one server can be claimed at a time |
There are two valid ways to get your users, shares and VM definitions onto the new machine, and the one you pick changes what you do in Steps 5 and 6.
Option A — Start clean and recreate by hand. You set your users and shares up again on the new server. Simplest to follow, nothing unexpected carried over, and you end up with a tidy system. Best if you have a handful of shares and users, which is true for most HexOS setups.
Option B — Restore the config backup from the old server. Your users, shares, SMB settings and VM definitions come back all at once. Saves real work if you have a lot of them, at the cost of a few extra steps and a couple of pitfalls — including one that will strand your new pool until you re-import it.
Both options are written out in full in Step 6. Everything up to that point is identical, with one exception noted in Step 5.
HDDs, SSDs or NVMEs. You will need it character for character.Follow the installation guide to install HexOS on
the new server's boot drive.
Stop before claiming it in the Command Deck.
Tip: One license, one claimed server. A HexOS license covers one claimed server at a time. If you try to claim the new machine while the old one is still claimed, you'll see "You do not have any licenses available to claim a new server." That's expected — you'll claim the new server at the end, once everything has been copied across and checked.
Leaving the new machine unclaimed for now is fine. An unclaimed HexOS machine is still a fully working TrueNAS system, reachable at
https://<new-server-ip>with thetruenas_adminaccount and the root password you set during installation. That's where the next few steps happen.
Log in to the new server directly at https://<new-server-ip> and create your pool under Storage > Create Pool, choosing the RAIDZ2 layout.
Two things to know:
HDDs).That second point is the single most valuable thing in this guide. Apps and VMs store absolute paths like /mnt/HDDs/… and /dev/zvol/HDDs/…. If the pool name matches, everything you copy across simply works. If it doesn't, you'll be hand-editing paths in every app and every VM
afterwards — and creating the pool yourself is the only opportunity you get to choose the name, because HexOS generates pool names automatically from the drive type.
Info: Names in the Command Deck — the name you can edit for a pool in HexOS is a display label. The underlying ZFS pool name — the one that appears in paths — is set when the pool is created and isn't changed by renaming the label.
Warning: Create the pool before restoring any config backup. If you're going with Option B, don't restore the config yet. TrueNAS won't let you create a pool
whose name already appears in its configuration, and a restored config still lists the old server's pool by that name. Create the pool first, restore later — Step 6 covers the order.
Put both servers on the same network. Replication runs directly between them; it doesn't go through HexOS or the internet.
The setup — SSH keypair, SSH connection, replication task — is covered step by step, with screenshots, in Replicating Virtual Machines. The same procedure applies here; you're just replicating more than VM disks.
Replicate all of the following from the old pool to the new one:
ix-apps dataset (<pool>/ix-apps). This is where your app configurations live. It is what actually brings your apps back — app settings are not in the config backup file, under either option.Tip: Stop your apps before the final pass. Replicate a snapshot taken with the apps stopped, so databases aren't caught mid-write. A practical approach: run the replication once while everything is running to move the bulk of the data, then stop your apps and run it a second time to pick up the changes. The second pass is
incremental and much faster.
Expect this to take hours rather than minutes for a couple of terabytes on a gigabit network.
On the new server, in the TrueNAS UI, go to Apps > Settings (the configuration menu) and set the apps pool to the pool you just replicated into.
TrueNAS finds the existing ix-apps dataset and picks your apps up with their settings intact. Because the pool name matches the old one, any folders your apps mount resolve to the right place.
Start the apps and check each one before moving on.
On Option A, recreate each VM in the TrueNAS UI now, attaching the zvol you replicated as its disk rather than creating a new one. The last section of
Replicating Virtual Machines shows this.
On Option B, skip this step. VM definitions are part of the config backup, so they'll come back on their own in Step 6 — and because the pool name matches, they'll already be pointing at the zvols you replicated. Check them after the restore instead.
Under both options: if a VM or app uses passed-through hardware — a GPU, a TPU, a USB device — you'll need to select that device again on the new machine. Hardware addresses differ from board to board, so the old selection won't carry over, and a restored config can't carry it either.
Pick the option you decided on earlier. Either way, this has to happen before you claim the server in Step 7.
In the TrueNAS UI on the new server, recreate:
Then move on to Step 7. Once the server is claimed, the folders will appear in the Command Deck alongside your apps.
The order matters here. Do it exactly like this:
Warning: Two things to watch on Option B.
Network settings come from the old machine. The new motherboard's network ports have different names, so the restored network configuration may not apply cleanly, and the restored hostname and static IP may collide with the old server if both are powered on. Keep a monitor and
keyboard on the new server for this reboot so you can fix the network from the console if it doesn't come back on the LAN.Never upload a config file to a server that's already claimed. The config contains the API key HexOS uses to talk to your server. Restoring an older config replaces that key, and the Command Deck loses access and disconnects the server. Restoring now, while the new machine is still
unclaimed, avoids this entirely — which is why Step 7 comes last.
Info: What a config restore does not bring back: app configurations. They live on the pool in the
ix-appsdataset, not in the config file, which is why Step 3 replicates it under both options.
Only once the new server is doing everything the old one did:
Network interface names change. Covered above for Option B, but it's worth a monitor and keyboard on the new machine for the first boot either way.
Hardware passthrough needs re-selecting. GPUs, TPUs and USB devices have to be picked again on the new machine, under both options.
Encryption keys. Pools created by HexOS aren't encrypted, so this usually doesn't apply. If you created encrypted datasets yourself, export their keys from the old server before you start, and keep them with your config backup.
The old server is your rollback plan. Don't wipe it, and don't pull its drives, until the new server has been running your workload without problems for a while.
If you get stuck partway through, the HexOS Discord is the
fastest place to ask. Include which step you reached, which option you chose, your old and new
pool names, and whether the new server has been claimed yet.
Contribute: to help to improve HexOS documentation join the #Docs channel on Discord today! Send feedback, suggestions or contribute a guide.