Go to main content

Managing ZFS File Systems in Oracle® Solaris 11.4

Exit Print View

Updated: July 2019
 
 

Migrating ZFS Storage Pools

Occasionally, you might need to move a storage pool between systems. You would disconnect the storage devices from the original system and reconnect them to the destination system either by physically recabling the devices or by using multiported devices such as the devices on a SAN.

ZFS enables you to export the pool from one system and import it on the destination system even if the systems are of different architectural endianness. For information about replicating or migrating file systems between different storage pools, which might reside on different systems, see Saving, Sending, and Receiving ZFS Data.

Preparing for ZFS Storage Pool Migration

To migrate a pool, you must first export it. This operation flushes any unwritten data to disk, writes data to the disk indicating that the export is complete, and removes all information about the pool from the system.

If you do not explicitly export the pool but instead remove the disks manually, you can still import the resulting pool on another system. However, you might lose the last few seconds of data transactions. Also, because the devices are no longer present, the pool will appear as UNAVAIL on the original system. By default, the destination system cannot import a pool that has not been explicitly exported. This condition is necessary to prevent you from accidentally importing an active pool that consists of network-attached storage that is still in use on another system.

Exporting a ZFS Storage Pool

To export a pool, use the following command:

$ zpool export [option] pool

The command first unmounts any mounted file systems within the pool. If any of the file systems fail to unmount, you can forcefully unmount them by using the –f option. However, if ZFS volumes in the pool are in use, the operation fails even with the –f option. To export a pool with a ZFS volume, first ensure that all consumers of the volume are no longer active.

For more information, see ZFS Volumes.

After this command is executed, the pool is no longer visible on the system.

If devices are unavailable at the time of export, the devices cannot be identified as cleanly exported. If one of these devices is later attached to a system without any of the other working devices, it appears as potentially active.

Determining Available Storage Pools to Import

After the pool has been removed from the system, you can attach the devices to the target system. You do not need to attach them under the same device name. ZFS detects any moved or renamed devices and adjusts the configuration appropriately. Note that ZFS can handle some situations in which only some of the devices are available. However, a successful pool migration depends on the overall health of all the devices.

Use the following general command syntax for all pool import operations:

$ zpool import [options] [pool|ID-number]

To discover available pools that can be imported, run the zpool import command without specifying pools. In the output, the pools are identified by names and unique number identifiers. If pools available for import share the same name, use the numeric identifier to import the correct pool.

If problems exist with a pool to be imported, the command output also provides the appropriate information to help you determine what action to take.

In the following example, one of the devices is missing but you can still import the pool because the mirrored data remains accessible.

$ zpool import
 pool: system1
    id: 4715259469716913940
 state: DEGRADED
status: One or more devices are unavailable.
action: The pool can be imported despite missing or damaged devices.  The
        fault tolerance of the pool may be compromised if imported.
config:

    system1                         DEGRADED
       mirror-0                     DEGRADED
         c0t5000C500335E106Bd0      ONLINE
         c0t5000C500335FC3E7d0      UNAVAIL  cannot open

device details:

         c0t5000C500335FC3E7d0     UNAVAIL   cannot open
         status: ZFS detected errors on this device.
                The device was missing.

In the following example, because two disks are missing from a RAID-Z virtual device, not enough redundant data exists to reconstruct the pool. With insufficient available devices, ZFS cannot import the pool.

$ zpool import
pool: mothership
    id: 3702878663042245922
 state: UNAVAIL
status: One or more devices are unavailable.
action: The pool cannot be imported due to unavailable devices or data.
config:

        mothership     UNAVAIL  insufficient replicas
          raidz1-0     UNAVAIL  insufficient replicas
            c8t0d0     UNAVAIL  cannot open
            c8t1d0     UNAVAIL  cannot open
            c8t2d0     ONLINE
            c8t3d0     ONLINE

device details:

        c8t0d0    UNAVAIL          cannot open
        status: ZFS detected errors on this device.
                The device was missing.

        c8t1d0    UNAVAIL          cannot open
        status: ZFS detected errors on this device.
                The device was missing.

Importing ZFS Storage Pools

To import a specific pool, specify the pool name or its numeric identifier with the zfs import command. Additionally, you can rename a pool while importing it. For example:

$ zpool import system1 mpool

This command imports the exported pool system1 and renames it mpool. The new pool name is persistent.


Note -  You cannot rename a pool directly. You can only change the name of a pool while exporting and importing the pool, which also renames the root dataset to the new pool name.

Caution

Caution  -  During an import operation, warnings occur if the pool might be in use on another system.

cannot import 'pool': pool may be in use on another system
use '-f' to import anyway
Do not attempt to import a pool that is active on one system to another system. ZFS is not a native cluster, distributed, or parallel file system and cannot provide concurrent access from multiple, different systems.


You can also import pools under an alternate root by using the –R option. For more information, see Using a ZFS Pool With an Alternate Root Location.

Importing a Pool With a Missing Log Device

By default, a pool with a missing log device cannot be imported. You can use zpool import –m command to force a pool to be imported with a missing log device.

In the following example, the output indicates a missing mirrored log when you first import the pool dozer.

$ zpool import dozer
The devices below are missing, use '-m' to import the pool anyway:
mirror-1 [log]
c3t3d0
c3t4d0

cannot import 'dozer': one or more devices is currently unavailable

To proceed with importing the pool with the missing mirrored log, use the –m option.

