'\" te

.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.

.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.

.\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the

.\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]

.SH NAME

zpool \- configures ZFS storage pools

.SH SYNOPSIS

.LP

.nf

\fBzpool\fR [\fB-?\fR]

.fi

.LP

.nf

\fBzpool add\fR [\fB-fn\fR] \fIpool\fR \fIvdev\fR ...

.fi

.LP

.nf

\fBzpool attach\fR [\fB-f\fR] \fIpool\fR \fIdevice\fR \fInew_device\fR

.fi

.LP

.nf

\fBzpool clear\fR \fIpool\fR [\fIdevice\fR]

.fi

.LP

.nf

\fBzpool create\fR [\fB-fn\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-O\fR \fIfile-system-property=value\fR]

     ... [\fB-m\fR \fImountpoint\fR] [\fB-R\fR \fIroot\fR] \fIpool\fR \fIvdev\fR ...

.fi

.LP

.nf

\fBzpool destroy\fR [\fB-f\fR] \fIpool\fR

.fi

.LP

.nf

\fBzpool detach\fR \fIpool\fR \fIdevice\fR

.fi

.LP

.nf

\fBzpool export\fR [\fB-f\fR] \fIpool\fR ...

.fi

.LP

.nf

\fBzpool get\fR "\fIall\fR" | \fIproperty\fR[,...] \fIpool\fR ...

.fi

.LP

.nf

\fBzpool history\fR [\fB-il\fR] [\fIpool\fR] ...

.fi

.LP

.nf

\fBzpool import\fR [\fB-d\fR \fIdir\fR] [\fB-D\fR]

.fi

.LP

.nf

