4.5 Device Management

Most of the basic information regarding devices is covered in 4.1 Virtual Devices. Once a pool has been created, there are a number of tasks to be done when managing the physical devices within the pool.

4.5.1 Adding Devices to a Pool

Space can be dynamically added to a pool by adding a new top-level virtual device. This space is immediately available to all datasets within the pool. To add a new virtual device to a pool, use the zpool add command:

# zpool add scoop mirror c0t1d0 c1t1d0

The format of the virtual devices is the same as for the zpool create command, and the same rules apply. Devices are checked to see if they are in use, and the command refuses to change the replication level unless the -f flag is given. The command also supports the -n option to do a dry run:

# zpool add -n scoop mirror c0t2d0 c1t2d0
would update 'scoop' to the following configuration:
      scoop
        mirror
            c0t0d0
            c1t0d0
        mirror
            c0t1d0
            c1t1d0
        mirror
            c0t2d0
            c1t2d0

The above command syntax would add mirrored devices c0t2d0 and c1t2d0 to pool scoop's existing configuration.

For more information on how virtual device validation is done, see 4.4.2.1 Detecting In-Use Devices.

4.5.2 Onlining and Offlining Devices

ZFS allows individual devices to be taken offline or brought online. When hardware is flaky or otherwise bad, ZFS will continue to read or write data to the device, assuming the condition is only temporary. If this is not a temporary condition, it is possible to tell ZFS to ignore the device by bringing it offline. ZFS will no longer send any requests to an offlined device.

Devices do not need to be offlined in order to replace them.

Bringing a device offline is an informational hint to ZFS to avoid sending requests to the device.

4.5.2.1 Taking a Device Offline

To take a device offline, use the zpool offline command. The device can be specified by path, or short name (if it is a disk). For example:

# zpool offline tank c0t0d0
bringing device 'c0t0d0' offline

You cannot offline a pool to the point where it becomes faulted. For example, you cannot offline two devices out of a RAID-Z configuration, nor can you offline a top-level virtual device. Offlined devices show up in the OFFLINE state when querying pool status. If you truly want to offline a device and cause your pool to become faulted, you can do so using the -f flag. Note that doing so prevents any data from being accessed, and may result in I/O errors and system panics.

# zpool offline tank c0t0d0
cannot offline /dev/dsk/c1t2d0: no valid replicas

By default, the offline state is persistent; the device remains offline when the system is rebooted.

For more information on device health, see 4.6.3 Health Status.

4.5.2.2 Bringing a Device Online

Once a device is taken offline, it can be restored by using the zpool online command:

# zpool online tank c0t0d0
bringing device 'c0t0d0' online

When a device is brought online, any data that has been written to the pool is resynced to the newly available device. Note that you cannot use device onlining to replace a disk. If you offline a device, replace the drive, and try to bring it online, it remains in the faulted state.

For more information on replacing devices, see 9.6 Repairing a Damaged Device.

4.5.3 Replacing Devices

You can replace a device in a storage pool by using the zpool replace command.

# zpool replace tank c0t0d0 c0t0d1

In the above example, the previous device, c0t0d0, is replaced by c0t0d1.

The replacement device must be either equal in size or larger than the previous device. If the replacement device is larger, the pool size is increased when the replacement is complete.

For more information about replacing devices, see 9.5 Repairing a Missing Device and 9.6 Repairing a Damaged Device.

4.6 Querying Pool Status

The zpool(1M) command provides a number of ways to get information regarding pool status. The information available generally falls into three categories: basic usage information, I/O statistics, and health status. These are covered in this section.

4.6.1 Basic Pool Information

The zpool list command is used to display basic information about pools.

4.6.1.1 Listing All Information

With no arguments, the command displays all the fields for all pools on the system:

# zpool list
NAME                    SIZE    USED   AVAIL    CAP  HEALTH     ALTROOT
tank                   80.0G   22.3G   47.7G    28%  ONLINE     -
dozer                   1.2T    384G    816G    32%  ONLINE     -

The field display the following information:

You can also gather statistics for an individual pool by specifying the pool name:

# zpool list tank
NAME                    SIZE    USED   AVAIL    CAP  HEALTH     ALTROOT
tank                   80.0G   22.3G   47.7G    28%  ONLINE     -

4.6.1.2 Listing Individual Statistics

Individual statistics can be specified using the -o option. This allows for custom reports or a quick way to list pertinent information. For example, to list only the name and size of each pool:

# zpool list -o name,size
NAME                    SIZE
tank                   80.0G
dozer                   1.2T

The column names correspond to the properties listed in the previous section.