Migrating ZFS Storage Pools
Occasionally, you might need to move a storage pool between machines. To do
so, the storage devices must be disconnected from the original machine and reconnected
to the destination machine. This task can be accomplished 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 machine and import it
on the destination machine, even if the machines are of different endianness. For
information about replicating or migrating file systems between different storage pools, which might
reside on different machines, see Saving and Restoring ZFS Data.
Preparing for ZFS Storage Pool Migration
Storage pools should be explicitly exported to indicate that they are ready to
be migrated. This operation flushes any unwritten data to disk, writes data to
the disk indicating that the export was done, and removes all knowledge of
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, and the pool
will appear faulted on the original machine because the devices are no longer
present. By default, the destination machine refuses to import a pool that has
not been explicitly exported. This condition is necessary to prevent 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 zpool export command. For example:
# zpool export tank
Once this command is executed, the pool tank is no longer visible on
the system. The command attempts to unmount any mounted file systems within the
pool before continuing. If any of the file systems fail to unmount, you
can forcefully unmount them by using the -f option. For example:
# zpool export tank
cannot unmount '/export/home/eschrock': Device busy
# zpool export -f tank
If devices are unavailable at the time of export, the disks cannot
be specified as cleanly exported. If one of these devices is later attached
to a system without any of the working devices, it appears as “potentially active.”
If ZFS volumes are in use in the pool, the pool cannot
be exported, even with the -f option. To export a pool with an
ZFS volume, first make sure that all consumers of the volume are no
longer active.
For more information about ZFS volumes, see ZFS Volumes.
Determining Available Storage Pools to Import
Once the pool has been removed from the system (either through export or
by forcefully removing the devices), attach the devices to the target system. Although
ZFS can handle some situations in which only a portion of the
devices is available, all devices within the pool must be moved between the
systems. The devices do not necessarily have to be attached under the same
device name. ZFS detects any moved or renamed devices, and adjusts the configuration
appropriately. To discover available pools, run the zpool import command with no options. For example:
# zpool import
pool: tank
id: 3778921145927357706
state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:
tank ONLINE
mirror ONLINE
c1t0d0 ONLINE
c1t1d0 ONLINEIn this example, the pool tank is available to be imported on the
target system. Each pool is identified by a name as well as a
unique numeric identifier. If multiple pools available to import have the same name,
you can use the numeric identifier to distinguish between them.
Similar to the zpool status command, the zpool import command refers to a knowledge
article available on the web with the most up-to-date information regarding repair procedures
for a problem that is preventing a pool from being imported. In this
case, the user can force the pool to be imported. However, importing a
pool that is currently in use by another system over a storage network
can result in data corruption and panics as both systems attempt to write
to the same storage. If some devices in the pool are not available
but enough redundancy is available to have a usable pool, the pool appears
in the DEGRADED state. For example:
# zpool import
pool: tank
id: 3778921145927357706
state: DEGRADED
status: One or more devices are missing from the system.
action: The pool can be imported despite missing or damaged devices. The
fault tolerance of the pool may be compromised if imported.
see: https://www.sun.com/msg/ZFS-8000-2Q
config:
tank DEGRADED
mirror DEGRADED
c1t0d0 UNAVAIL cannot open
c1t1d0 ONLINEIn this example, the first disk is damaged or missing, though you
can still import the pool because the mirrored data is still accessible. If
too many faulted or missing devices are present, the pool cannot be imported. For
example:
# zpool import
pool: dozer
id: 12090808386336829175
state: FAULTED
action: The pool cannot be imported. Attach the missing
devices and try again.
see: https://www.sun.com/msg/ZFS-8000-6X
config:
raidz FAULTED
c1t0d0 ONLINE
c1t1d0 FAULTED
c1t2d0 ONLINE
c1t3d0 FAULTEDIn this example, two disks are missing from a RAID-Z virtual device, which
means that sufficient redundant data is not available to reconstruct the pool. In
some cases, not enough devices are present to determine the complete configuration. In
this case, ZFS doesn't know what other devices were part of the pool,
though ZFS does report as much information as possible about the situation. For
example:
# zpool import
pool: dozer
id: 12090808386336829175
state: FAULTED
status: One or more devices are missing from the system.
action: The pool cannot be imported. Attach the missing
devices and try again.
see: https://www.sun.com/msg/ZFS-8000-6X
config:
dozer FAULTED missing device
raidz ONLINE
c1t0d0 ONLINE
c1t1d0 ONLINE
c1t2d0 ONLINE
c1t3d0 ONLINE
Additional devices are known to be part of this pool, though their
exact configuration cannot be determined.
Finding ZFS Storage Pools From Alternate Directories
By default, the zpool import command only searches devices 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 different directories. For example:
# zpool create dozer mirror /file/a /file/b
# zpool export dozer
# zpool import -d /file
pool: dozer
id: 10952414725867935582
state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:
dozer ONLINE
mirror ONLINE
/file/a ONLINE
/file/b ONLINE
# zpool import -d /file dozerIf devices exist in multiple directories, you can specify multiple -d options.
Importing ZFS Storage Pools
Once a pool has been identified for import, you can import it
by specifying the name of the pool or its numeric identifier as an
argument to the zpool import command. For example:
# zpool import tank
If multiple available pools have the same name, you can specify which pool
to import using the numeric identifier. For example:
# zpool import
pool: dozer
id: 2704475622193776801
state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:
dozer ONLINE
c1t9d0 ONLINE
pool: dozer
id: 6223921996155991199
state: ONLINE
action: The pool can be imported using its name or numeric identifier.
config:
dozer ONLINE
c1t8d0 ONLINE
# zpool import dozer
cannot import 'dozer': more than one matching pool
import by numeric ID instead
# zpool import 6223921996155991199If the pool name conflicts with an existing pool name, you can
import the pool under a different name. For example:
# zpool import dozer zeepool
This command imports the exported pool dozer using the new name zeepool. If
the pool was not cleanly exported, ZFS requires the -f flag to prevent
users from accidentally importing a pool that is still in use on another
system. For example:
# zpool import dozer
cannot import 'dozer': pool may be in use on another system
use '-f' to import anyway
# zpool import -f dozer
Pools can also be imported under an alternate root by using the
-R option. For more information on alternate root pools, see Using ZFS Alternate Root Pools.
Recovering Destroyed ZFS Storage Pools
You can use the zpool import -D command to recover a storage pool that
has been destroyed. For example:
# zpool destroy tank
# zpool import -D
pool: tank
id: 3778921145927357706
state: ONLINE (DESTROYED)
action: The pool can be imported using its name or numeric identifier. The
pool was destroyed, but can be imported using the '-Df' flags.
config:
tank ONLINE
mirror ONLINE
c1t0d0 ONLINE
c1t1d0 ONLINEIn the above zpool import output, you can identify this pool as the destroyed
pool because of the following state information:
state: ONLINE (DESTROYED)
To recover the destroyed pool, issue the zpool import -D command again with
the pool to be recovered and the -f option. For example:
# zpool import -Df tank
# zpool status tank
pool: tank
state: ONLINE
scrub: none requested
config:
NAME STATE READ WRITE CKSUM
tank ONLINE 0 0 0
mirror ONLINE 0 0 0
c1t0d0 ONLINE 0 0 0
c1t1d0 ONLINE 0 0 0
errors: No known data errorsIf one of the devices in the destroyed pool is faulted or
unavailable, you might be able to recover the destroyed pool anyway. In this
scenario, import the degraded pool and then attempt to fix the device failure.
For example:
# zpool destroy dozer
# zpool import -D
pool: dozer
id:
state: DEGRADED (DESTROYED)
status: One or more devices are missing from the system.
action: The pool can be imported despite missing or damaged devices. The
fault tolerance of the pool may be compromised if imported. The
pool was destroyed, but can be imported using the '-Df' flags.
see: https://www.sun.com/msg/ZFS-8000-2Q
config:
dozer DEGRADED
raidz ONLINE
c1t0d0 ONLINE
c1t1d0 ONLINE
c1t2d0 UNAVAIL cannot open
c1t3d0 ONLINE
# zpool import -Df dozer
# zpool status -x
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: https://www.sun.com/msg/ZFS-8000-D3
scrub: resilver completed with 0 errors on Fri Mar 17 16:11:35 2006
config:
NAME STATE READ WRITE CKSUM
dozer DEGRADED 0 0 0
raidz ONLINE 0 0 0
c1t0d0 ONLINE 0 0 0
c1t1d0 ONLINE 0 0 0
c1t2d0 UNAVAIL 0 0 0 cannot open
c1t3d0 ONLINE 0 0 0
errors: No known data errors
# zpool online dozer c1t2d0
Bringing device c1t2d0 online
# zpool status -x
all pools are healthy
Upgrading ZFS Storage Pools
If you have ZFS storage pools from a previous Solaris release, such as
the Solaris 10 6/06 release, you can upgrade your pools with the
zpool upgrade command to take advantage of the pool features in the Solaris 10
11/06 release. In addition, the zpool status command has been modified to notify you
when your pools are running older versions. For example:
# zpool status
pool: test
state: ONLINE
status: The pool is formatted using an older on-disk format. The pool can
still be used, but some features are unavailable.
action: Upgrade the pool using 'zpool upgrade'. Once this is done, the
pool will no longer be accessible on older software versions.
scrub: none requested
config:
NAME STATE READ WRITE CKSUM
test ONLINE 0 0 0
c1t27d0 ONLINE 0 0 0
errors: No known data errorsYou can use the following syntax to identify additional information about a particular
version and supported releases.
# zpool upgrade -v
This system is currently running ZFS version 3.
The following versions are supported:
VER DESCRIPTION
--- --------------------------------------------------------
1 Initial ZFS version
2 Ditto blocks (replicated metadata)
3 Hot spares and double parity RAID-Z
For more information on a particular version, including supported releases, see:
https://www.opensolaris.org/os/community/zfs/version/N
Where 'N' is the version number.
Then, you can run the zpool upgrade command to upgrade your pools. For example:
# zpool upgrade -a
Note - If you upgrade your pools to the latest version, they will not be
accessible on systems that run older ZFS versions.
