TrueNAS Development Documentation
This content follows experimental development changes in TrueNAS 27, a future version of TrueNAS.
Use the Product and Version selectors above to view content specific to a stable software release.
Local Pool Migration
8 minute read.
This tutorial covers migrating data and configuration from one local pool to another on a TrueNAS storage appliance. Migrating is helpful if, for example, when you have two local pools (Pool A and Pool B) and want to consolidate them by moving data and shares from Pool B to Pool A. You can then destroy Pool B and repurpose its drives.
Local pool migration is a significant and disruptive storage configuration change. Make sure you have everything you need as discussed in the preparation phase before continuing to the migration phase.
Have the following ready:
- List of shares and share types being moved
- List of backup tasks being moved
- New topology for the target pool (if vdev changes are planned for Pool A)
- Details and hierarchy of any encrypted datasets being moved, and the encryption key or passphrases to unlock them
- Plan for reusing the drives freed from Pool B (for example, extending Pool A or creating new pools)
The work is divided into two phases:
Phase 1: Preparation — split into two parts: one performed a week before the maintenance window, and the other the day of.
Phase 2: Migration — the actual data and configuration move, followed by destroying Pool B.
If the post-migration goal is to consolidate Pool B drives into Pool A as part of enabling Storage Tiering, follow the Storage Tiering Migration Guide instead. That procedure adds tiering-specific preparation items, a topology change to the Pool A special class, and a third phase covering tier migration jobs.
Preparation is performed in two stages, one completed approximately one week before, and the other the day of the planned migration.
Complete these tasks approximately one week before the scheduled maintenance window. Use this time to identify issues and reduce risks during the maintenance window.
- Confirm the system (or both controllers on Enterprise HA systems) is on a supported, stable TrueNAS version.
- Confirm that Pool A has sufficient space to hold the data from Pool B.
- Move the system dataset to Pool A if it is not located there already.
- Configure local replication tasks for data from Pool B to Pool A. Ensure your Pool B dataset hierarchy is set up to avoid name collisions with existing datasets in Pool A.
- Be prepared to reconfigure local storage paths after they change pools.
- Reconfigure apps, containers, and VMs to use Pool A.
- Move local user account home directories from Pool B to Pool A.
- Schedule and confirm an uninterrupted 4-hour maintenance window for the migration.
If you are using multi-layered ZFS encryption, contact support before continuing.
Complete these checks immediately before beginning migration work.
- Confirm that you have an uninterrupted 4-hour maintenance window for the migration.
- Verify you have OOBM/IPMI access to the system (or both controllers on HA systems) as well as SSH access, and the admin user has full control permissions with
sudocommand permissions. - Download a system configuration fle as a backup, including the secret seed.**
- Download a system debug.
- Ensure no client systems are connected to services shared by Pool B.
- Stop all sharing services exporting data from Pool B. Do not delete the share configuration!
- Stop all Pool B replication jobs that are not the local replication jobs you created for this migration.
Do not delete the job configuration! - Take a final snapshot and run local replication to ensure all data on Pool B is fully replicated to Pool A.
- Confirm the system dataset is still assigned to Pool A.
- Verify directory services are healthy (if applicable).
Migration can take four hours or more to complete depending on the amount of data in the dataset. Make sure you have ample time to complete this process before beginning the migration process.
Complete these checks immediately before beginning migration work.
Review all shares using storage on Pool B and follow the share migration steps for each share.
Reload the Datasets page in the WebUI and confirm no datasets in Pool B show sharing icons. Open the Sharing page and confirm all share paths now point to Pool A.
Review all backup-related tasks on Pool B and follow the task migration steps for each item.
Reload the Datasets page and confirm no stray backup tasks remain on Pool B. Open the Data Protection page and confirm no data protection tasks are active for Pool B.
Review local user account home directories to confirm no accounts are using paths on Pool B.
At this point, you have reconfigured the server so that all shares, tasks, and user home directories are on Pool A. However, you can still revert all changes using the configuration file you previously saved. Before proceeding, verify all data is accessible via test clients at the new Pool A paths.
For replicated datasets and zvols, you might need to change them to read-write before the customer can validate access.
- Destroy Pool B from the WebUI. Go to Storage and click Disconnect on Pool B. Select Delete Pool. then confirm the export and click Disconnect
You can now reuse the drives freed from Pool B for your new use case (extending Pool A, creating new pools, creating a fusion pool for storage tiering, etc.).
Any topology changes you make to Pool A (such as adding vdevs) are permanent. Thoroughly review the all new topology changes before applying them.