.\"
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
-.\" Copyright (c) 2013 by Delphix. All rights reserved.
+.\" Copyright (c) 2012, 2018 by Delphix. All rights reserved.
.\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved.
.\" Copyright (c) 2017 Datto Inc.
-.\" Copyright (c) 2017 George Melikov. All Rights Reserved.
+.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
-.Dd August 23, 2017
+.Dd April 27, 2018
.Dt ZPOOL 8 SMM
.Os Linux
.Sh NAME
.Oo Fl o Ar property Ns = Ns Ar value Oc
.Ar pool device new_device
.Nm
+.Cm checkpoint
+.Op Fl d, -discard
+.Ar pool
+.Nm
.Cm clear
.Ar pool
.Op Ar device
.Nm
.Cm import
.Op Fl D
-.Op Fl d Ar dir
+.Op Fl d Ar dir Ns | Ns device
.Nm
.Cm import
.Fl a
.Op Fl DflmN
.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc
-.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
+.Op Fl -rewind-to-checkpoint
+.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
.Cm import
.Op Fl Dflm
.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc
-.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
+.Op Fl -rewind-to-checkpoint
+.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
.Ar pool
.Nm
.Cm remove
+.Op Fl np
.Ar pool Ar device Ns ...
.Nm
+.Cm remove
+.Fl s
+.Ar pool
+.Nm
.Cm replace
.Op Fl f
.Oo Fl o Ar property Ns = Ns Ar value Oc
.Sx EXAMPLES
section for an example of mirroring multiple log devices.
.Pp
-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.
+Log devices can be added, replaced, attached, detached and removed. In
+addition, log devices are imported and exported as part of the pool
+that contains them.
+Mirrored devices can be removed by specifying the top-level mirror vdev.
.Ss Cache Devices
Devices can be added to a storage pool as
.Qq cache devices .
.Pp
The content of the cache devices is considered volatile, as is the case with
other system caches.
+.Ss Pool checkpoint
+Before starting critical procedures that include destructive actions (e.g
+.Nm zfs Cm destroy
+), an administrator can checkpoint the pool's state and in the case of a
+mistake or failure, rewind the entire pool back to the checkpoint.
+Otherwise, the checkpoint can be discarded when the procedure has completed
+successfully.
+.Pp
+A pool checkpoint can be thought of as a pool-wide snapshot and should be used
+with care as it contains every part of the pool's state, from properties to vdev
+configuration.
+Thus, while a pool has a checkpoint certain operations are not allowed.
+Specifically, vdev removal/attach/detach, mirror splitting, and
+changing the pool's guid.
+Adding a new vdev is supported but in the case of a rewind it will have to be
+added again.
+Finally, users of this feature should keep in mind that scrubs in a pool that
+has a checkpoint do not repair checkpointed data.
+.Pp
+To create a checkpoint for a pool:
+.Bd -literal
+# zpool checkpoint pool
+.Ed
+.Pp
+To later rewind to its checkpointed state, you need to first export it and
+then rewind it during import:
+.Bd -literal
+# zpool export pool
+# zpool import --rewind-to-checkpoint pool
+.Ed
+.Pp
+To discard the checkpoint from a pool:
+.Bd -literal
+# zpool checkpoint -d pool
+.Ed
+.Pp
+Dataset reservations (controlled by the
+.Nm reservation
+or
+.Nm refreservation
+zfs properties) may be unenforceable while a checkpoint exists, because the
+checkpoint is allowed to consume the dataset's reservation.
+Finally, data that is part of the checkpoint but has been freed in the
+current state of the pool won't be scanned during a scrub.
.Ss Properties
Each pool has several properties associated with it.
Some properties are read-only statistics while others are configurable and
.Pp
The following are read-only properties:
.Bl -tag -width Ds
-.It Sy available
-Amount of storage available within the pool.
-This property can also be referred to by its shortened column name,
-.Sy avail .
+.It Cm allocated
+Amount of storage used within the pool.
.It Sy capacity
Percentage of pool space used.
This property can also be referred to by its shortened column name,
.Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL .
.It Sy guid
A unique identifier for the pool.
+.It Sy load_guid
+A unique identifier for the pool.
+Unlike the
+.Sy guid
+property, this identifier is generated every time we load the pool (e.g. does
+not persist across imports/exports) and never changes while the pool is loaded
+(even if a
+.Sy reguid
+operation takes place).
.It Sy size
Total size of the storage pool.
.It Sy unsupported@ Ns Em feature_guid
See
.Xr zpool-features 5
for details.
-.It Sy used
-Amount of storage space used within the pool.
.El
.Pp
The space usage properties report actual physical space available to the
See
.Xr genhostid 1
.Xr zgenhostid 8
-.Xr spl-module-paramters 5
+.Xr spl-module-parameters 5
for additional details. The default value is
.Sy off .
.It Sy version Ns = Ns Ar version
Display real paths for
.Ar vdev Ns s
instead of only the last component of the path. This can be used in
-conjunction with the -L flag.
+conjunction with the
+.Fl L
+flag.
.It Fl o Ar property Ns = Ns Ar value
Sets the given pool properties. See the
.Sx Properties
.El
.It Xo
.Nm
+.Cm checkpoint
+.Op Fl d, -discard
+.Ar pool
+.Xc
+Checkpoints the current state of
+.Ar pool
+, which can be later restored by
+.Nm zpool Cm import --rewind-to-checkpoint .
+The existence of a checkpoint in a pool prohibits the following
+.Nm zpool
+commands:
+.Cm remove ,
+.Cm attach ,
+.Cm detach ,
+.Cm split ,
+and
+.Cm reguid .
+In addition, it may break reservation boundaries if the pool lacks free
+space.
+The
+.Nm zpool Cm status
+command indicates the existence of a checkpoint or the progress of discarding a
+checkpoint from a pool.
+The
+.Nm zpool Cm list
+command reports how much space the checkpoint takes from the pool.
+.Bl -tag -width Ds
+.It Fl d, -discard
+Discards an existing checkpoint from
+.Ar pool .
+.El
+.It Xo
+.Nm
.Cm clear
.Ar pool
.Op Ar device
.Sy spare
and
.Sy log
-are reserved, as are names beginning with the pattern
+are reserved, as are names beginning with
+.Sy mirror ,
+.Sy raidz ,
+.Sy spare ,
+and the pattern
.Sy c[0-9] .
The
.Ar vdev
.Nm
.Cm import
.Op Fl D
-.Op Fl d Ar dir
+.Op Fl d Ar dir Ns | Ns device
.Xc
Lists pools available to import.
If the
This
.Ar cachefile
is used instead of searching for devices.
-.It Fl d Ar dir
-Searches for devices or files in
+.It Fl d Ar dir Ns | Ns Ar device
+Uses
+.Ar device
+or searches for devices or files in
.Ar dir .
The
.Fl d
.Fl a
.Op Fl DflmN
.Op Fl F Oo Fl n Oc Oo Fl T Oc Oo Fl X Oc
-.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
+.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
This
.Ar cachefile
is used instead of searching for devices.
-.It Fl d Ar dir
-Searches for devices or files in
+.It Fl d Ar dir Ns | Ns Ar device
+Uses
+.Ar device
+or searches for devices or files in
.Ar dir .
The
.Fl d
.Sy altroot
property to
.Ar root .
+.It Fl -rewind-to-checkpoint
+Rewinds pool to the checkpointed state.
+Once the pool is imported with this flag there is no way to undo the rewind.
+All changes and data that were written after the checkpoint are lost!
+The only exception is when the
+.Sy readonly
+mounting option is enabled.
+In this case, the checkpointed state of the pool is opened and an
+administrator can see how the pool would look like if they were
+to fully rewind.
.It Fl s
Scan using the default search path, the libblkid cache will not be
consulted. A custom search path may be specified by setting the
.Cm import
.Op Fl Dflm
.Op Fl F Oo Fl n Oc Oo Fl t Oc Oo Fl T Oc Oo Fl X Oc
-.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
+.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir Ns | Ns device
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
This
.Ar cachefile
is used instead of searching for devices.
-.It Fl d Ar dir
-Searches for devices or files in
+.It Fl d Ar dir Ns | Ns Ar device
+Uses
+.Ar device
+or searches for devices or files in
.Ar dir .
The
.Fl d
.Fl X
option, above. WARNING: This option can be extremely hazardous to the
health of your pool and should only be used as a last resort.
-.It Fl s
+.It Fl t
Used with
.Sy newpool .
Specifies that
Verbose statistics Reports usage statistics for individual vdevs within the
pool, in addition to the pool-wide statistics.
.It Fl y
+Omit statistics since boot.
+Normally the first line of output reports the statistics since boot.
+This option suppresses that first line of output.
.It Fl w
+Display latency histograms:
+.Pp
+.Ar total_wait :
+Total IO time (queuing + disk IO time).
+.Ar disk_wait :
+Disk IO time (time reading/writing the disk).
+.Ar syncq_wait :
+Amount of time IO spent in synchronous priority queues. Does not include
+disk time.
+.Ar asyncq_wait :
+Amount of time IO spent in asynchronous priority queues. Does not include
+disk time.
+.Ar scrub :
+Amount of time IO spent in scrub queue. Does not include disk time.
.It Fl l
Include average latency statistics:
.Pp
.Sx Properties
section for a list of valid properties.
The default list is
-.Sy name, size, alloc, free, fragmentation, expandsize, capacity,
-.Sy dedupratio, health, altroot .
+.Cm name , size , allocated , free , checkpoint, expandsize , fragmentation ,
+.Cm capacity , dedupratio , health , altroot .
.It Fl L
Display real paths for vdevs resolving all symbolic links. This can
be used to look up the current block device name regardless of the
.It Fl P
Display full paths for vdevs instead of only the last component of
the path. This can be used in conjunction with the
-.Fl L flag.
+.Fl L
+flag.
.It Fl T Sy u Ns | Ns Sy d
Display a time stamp.
Specify
.It Fl n
Do not restart an in-progress scrub operation. This is not recommended and can
result in partially resilvered devices unless a second scrub is performed.
+.El
.It Xo
.Nm
.Cm remove
+.Op Fl np
.Ar pool Ar device Ns ...
.Xc
Removes the specified device from the pool.
-This command currently only supports removing hot spares, cache, and log
-devices.
-A mirrored log device can be removed by specifying the top-level mirror for the
-log.
-Non-log devices that are part of a mirrored configuration can be removed using
+This command currently only supports removing hot spares, cache, log
+devices and mirrored top-level vdevs (mirror of leaf devices); but not raidz.
+.sp
+Removing a top-level vdev reduces the total amount of space in the storage pool.
+The specified device will be evacuated by copying all allocated space from it to
+the other devices in the pool.
+In this case, the
+.Nm zpool Cm remove
+command initiates the removal and returns, while the evacuation continues in
+the background.
+The removal progress can be monitored with
+.Nm zpool Cm status.
+This feature must be enabled to be used, see
+.Xr zpool-features 5
+.Pp
+A mirrored top-level device (log or data) can be removed by specifying the top-level mirror for the
+same.
+Non-log devices or data devices that are part of a mirrored configuration can be removed using
the
.Nm zpool Cm detach
command.
-Non-redundant and raidz devices cannot be removed from a pool.
+.Bl -tag -width Ds
+.It Fl n
+Do not actually perform the removal ("no-op").
+Instead, print the estimated amount of memory that will be used by the
+mapping table after the removal completes.
+This is nonzero only for top-level vdevs.
+.El
+.Bl -tag -width Ds
+.It Fl p
+Used in conjunction with the
+.Fl n
+flag, displays numbers as parsable (exact) values.
+.El
+.It Xo
+.Nm
+.Cm remove
+.Fl s
+.Ar pool
+.Xc
+Stops and cancels an in-progress removal of a top-level vdev.
.It Xo
.Nm
.Cm replace
.It Fl P
Display full paths for vdevs instead of only the last component of
the path. This can be used in conjunction with the
-.Fl L flag.
+.Fl L
+flag.
.It Fl o Ar property Ns = Ns Ar value
Sets the specified property for
.Ar newpool .
be used to look up the current block device name regardless of the
.Pa /dev/disk/
path used to open it.
-.It Fl p
-Display numbers in parsable (exact) values. Time values are in
-nanoseconds.
+.It Fl P
+Display full paths for vdevs instead of only the last component of
+the path. This can be used in conjunction with the
+.Fl L
+flag.
.It Fl D
Display a histogram of deduplication statistics, showing the allocated
.Pq physically present on disk
The results from this command are similar to the following:
.Bd -literal
# zpool list
-NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
-rpool 19.9G 8.43G 11.4G 33% - 42% 1.00x ONLINE -
-tank 61.5G 20.0G 41.5G 48% - 32% 1.00x ONLINE -
-zion - - - - - - - FAULTED -
+NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
+rpool 19.9G 8.43G 11.4G - 33% 42% 1.00x ONLINE -
+tank 61.5G 20.0G 41.5G - 48% 32% 1.00x ONLINE -
+zion - - - - - - - FAULTED -
.Ed
.It Sy Example 7 No Destroying a ZFS Storage Pool
The following command destroys the pool
.Bd -literal
# zpool iostat -v pool 5
.Ed
-.It Sy Example 14 No Removing a Mirrored Log Device
-The following command removes the mirrored log device
-.Sy mirror-2 .
+.It Sy Example 14 No Removing a Mirrored top-level (Log or Data) Device
+The following commands remove the mirrored log device
+.Sy mirror-2
+and mirrored top-level data device
+.Sy mirror-1 .
+.Pp
Given this configuration:
.Bd -literal
pool: tank
.Bd -literal
# zpool remove tank mirror-2
.Ed
+.Pp
+The command to remove the mirrored data
+.Sy mirror-1
+is:
+.Bd -literal
+# zpool remove tank mirror-1
+.Ed
.It Sy Example 15 No Displaying expanded space on a device
The following command displays the detailed information for the pool
.Em data .
all the devices under the raidz vdev have been expanded.
.Bd -literal
# zpool list -v data
-NAME SIZE ALLOC FREE FRAG EXPANDSZ CAP DEDUP HEALTH ALTROOT
-data 23.9G 14.6G 9.30G 48% - 61% 1.00x ONLINE -
- raidz1 23.9G 14.6G 9.30G 48% -
- sda - - - - -
- sdb - - - - 10G
- sdc - - - - -
+NAME SIZE ALLOC FREE EXPANDSZ FRAG CAP DEDUP HEALTH ALTROOT
+data 23.9G 14.6G 9.30G - 48% 61% 1.00x ONLINE -
+ raidz1 23.9G 14.6G 9.30G - 48%
+ sda - - - - -
+ sdb - - - 10G -
+ sdc - - - - -
.Ed
.It Sy Example 16 No Adding output columns
Additional columns can be added to the
projects / mirror_zfs.git / blobdiff