$ zpool import -m dozer
$ zpool status dozer
pool: dozer
state: DEGRADED
status: One or more devices could not be opened.  Sufficient replicas exist for
the pool to continue functioning in a degraded state.
action: Attach the missing device and online it using 'zpool online'.
see: URL to My Oracle Support knowledge article
scan: scrub repaired 0 in 0h0m with 0 errors on Fri Oct 15 16:51:39 2010
config:

NAME                   STATE     READ  WRITE  CKSUM
dozer                  DEGRADED     0      0      0
   mirror-0            ONLINE       0      0      0
      c3t1d0           ONLINE       0      0      0
      c3t2d0           ONLINE       0      0      0
   logs
   mirror-1                 UNAVAIL      0     0     0  insufficient replicas
      13514061426445294202  UNAVAIL      0     0     0  was c3t3d0
      16839344638582008929  UNAVAIL      0     0     0  was c3t4d0

The imported pool remains in a DEGRADED state. Based on the output recommendation, attach the missing log devices. Then, run the zpool clear command to clear the pool errors.

Importing a Pool in Read-Only Mode

If a pool is so damaged that it cannot be accessed, importing in read-only mode might enable you to recover the pool's data. For example:

$ zpool import -o readonly=on system1
$ zpool scrub system1
cannot scrub system1: pool is read-only

When a pool is imported in read-only mode, the following conditions apply:

  • All file systems and volumes are mounted in read-only mode.

  • Pool transaction processing is disabled. Any pending synchronous writes in the intent log are not made until the pool is imported in read-write mode.

  • Setting a pool property during the read-only import is ignored.

You can set the pool back to read-write mode by exporting and importing the pool. For example:

$ zpool export system1
$ zpool import system1
$ zpool scrub system1

Importing a Pool By Using a Specific Device Path

By default, the zpool import command searches devices only within the /dev/dsk directory. If devices exist in another directory, or you are using pools backed by files, you must use the –d option to search alternate directories. For example:

$ zpool create mpool mirror /file/a /file/b
$ zpool export mpool
$ zpool import -d /file
  pool: mpool
    id: 7318163511366751416
 state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:

        mpool        ONLINE
          mirror-0   ONLINE
            /file/a  ONLINE
            /file/b  ONLINE
$ zpool import -d /file mpool

If devices exist in multiple directories, you can specify multiple –d options.

The following command imports the pool mpool by identifying one of the pool's specific devices, /dev/etc/c2t3d0:

$ zpool import -d /dev/etc/c2t3d0 mpool
$ zpool status mpool
pool: mpool
state: ONLINE
scan: resilvered 952K in 0h0m with 0 errors on Fri Jun 29 16:22:06 2012
config:

NAME        STATE     READ WRITE CKSUM
mpool       ONLINE       0     0     0
mirror-0    ONLINE       0     0     0
  c2t3d0    ONLINE       0     0     0
  c2t1d0    ONLINE       0     0     0

Recovering Destroyed ZFS Storage Pools

You can use the zpool import –D command to recover a storage pool that has been destroyed.

In the following example, the pool system1 is indicated as destroyed.

$ zpool import -D
  pool: system1
    id: 5154272182900538157
 state: ONLINE (DESTROYED)
action: The pool can be imported using its name or numeric identifier.
config:

        system1     ONLINE
          mirror-0  ONLINE
            c1t0d0  ONLINE
            c1t1d0  ONLINE

To recover the destroyed pool, import it with the –D option.

$ zpool import -D system1
$ zpool status system1
  pool: system1
 state: ONLINE
 scrub: none requested
config:

        NAME        STATE     READ WRITE CKSUM
        system1     ONLINE       0     0     0
          mirror-0  ONLINE       0     0     0
            c1t0d0  ONLINE       0     0     0
            c1t1d0  ONLINE       0     0     0

errors: No known data errors

If one of the devices in the destroyed pool is unavailable, you might still recover the destroyed pool by including the –f option. In this scenario, you would import the degraded pool and then attempt to fix the device failure. For example:

$ zpool import -D
  pool: dozer
    id: 4107023015970708695
 state: DEGRADED (DESTROYED)
status: One or more devices are unavailable.
action: The pool can be imported despite missing or damaged devices.  The
        fault tolerance of the pool may be compromised if imported.
config:

        dozer              DEGRADED
          raidz2-0         DEGRADED
            c8t0d0         ONLINE
            c8t1d0         ONLINE
            c8t2d0         ONLINE
            c8t3d0         UNAVAIL  cannot open
            c8t4d0         ONLINE

device details:

        c8t3d0    UNAVAIL          cannot open
        status: ZFS detected errors on this device.
                The device was missing.
$ zpool import -Df dozer
$ zpool status -x
  pool: dozer
 state: DEGRADED
status: One or more devices are unavailable in response to persistent errors.
        Sufficient replicas exist for the pool to continue functioning in a
        degraded state.
action: Determine if the device needs to be replaced, and clear the errors
        using 'zpool clear' or 'fmadm repaired', or replace the device
        with 'zpool replace'.
        Run 'zpool status -v' to see device specific details.
  scan: none requested
config:

        NAME                     STATE     READ WRITE CKSUM
        dozer                    DEGRADED     0     0     0
          raidz2-0               DEGRADED     0     0     0
            c8t0d0               ONLINE       0     0     0
            c8t1d0               ONLINE       0     0     0
            c8t2d0               ONLINE       0     0     0
            4881130428504041127  UNAVAIL      0     0     0
            c8t4d0               ONLINE       0     0     0

errors: No known data errors
$ zpool online dozer c8t3d0
$ zpool status -x
all pools are healthy