Go to main content

Managing ZFS File Systems in Oracle® Solaris 11.4

Exit Print View

Updated: August 2019
 
 

Migrating ZFS File Systems

To migrate a local or remote ZFS or UFS file system to a target ZFS file system, use shadow migration. The target file system is also called the shadow file system.

Use the following commands to manage shadow migration:

  • The shadowadm command stops, resumes, or cancels shadow migration.

  • The shadowstat command with its options monitors migrations running on the system. Use the shadowstat command without options to monitor the progress of migrations. The displayed information is continuously updated until you type Ctl-C.

    The command's –E and –e options are particularly useful.

    • To list all currently running migrations and identify those that could not be completed because of errors, use the –E option.

    • To list a specific migration and check if errors are causing the migration to fail, use the –e option.

For an example that shows how these commands are used, see Example 38, Starting and Monitoring File System Migrations.


Caution

Caution  -  When migrating file systems, observe the following rules:

  • Do not add or remove data from the file system while it is being migrated. Otherwise, those changes are excluded from migration.
  • Do not change the mountpoint property of the shadow file system while migration is in progress.


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 remote and local 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. If necessary, install the shadow-migration package on the target system.
    $ pkg install shadow-migration
  3. Enable the shadowd service.
    $ svcadm enable shadowd
  4. 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 as read-only. For example:

      $ share -F nfs -o ro /export/home/ufsdata
      
  5. Create the target file system while setting the shadow file to the file system to be migrated.

    Note -  The new target ZFS file system must be completely empty. Otherwise, migration will not start.

    Specify the shadow setting depending on the type of system you are migrating.

    • If you are migrating a local file system, specify the source path.

      For example:

      $ zfs create -o shadow=file:///west/home/data users/home/shadow
    • If you are migrating a NFS file system. specify the source host name and path.

      For example:

      $ zfs create -o shadow=nfs://neo/export/home/ufsdata users/home/shadow2
  6. (Optional) To check the progress of the migration, issue the shadowstat command.

    For examples of how to monitor migrations, see Example 38, Starting and Monitoring File System Migrations.


    Note -  Migrating file system data over NFS can be slow, depending on your network bandwidth. If the system is rebooted during migration, the migration continues after the system boot completes.
Example 38  Starting and Monitoring File System Migrations

In this example, multiple migrations are initiated. The shadowadm command lists ongoing migrations while the shadowstat command monitors their progress.

$ zfs create -o shadow=nfs://system2/rpool/data/jsmith/archive rpool/data/copyarchive
$ shadowadm list
PATH                                        STATE
/rpool/data/copyarchive                     ACTIVE

$ zfs create -o shadow=nfs://system2/rpool/data/jsmith/datlogs rpool/data/logcopy
$ shadowadm list
PATH                                        STATE
/rpool/data/copyarchive                     ACTIVE
/rpool/data/logcopy                         ACTIVE

$ shadowstat
                                        EST
                                BYTES   BYTES           ELAPSED
DATASET                         XFRD    LEFT    ERRORS  TIME
rpool/data/copyarchive          34.4M   3.37G   -       00:00:36
rpool/data/logcopy              1.12K   155K    1       (completed)Errors are detected.
rpool/data/copyarchive          34.5M   3.37G   -       00:00:37
rpool/data/logcopy              1.12K   155K    1       (completed)
rpool/data/copyarchive          35.0M   3.37G   -       00:00:38
rpool/data/logcopy              1.12K   155K    1       (completed)
rpool/data/copyarchive          35.2M   3.37G   -       00:00:39
rpool/data/logcopy              1.12K   155K    1       (completed)
^C

The previous shadowstat output indicates errors in the migration to rpool/data/logcopy.

The following output from the shadowstat –E and –e command options shows that migration to rpool/data/logcopy could not be completed because socket migration is not supported. The shadowadm command cancels the migration.

$ shadowstat -E
rpool/data/copyarchive:
No errors encountered.
rpool/data/logcopy:
PATH                                                   ERROR
errdir/cups-socket                                     Operation not supported

$ shadowstat -e /rpool/data/logcopy
rpool/data/logcopy:
PATH                                                   ERROR
errdir/cups-socket                                     Operation not supported

$ shadowadm cancel /rpool/data/logcopy

The following output shows information about the migration to rpool/data/copyarchive, which continues toward completion.

$ shadowadm list
PATH                                        STATE
/rpool/data/copyarchive                     ACTIVE$ shadowstat
                                        EST             
                                BYTES   BYTES           ELAPSED
DATASET                         XFRD    LEFT    ERRORS  TIME
rpool/data/copyarchive          251M    3.16G   -       00:01:27
rpool/data/copyarchive          251M    3.16G   -       00:01:28
rpool/data/copyarchive          252M    3.16G   -       00:01:29
^C

$ shadowstat
No migrations in progress.
$ shadowadm list
$ exit