\fBzpool import\fR [\fB-o \fImntopts\fR\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]

     [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fB-a\fR

.fi

.LP

.nf

\fBzpool import\fR [\fB-o \fImntopts\fR\fR] [\fB-o\fR \fIproperty=value\fR] ... [\fB-d\fR \fIdir\fR | \fB-c\fR \fIcachefile\fR]

     [\fB-D\fR] [\fB-f\fR] [\fB-R\fR \fIroot\fR] \fIpool\fR |\fIid\fR [\fInewpool\fR]

.fi

.LP

.nf

\fBzpool iostat\fR [\fB-T\fR u | d ] [\fB-v\fR] [\fIpool\fR] ... [\fIinterval\fR[\fIcount\fR]]

.fi

.LP

.nf

\fBzpool list\fR [\fB-H\fR] [\fB-o\fR \fIproperty\fR[,...]] [\fIpool\fR] ...

.fi

.LP

.nf

\fBzpool offline\fR [\fB-t\fR] \fIpool\fR \fIdevice\fR ...

.fi

.LP

.nf

\fBzpool online\fR \fIpool\fR \fIdevice\fR ...

.fi

.LP

.nf

\fBzpool reguid\fR \fIpool\fR

.fi

.LP

.nf

\fBzpool remove\fR \fIpool\fR \fIdevice\fR ...

.fi

.LP

.nf

\fBzpool replace\fR [\fB-f\fR] \fIpool\fR \fIdevice\fR [\fInew_device\fR]

.fi

.LP

.nf

\fBzpool scrub\fR [\fB-s\fR] \fIpool\fR ...

.fi

.LP

.nf

\fBzpool set\fR \fIproperty\fR=\fIvalue\fR \fIpool\fR

.fi

.LP

.nf

\fBzpool status\fR [\fB-xv\fR] [\fIpool\fR] ...

.fi

.LP

.nf

\fBzpool upgrade\fR

.fi

.LP

.nf

\fBzpool upgrade\fR \fB-v\fR

.fi

.LP

.nf

\fBzpool upgrade\fR [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIpool\fR ...

.fi

.SH DESCRIPTION

.sp

.LP

The \fBzpool\fR command configures \fBZFS\fR storage pools. A storage pool is a

collection of devices that provides physical storage and data replication for

\fBZFS\fR datasets.

.sp

.LP

All datasets within a storage pool share the same space. See \fBzfs\fR(1M) for

information on managing datasets.

.SS "Virtual Devices (\fBvdev\fRs)"

.sp

.LP

A "virtual device" describes a single device or a collection of devices

organized according to certain performance and fault characteristics. The

following virtual devices are supported:

.sp

.ne 2

.na

\fB\fBdisk\fR\fR

.ad

.RS 10n

A block device, typically located under \fB/dev/dsk\fR. \fBZFS\fR can use

individual slices or partitions, though the recommended mode of operation is to

use whole disks. A disk can be specified by a full path, or it can be a

shorthand name (the relative portion of the path under "/dev/dsk"). A whole

disk can be specified by omitting the slice or partition designation. For

example, "c0t0d0" is equivalent to "/dev/dsk/c0t0d0s2". When given a whole

disk, \fBZFS\fR automatically labels the disk, if necessary.

.RE

.sp

.ne 2

.na

\fB\fBfile\fR\fR

.ad

.RS 10n

A regular file. The use of files as a backing store is strongly discouraged. It

is designed primarily for experimental purposes, as the fault tolerance of a

file is only as good as the file system of which it is a part. A file must be

specified by a full path.

.RE

.sp

.ne 2

.na

\fB\fBmirror\fR\fR

.ad

.RS 10n

A mirror of two or more devices. Data is replicated in an identical fashion

across all components of a mirror. A mirror with \fIN\fR disks of size \fIX\fR

can hold \fIX\fR bytes and can withstand (\fIN-1\fR) devices failing before

data integrity is compromised.

.RE

.sp

.ne 2

.na

\fB\fBraidz\fR\fR

.ad

.br

.na

\fB\fBraidz1\fR\fR

.ad

.br

.na

\fB\fBraidz2\fR\fR

.ad

.br

.na

\fB\fBraidz3\fR\fR

.ad

.RS 10n

A variation on \fBRAID-5\fR that allows for better distribution of parity and

eliminates the "\fBRAID-5\fR write hole" (in which data and parity become

inconsistent after a power loss). Data and parity is striped across all disks

within a \fBraidz\fR group.

.sp

A \fBraidz\fR group can have single-, double- , or triple parity, meaning that

the \fBraidz\fR group can sustain one, two, or three failures, respectively,

without losing any data. The \fBraidz1\fR \fBvdev\fR type specifies a

single-parity \fBraidz\fR group; the \fBraidz2\fR \fBvdev\fR type specifies a

double-parity \fBraidz\fR group; and the \fBraidz3\fR \fBvdev\fR type specifies

a triple-parity \fBraidz\fR group. The \fBraidz\fR \fBvdev\fR type is an alias

for \fBraidz1\fR.

.sp

A \fBraidz\fR group with \fIN\fR disks of size \fIX\fR with \fIP\fR parity

disks can hold approximately (\fIN-P\fR)*\fIX\fR bytes and can withstand

\fIP\fR device(s) failing before data integrity is compromised. The minimum

number of devices in a \fBraidz\fR group is one more than the number of parity

disks. The recommended number is between 3 and 9 to help increase performance.

.RE

.sp

.ne 2

.na

\fB\fBspare\fR\fR

.ad

.RS 10n

A special pseudo-\fBvdev\fR which keeps track of available hot spares for a

pool. For more information, see the "Hot Spares" section.

.RE

.sp

.ne 2

.na

\fB\fBlog\fR\fR

.ad

.RS 10n

A separate-intent log device. If more than one log device is specified, then

writes are load-balanced between devices. Log devices can be mirrored. However,

\fBraidz\fR \fBvdev\fR types are not supported for the intent log. For more

information, see the "Intent Log" section.

.RE

.sp

.ne 2

.na

\fB\fBcache\fR\fR

.ad

.RS 10n

A device used to cache storage pool data. A cache device cannot be cannot be

configured as a mirror or \fBraidz\fR group. For more information, see the

"Cache Devices" section.

.RE

.sp

.LP

Virtual devices cannot be nested, so a mirror or \fBraidz\fR virtual device can

only contain files or disks. Mirrors of mirrors (or other combinations) are not

allowed.

.sp

.LP

A pool can have any number of virtual devices at the top of the configuration

(known as "root vdevs"). Data is dynamically distributed across all top-level

devices to balance data among devices. As new virtual devices are added,

\fBZFS\fR automatically places data on the newly available devices.

.sp

.LP

Virtual devices are specified one at a time on the command line, separated by

whitespace. The keywords "mirror" and "raidz" are used to distinguish where a

group ends and another begins. For example, the following creates two root

vdevs, each a mirror of two disks:

.sp

.in +2

.nf

# \fBzpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0\fR

.fi

.in -2

.sp

.SS "Device Failure and Recovery"

.sp

.LP

\fBZFS\fR supports a rich set of mechanisms for handling device failure and

data corruption. All metadata and data is checksummed, and \fBZFS\fR

automatically repairs bad data from a good copy when corruption is detected.

.sp

.LP

In order to take advantage of these features, a pool must make use of some form

of redundancy, using either mirrored or \fBraidz\fR groups. While \fBZFS\fR

supports running in a non-redundant configuration, where each root vdev is

simply a disk or file, this is strongly discouraged. A single case of bit

corruption can render some or all of your data unavailable.

.sp

.LP

A pool's health status is described by one of three states: online, degraded,

or faulted. An online pool has all devices operating normally. A degraded pool

is one in which one or more devices have failed, but the data is still

available due to a redundant configuration. A faulted pool has corrupted

metadata, or one or more faulted devices, and insufficient replicas to continue

functioning.

.sp

.LP

The health of the top-level vdev, such as mirror or \fBraidz\fR device, is

potentially impacted by the state of its associated vdevs, or component

devices. A top-level vdev or component device is in one of the following

states:

.sp

.ne 2

.na

\fB\fBDEGRADED\fR\fR

.ad

.RS 12n

One or more top-level vdevs is in the degraded state because one or more

component devices are offline. Sufficient replicas exist to continue

functioning.

.sp

One or more component devices is in the degraded or faulted state, but

sufficient replicas exist to continue functioning. The underlying conditions

are as follows:

.RS +4

.TP

.ie t \(bu

.el o

The number of checksum errors exceeds acceptable levels and the device is

degraded as an indication that something may be wrong. \fBZFS\fR continues to

use the device as necessary.

.RE

.RS +4

.TP

.ie t \(bu

.el o

The number of I/O errors exceeds acceptable levels. The device could not be

marked as faulted because there are insufficient replicas to continue

functioning.

.RE

.RE

.sp

.ne 2

.na

\fB\fBFAULTED\fR\fR

.ad

.RS 12n

One or more top-level vdevs is in the faulted state because one or more

component devices are offline. Insufficient replicas exist to continue

functioning.

.sp

One or more component devices is in the faulted state, and insufficient

replicas exist to continue functioning. The underlying conditions are as

follows:

.RS +4

.TP

.ie t \(bu

.el o

The device could be opened, but the contents did not match expected values.

.RE

.RS +4

.TP

.ie t \(bu

.el o

The number of I/O errors exceeds acceptable levels and the device is faulted to

prevent further use of the device.

.RE

.RE

.sp

.ne 2

.na

\fB\fBOFFLINE\fR\fR

.ad

.RS 12n

The device was explicitly taken offline by the "\fBzpool offline\fR" command.

.RE

.sp

.ne 2

.na

\fB\fBONLINE\fR\fR

.ad

.RS 12n

The device is online and functioning.

.RE

.sp

.ne 2

.na

\fB\fBREMOVED\fR\fR

.ad

.RS 12n

The device was physically removed while the system was running. Device removal

detection is hardware-dependent and may not be supported on all platforms.

.RE

.sp

.ne 2

.na

\fB\fBUNAVAIL\fR\fR

.ad

.RS 12n

The device could not be opened. If a pool is imported when a device was

unavailable, then the device will be identified by a unique identifier instead

of its path since the path was never correct in the first place.

.RE

.sp

.LP

If a device is removed and later re-attached to the system, \fBZFS\fR attempts

to put the device online automatically. Device attach detection is

hardware-dependent and might not be supported on all platforms.

.SS "Hot Spares"

.sp

.LP

\fBZFS\fR allows devices to be associated with pools as "hot spares". These

devices are not actively used in the pool, but when an active device fails, it

is automatically replaced by a hot spare. To create a pool with hot spares,

specify a "spare" \fBvdev\fR with any number of devices. For example,

.sp

.in +2

.nf

# zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0

.fi

.in -2

.sp

.sp

.LP

Spares can be shared across multiple pools, and can be added with the "\fBzpool

add\fR" command and removed with the "\fBzpool remove\fR" command. Once a spare

replacement is initiated, a new "spare" \fBvdev\fR is created within the

configuration that will remain there until the original device is replaced. At

this point, the hot spare becomes available again if another device fails.

.sp

.LP

If a pool has a shared spare that is currently being used, the pool can not be

exported since other pools may use this shared spare, which may lead to

potential data corruption.

.sp

.LP

An in-progress spare replacement can be cancelled by detaching the hot spare.

If the original faulted device is detached, then the hot spare assumes its

place in the configuration, and is removed from the spare list of all active

pools.

.sp

.LP

Spares cannot replace log devices.

.SS "Intent Log"

.sp

.LP

The \fBZFS\fR Intent Log (\fBZIL\fR) satisfies \fBPOSIX\fR requirements for

synchronous transactions. For instance, databases often require their

transactions to be on stable storage devices when returning from a system call.

\fBNFS\fR and other applications can also use \fBfsync\fR() to ensure data

stability. By default, the intent log is allocated from blocks within the main

pool. However, it might be possible to get better performance using separate

intent log devices such as \fBNVRAM\fR or a dedicated disk. For example:

.sp

.in +2

.nf

\fB# zpool create pool c0d0 c1d0 log c2d0\fR

.fi

.in -2

.sp

.sp

.LP

Multiple log devices can also be specified, and they can be mirrored. See the

EXAMPLES section for an example of mirroring multiple log devices.

.sp

.LP

Log devices can be added, replaced, attached, detached, and imported and

exported as part of the larger pool. Mirrored log devices can be removed by

specifying the top-level mirror for the log.

.SS "Cache Devices"

.sp

.LP

Devices can be added to a storage pool as "cache devices." These devices

provide an additional layer of caching between main memory and disk. For

read-heavy workloads, where the working set size is much larger than what can

be cached in main memory, using cache devices allow much more of this working

set to be served from low latency media. Using cache devices provides the

greatest performance improvement for random read-workloads of mostly static

content.

.sp

.LP

To create a pool with cache devices, specify a "cache" \fBvdev\fR with any

number of devices. For example:

.sp

.in +2

.nf

\fB# zpool create pool c0d0 c1d0 cache c2d0 c3d0\fR

.fi

.in -2

.sp

.sp

.LP

Cache devices cannot be mirrored or part of a \fBraidz\fR configuration. If a

read error is encountered on a cache device, that read \fBI/O\fR is reissued to

the original storage pool device, which might be part of a mirrored or

\fBraidz\fR configuration.

.sp

.LP

The content of the cache devices is considered volatile, as is the case with

other system caches.

.SS "Properties"

.sp

.LP

Each pool has several properties associated with it. Some properties are

read-only statistics while others are configurable and change the behavior of

the pool. The following are read-only properties:

.sp

.ne 2