Migrating ZFS File Systems

You can use the shadow migration feature to migrate file systems as follows:

• A local or remote ZFS file system to a target ZFS file system

• A local or remote UFS file system to a target ZFS file system

Shadow migration is a process that pulls the data to be migrated:

• Create an empty ZFS file system.

• Set the shadow property on an empty ZFS file system, which is the target (or shadow) file system, to point to the file system to be migrated.

• Data from file system to be migrated is copied over to the shadow file system.

You can use the shadow property URI to identify the file system to be migrated in two ways:

• shadow=file:///path – Use this syntax to migrate a local file system

• shadow=nfs://host/path – Use this syntax to migrate a NFS file system

Review the following considerations when migrating file systems:

• The file system to migrated must be set to read-only. If the file system is not set to read-only, in progress changes might not be migrated.

• The target file system must be completely empty.

• If the system is rebooted during a migration, the migration continues after the system is booted.

• Access to directory content that is not completely migrated or access to file content that is not completely migrated is blocked until the entire content is migrated.

• If you want the UID, GID, and ACL information to be migrated to the shadow file system during an NFS migration, make sure that the name service information is accessible between the local and remote systems. You might consider copying a subset of the file system data to be migrated for a test migration to see that all the information is migrated properly before doing a completing a large migration of data over NFS.

• Migrating file system data over NFS can be slow, depending on your network bandwidth. Be patient.

• You can use the shadowstat command to monitor a file system migration, which provides the following data:

  • The BYTES XFRD column identifies how many bytes have been transferred to the shadow file system.

  • The BYTES LEFT column fluxuates continuously until the migration is almost complete. ZFS does not identify how much data needs to be migrated at the beginning of the migration because this process might be too time-consuming.

  • Consider using the BYTES XFRD and the ELAPSED TIME information to estimate the length of the migration process.

How to Migrate a File System to a ZFS File System

1. If you are migrating data from a remote NFS server, confirm that the name service information is accessible on both systems.

   For a large migration using NFS, you might consider doing a test migration of a subset of the data to ensure that the UID, GUID, and ACL information migrates correctly.

2. Install the shadow-migration package on the system where the data is to be migrated, if necessary, and enable the shadowd service to assist with the migration process.

   # pkg install shadow-migration

   # svcadm enable shadowd

   If you do not enable the shadowd process, you will have to reset the shadow property to none when the migration process is complete.

3. Set the local or remote file system to be migrated to read-only.

   If you are migrating a local ZFS file system, set it to read-only. For example:

   # zfs set readonly=on tank/home/data

   If you are migrating a remote file system, share it read-only. For example,

   # share -F nfs -o ro /export/home/ufsdata
   # share
   -               /export/home/ufsdata   ro   ""  

4. Create a new ZFS file system with the shadow property set to the file system to be migrated.

   For example, if you are migrating a local ZFS file system, rpool/old, to a new ZFS file system, users/home/shadow, set the shadow property to rpool/old when the users/home/shadow file system is created.

   # zfs create -o shadow=file:///rpool/old users/home/shadow

   For example, to migrate /export/home/ufsdata from a remote server, set the shadow property when the ZFS file system is created.

   # zfs create -o shadow=nfs://neo/export/home/ufsdata users/home/shadow2

5. Check the progress of the migration.

   For example:

   # shadowstat
                                           EST             
                                   BYTES   BYTES           ELAPSED
   DATASET                         XFRD    LEFT    ERRORS  TIME
   users/home/shadow               45.5M   2.75M   -       00:02:31
   users/home/shadow               55.8M   -       -       00:02:41
   users/home/shadow               69.7M   -       -       00:02:51
   No migrations in progress

   When the migration is complete, the shadow property is set to none.

   # zfs get -r shadow users/home/shadow*
   NAME                PROPERTY  VALUE   SOURCE
   users/home/shadow   shadow    none    -
   users/home/shadow2  shadow    none    -

Troubleshooting ZFS File System Migrations

Review the following points when troubleshooting ZFS migration problems:

• If the file system to be migrated is not set to read-only, then not all data will be migrated.

• If the target file system is not empty when the shadow property is set, the data migration will not begin.

• If you add or remove data from the file system to be migrated when the migration is in progress, those changes might not be migrated.

• If you attempt to change the mount of the shadow file system when the migration is in progress, you will see the following message:

  # zfs set mountpoint=/users/home/data users/home/shadow3
  cannot unmount '/users/home/shadow3': Device busy