c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2026-05-25 11:47:43 +03:00
Code Issues Packages Projects Releases Wiki Activity

Move properties, parameters, events, and concepts around manual sections

Browse Source 
The pages moved as follows:
  zpool-features.{5 => 7}
  spl{-module-parameters.5 => .4}
  zfs{-module-parameters.5 => .4}
  zfs-events.5 => into zpool-events.8
  zfsconcepts.{8 => 7}
  zfsprops.{8 => 7}
  zpoolconcepts.{8 => 7}
  zpoolprops.{8 => 7}

Reviewed-by: Richard Laager <rlaager@wiktel.com>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Co-authored-by: Daniel Ebdrup Jensen <debdrup@FreeBSD.org>
Closes #12149
Closes #12212
This commit is contained in:
наб
2021-06-04 22:29:26 +02:00
committed by Brian Behlendorf
parent 0bef46e6d5
commit a444efb6d7
50 changed files with 543 additions and 582 deletions
Download Patch File Download Diff File Expand all files Collapse all files
man/man8/mount.zfs.8
+1 -1
View File
@@ -56,7 +56,7 @@ in most cases.
are handled according to the
.Em Temporary Mount Point Properties
section in
.Xr zfsprops 8 ,
.Xr zfsprops 7 ,
except for those described below.
.Pp
If
man/man8/zed.8.in
-1
View File
@@ -237,7 +237,6 @@ Terminate the daemon.
.El
.
.Sh SEE ALSO
.Xr zfs-events 5 ,
.Xr zfs 8 ,
.Xr zpool 8 ,
.Xr zpool-events 8
man/man8/zfs-bookmark.8
+1 -1
View File
@@ -56,7 +56,7 @@ a redaction bookmark.
.Pp
This feature must be enabled to be used.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags and the
.Sy bookmarks
feature.
man/man8/zfs-clone.8
+1 -1
View File
@@ -47,7 +47,7 @@
See the
.Sx Clones
section of
.Xr zfsconcepts 8
.Xr zfsconcepts 7
for details.
The target dataset can be located anywhere in the ZFS hierarchy,
and is created as the same type as the original.
man/man8/zfs-create.8
+1 -1
View File
@@ -184,7 +184,7 @@ See
in the
.Em Native Properties
section of
.Xr zfsprops 8
.Xr zfsprops 7
for more information about sparse volumes.
.It Fl n
Do a dry-run
man/man8/zfs-jail.8
+2 -2
View File
@@ -119,5 +119,5 @@ or name
.Ar jailname .
.El
.Sh SEE ALSO
.Xr jail 8 ,
.Xr zfsprops 8
.Xr zfsprops 7 ,
.Xr jail 8
man/man8/zfs-list.8
+4 -4
View File
@@ -90,7 +90,7 @@ The property must be:
One of the properties described in the
.Sx Native Properties
section of
.Xr zfsprops 8
.Xr zfsprops 7
.It
A user property
.It
@@ -118,7 +118,7 @@ value of the property.
The property must be one of the properties described in the
.Sx Properties
section of
.Xr zfsprops 8
.Xr zfsprops 7
or the value
.Sy name
to sort by the dataset name.
@@ -158,5 +158,5 @@ displays only snapshots.
.El
.
.Sh SEE ALSO
.Xr zfs-get 8 ,
.Xr zfsprops 8
.Xr zfsprops 7 ,
.Xr zfs-get 8
man/man8/zfs-load-key.8
+2 -2
View File
@@ -296,6 +296,6 @@ Deduplication with encryption will leak information about which blocks
are equivalent in a dataset and will incur an extra CPU cost for each block written.
.
.Sh SEE ALSO
.Xr zfsprops 7 ,
.Xr zfs-create 8 ,
.Xr zfs-set 8 ,
.Xr zfsprops 8
.Xr zfs-set 8
man/man8/zfs-mount-generator.8.in
+2 -2
View File
@@ -186,7 +186,7 @@ to re-run all generators:
.Xr systemd.mount 5 ,
.Xr systemd.target 5 ,
.Xr zfs 5 ,
.Xr zfs-events 5 ,
.Xr systemd.generator 7 ,
.Xr systemd.special 7 ,
.Xr zed 8
.Xr zed 8 ,
.Xr zpool-events 8
man/man8/zfs-mount.8
+1 -1
View File
@@ -91,7 +91,7 @@ duration of the mount.
See the
.Em Temporary Mount Point Properties
section of
.Xr zfsprops 8
.Xr zfsprops 7
for details.
.It Fl l
Load keys for encrypted filesystems as they are being mounted.
man/man8/zfs-receive.8
+1 -1
View File
@@ -357,7 +357,7 @@ To use this flag, the storage pool must have the
.Sy extensible_dataset
feature enabled.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags.
.It Fl u
File system that is associated with the received stream is not mounted.
man/man8/zfs-send.8
+4 -4
View File
@@ -110,7 +110,7 @@ The receiving system must have the
.Sy large_blocks
pool feature enabled as well.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags and the
.Sy large_blocks
feature.
@@ -161,7 +161,7 @@ received as an encrypted dataset, since encrypted datasets cannot use the
.Sy embedded_data
feature.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags and the
.Sy embedded_data
feature.
@@ -308,7 +308,7 @@ The receiving system must have the
.Sy large_blocks
pool feature enabled as well.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags and the
.Sy large_blocks
feature.
@@ -372,7 +372,7 @@ since encrypted datasets cannot use the
.Sy embedded_data
feature.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on ZFS feature flags and the
.Sy embedded_data
feature.
man/man8/zfs-set.8
+6 -6
View File
@@ -65,7 +65,7 @@
.Xc
Only some properties can be edited.
See
.Xr zfsprops 8
.Xr zfsprops 7
for more information on what properties can be set and acceptable
values.
Numeric values can be specified as exact values, or in a human-readable form
@@ -78,7 +78,7 @@ User properties can be set on snapshots.
For more information, see the
.Em User Properties
section of
.Xr zfsprops 8 .
.Xr zfsprops 7 .
.It Xo
.Nm zfs
.Cm get
@@ -114,7 +114,7 @@ This command takes a comma-separated list of properties as described in the
and
.Sx User Properties
sections of
.Xr zfsprops 8 .
.Xr zfsprops 7 .
.Pp
The value
.Sy all
@@ -163,7 +163,7 @@ restored to default if no ancestor has the property set, or with the
.Fl S
option reverted to the received value if one exists.
See
.Xr zfsprops 8
.Xr zfsprops 7
for a listing of default values, and details on which properties can be
inherited.
.Bl -tag -width "-r"
@@ -178,5 +178,5 @@ option was not specified.
.El
.
.Sh SEE ALSO
.Xr zfs-list 8 ,
.Xr zfsprops 8
.Xr zfsprops 7 ,
.Xr zfs-list 8
man/man8/zfs-share.8
+1 -1
View File
@@ -87,4 +87,4 @@ The command can also be given a path to a ZFS file system shared on the system.
.Sh SEE ALSO
.Xr exports 5 ,
.Xr smb.conf 5 ,
.Xr zfsprops 8
.Xr zfsprops 7
man/man8/zfs-snapshot.8
+1 -1
View File
@@ -54,7 +54,7 @@ can be used as an alias for
See the
.Sx Snapshots
section of
.Xr zfsconcepts 8
.Xr zfsconcepts 7
for details.
.Bl -tag -width "-o"
.It Fl o Ar property Ns = Ns Ar value
man/man8/zfs-upgrade.8
+1 -1
View File
@@ -77,7 +77,7 @@ systems running older versions of ZFS.
.Pp
In general, the file system version is independent of the pool version.
See
.Xr zpool-features 5
.Xr zpool-features 7
for information on features of ZFS storage pools.
.Pp
In some cases, the file system version and the pool version are interrelated and
man/man8/zfs-userspace.8
+2 -2
View File
@@ -183,5 +183,5 @@ for types.
.El
.
.Sh SEE ALSO
.Xr zfs-set 8 ,
.Xr zfsprops 8
.Xr zfsprops 7 ,
.Xr zfs-set 8
man/man8/zfs.8
+5 -5
View File
@@ -96,7 +96,7 @@ or
.El
.Pp
See
.Xr zfsconcepts 8
.Xr zfsconcepts 7
for details.
.
.Ss Properties
@@ -108,7 +108,7 @@ In addition, native properties are either editable or read-only.
User properties have no effect on ZFS behavior, but you can use them to annotate
datasets in a way that is meaningful in your environment.
For more information about properties, see
.Xr zfsprops 8 .
.Xr zfsprops 7 .
.
.Ss Encryption
Enabling the
@@ -354,7 +354,7 @@ Snapshots are displayed if
The default is
.Sy off .
See
.Xr zpoolprops 8
.Xr zpoolprops 7
for more information on pool properties.
.Bd -literal -compact -offset Ds
.No # Nm zfs Cm list
@@ -728,6 +728,8 @@ This option is provided for backwards compatibility with older ZFS versions.
.Xr acl 5 ,
.Xr attributes 5 ,
.Xr exports 5 ,
.Xr zfsconcepts 7 ,
.Xr zfsprops 7 ,
.Xr exportfs 8 ,
.Xr mount 8 ,
.Xr net 8 ,
@@ -768,6 +770,4 @@ This option is provided for backwards compatibility with older ZFS versions.
.Xr zfs-upgrade 8 ,
.Xr zfs-userspace 8 ,
.Xr zfs-wait 8 ,
.Xr zfsconcepts 8 ,
.Xr zfsprops 8 ,
.Xr zpool 8
man/man8/zfsconcepts.8
-206
View File
@@ -1,206 +0,0 @@
.\"
.\" CDDL HEADER START
.\"
.\" 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]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
.\" Copyright (c) 2014 Integros [integros.com]
.\" Copyright 2019 Richard Laager. All rights reserved.
.\" Copyright 2018 Nexenta Systems, Inc.
.\" Copyright 2019 Joyent, Inc.
.\"
.Dd June 30, 2019
.Dt ZFSCONCEPTS 8
.Os
.
.Sh NAME
.Nm zfsconcepts
.Nd overview of ZFS concepts
.
.Sh DESCRIPTION
.Ss ZFS File System Hierarchy
A ZFS storage pool is a logical collection of devices that provide space for
datasets.
A storage pool is also the root of the ZFS file system hierarchy.
.Pp
The root of the pool can be accessed as a file system, such as mounting and
unmounting, taking snapshots, and setting properties.
The physical storage characteristics, however, are managed by the
.Xr zpool 8
command.
.Pp
See
.Xr zpool 8
for more information on creating and administering pools.
.Ss Snapshots
A snapshot is a read-only copy of a file system or volume.
Snapshots can be created extremely quickly, and initially consume no additional
space within the pool.
As data within the active dataset changes, the snapshot consumes more data than
would otherwise be shared with the active dataset.
.Pp
Snapshots can have arbitrary names.
Snapshots of volumes can be cloned or rolled back, visibility is determined
by the
.Sy snapdev
property of the parent volume.
.Pp
File system snapshots can be accessed under the
.Pa .zfs/snapshot
directory in the root of the file system.
Snapshots are automatically mounted on demand and may be unmounted at regular
intervals.
The visibility of the
.Pa .zfs
directory can be controlled by the
.Sy snapdir
property.
.Ss Bookmarks
A bookmark is like a snapshot, a read-only copy of a file system or volume.
Bookmarks can be created extremely quickly, compared to snapshots, and they
consume no additional space within the pool.
Bookmarks can also have arbitrary names, much like snapshots.
.Pp
Unlike snapshots, bookmarks can not be accessed through the filesystem in any way.
From a storage standpoint a bookmark just provides a way to reference
when a snapshot was created as a distinct object.
Bookmarks are initially tied to a snapshot, not the filesystem or volume,
and they will survive if the snapshot itself is destroyed.
Since they are very light weight there's little incentive to destroy them.
.Ss Clones
A clone is a writable volume or file system whose initial contents are the same
as another dataset.
As with snapshots, creating a clone is nearly instantaneous, and initially
consumes no additional space.
.Pp
Clones can only be created from a snapshot.
When a snapshot is cloned, it creates an implicit dependency between the parent
and child.
Even though the clone is created somewhere else in the dataset hierarchy, the
original snapshot cannot be destroyed as long as a clone exists.
The
.Sy origin
property exposes this dependency, and the
.Cm destroy
command lists any such dependencies, if they exist.
.Pp
The clone parent-child dependency relationship can be reversed by using the
.Cm promote
subcommand.
This causes the
.Qq origin
file system to become a clone of the specified file system, which makes it
possible to destroy the file system that the clone was created from.
.Ss "Mount Points"
Creating a ZFS file system is a simple operation, so the number of file systems
per system is likely to be numerous.
To cope with this, ZFS automatically manages mounting and unmounting file
systems without the need to edit the
.Pa /etc/fstab
file.
All automatically managed file systems are mounted by ZFS at boot time.
.Pp
By default, file systems are mounted under
.Pa /path ,
where
.Ar path
is the name of the file system in the ZFS namespace.
Directories are created and destroyed as needed.
.Pp
A file system can also have a mount point set in the
.Sy mountpoint
property.
This directory is created as needed, and ZFS automatically mounts the file
system when the
.Nm zfs Cm mount Fl a
command is invoked
.Po without editing
.Pa /etc/fstab
.Pc .
The
.Sy mountpoint
property can be inherited, so if
.Em pool/home
has a mount point of
.Pa /export/stuff ,
then
.Em pool/home/user
automatically inherits a mount point of
.Pa /export/stuff/user .
.Pp
A file system
.Sy mountpoint
property of
.Sy none
prevents the file system from being mounted.
.Pp
If needed, ZFS file systems can also be managed with traditional tools
.Po
.Nm mount ,
.Nm umount ,
.Pa /etc/fstab
.Pc .
If a file system's mount point is set to
.Sy legacy ,
ZFS makes no attempt to manage the file system, and the administrator is
responsible for mounting and unmounting the file system.
Because pools must
be imported before a legacy mount can succeed, administrators should ensure
that legacy mounts are only attempted after the zpool import process
finishes at boot time.
For example, on machines using systemd, the mount option
.Pp
.Nm x-systemd.requires=zfs-import.target
.Pp
will ensure that the zfs-import completes before systemd attempts mounting
the filesystem.
See
.Xr systemd.mount 5
for details.
.Ss Deduplication
Deduplication is the process for removing redundant data at the block level,
reducing the total amount of data stored.
If a file system has the
.Sy dedup
property enabled, duplicate data blocks are removed synchronously.
The result
is that only unique data is stored and common components are shared among files.
.Pp
Deduplicating data is a very resource-intensive operation.
It is generally recommended that you have at least 1.25 GiB of RAM
per 1 TiB of storage when you enable deduplication.
Calculating the exact requirement depends heavily
on the type of data stored in the pool.
.Pp
Enabling deduplication on an improperly-designed system can result in
performance issues (slow IO and administrative operations).
It can potentially lead to problems importing a pool due to memory exhaustion.
Deduplication can consume significant processing power (CPU) and memory as well
as generate additional disk IO.
.Pp
Before creating a pool with deduplication enabled, ensure that you have planned
your hardware requirements appropriately and implemented appropriate recovery
practices, such as regular backups.
Consider using the
.Sy compression
property as a less resource-intensive alternative.
man/man8/zfsprops.8
-2045
View File
File diff suppressed because it is too large Load Diff
man/man8/zgenhostid.8
+1 -1
View File
@@ -83,7 +83,7 @@ digits long, optionally prefixed by
.Xr genhostid 1 ,
.Xr hostid 1 ,
.Xr sethostid 3 ,
.Xr spl-module-parameters 5
.Xr spl 4
.Sh HISTORY
.Nm
emulates the
man/man8/zpool-add.8
+2 -2
View File
@@ -46,7 +46,7 @@ The
specification is described in the
.Em Virtual Devices
section of
.Xr zpoolconcepts 8 .
.Xr zpoolconcepts 7 .
The behavior of the
.Fl f
option, and the device checks performed are described in the
@@ -87,7 +87,7 @@ flag.
.It Fl o Ar property Ns = Ns Ar value
Sets the given pool properties.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for a list of valid properties that can be set.
The only property supported at the moment is
.Sy ashift .
man/man8/zpool-attach.8
+1 -1
View File
@@ -71,7 +71,7 @@ Not all devices can be overridden in this manner.
.It Fl o Ar property Ns = Ns Ar value
Sets the given pool properties.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for a list of valid properties that can be set.
The only property supported at the moment is
.Sy ashift .
man/man8/zpool-create.8
+7 -7
View File
@@ -80,7 +80,7 @@ The
specification is described in the
.Sx Virtual Devices
section of
.Xr zpoolconcepts 8 .
.Xr zpoolconcepts 7 .
.Pp
The command attempts to verify that each device specified is accessible and not
currently in use by another subsystem.
@@ -139,7 +139,7 @@ Individual features can be enabled by setting their corresponding properties to
with
.Fl o .
See
.Xr zpool-features 5
.Xr zpool-features 7
for details about feature properties.
.It Fl f
Forces use of
@@ -160,7 +160,7 @@ The mount point must be an absolute path,
or
.Sy none .
For more information on dataset mount points, see
.Xr zfsprops 8 .
.Xr zfsprops 7 .
.It Fl n
Displays the configuration that would be used without actually creating the
pool.
@@ -169,23 +169,23 @@ device sharing.
.It Fl o Ar property Ns = Ns Ar value
Sets the given pool properties.
See
.Xr zpoolprops 8
.Xr zpoolprops 7
for a list of valid properties that can be set.
.It Fl o Ar compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
Specifies compatibility feature sets.
See
.Xr zpool-features 5
.Xr zpool-features 7
for more information about compatibility feature sets.
.It Fl o Sy feature@ Ns Ar feature Ns = Ns Ar value
Sets the given pool feature.
See the
.Xr zpool-features 5
.Xr zpool-features 7
section for a list of valid features that can be set.
Value can be either disabled or enabled.
.It Fl O Ar file-system-property Ns = Ns Ar value
Sets the given file system properties in the root file system of the pool.
See
.Xr zfsprops 8
.Xr zfsprops 7
for a list of valid properties that can be set.
.It Fl R Ar root
Equivalent to
man/man8/zpool-events.8
+416 -6
View File
@@ -49,10 +49,11 @@ These events are consumed by the
and used to automate administrative tasks such as replacing a failed device
with a hot spare.
For more information about the subclasses and event payloads
that can be generated see the
.Xr zfs-events 5
man page.
.Pp
that can be generated see
.Sx EVENTS
and the following sections.
.
.Sh OPTIONS
.Bl -tag -compact -width Ds
.It Fl c
Clear all previous events.
@@ -66,8 +67,417 @@ single tab instead of arbitrary space.
Print the entire payload for each event.
.El
.
.Sh EVENTS
Theese are the different event subclasses.
The full event name would be
.Sy ereport.fs.zfs.\& Ns Em SUBCLASS ,
but only the last part is listed here.
.Pp
.Bl -tag -compact -width "vdev.bad_guid_sum"
.It Sy checksum
Issued when a checksum error has been detected.
.It Sy io
Issued when there is an I/O error in a vdev in the pool.
.It Sy data
Issued when there have been data errors in the pool.
.It Sy deadman
Issued when an I/O request is determined to be "hung", this can be caused
by lost completion events due to flaky hardware or drivers.
See
.Sy zfs_deadman_failmode
in
.Xr zfs 4
for additional information regarding "hung" I/O detection and configuration.
.It Sy delay
Issued when a completed I/O request exceeds the maximum allowed time
specified by the
.Sy zio_slow_io_ms
module parameter.
This can be an indicator of problems with the underlying storage device.
The number of delay events is ratelimited by the
.Sy zfs_slow_io_events_per_second
module parameter.
.It Sy config
Issued every time a vdev change have been done to the pool.
.It Sy zpool
Issued when a pool cannot be imported.
.It Sy zpool.destroy
Issued when a pool is destroyed.
.It Sy zpool.export
Issued when a pool is exported.
.It Sy zpool.import
Issued when a pool is imported.
.It Sy zpool.reguid
Issued when a REGUID (new unique identifier for the pool have been regenerated) have been detected.
.It Sy vdev.unknown
Issued when the vdev is unknown.
Such as trying to clear device errors on a vdev that have failed/been kicked
from the system/pool and is no longer available.
.It Sy vdev.open_failed
Issued when a vdev could not be opened (because it didn't exist for example).
.It Sy vdev.corrupt_data
Issued when corrupt data have been detected on a vdev.
.It Sy vdev.no_replicas
Issued when there are no more replicas to sustain the pool.
This would lead to the pool being
.Em DEGRADED .
.It Sy vdev.bad_guid_sum
Issued when a missing device in the pool have been detected.
.It Sy vdev.too_small
Issued when the system (kernel) have removed a device, and ZFS
notices that the device isn't there any more.
This is usually followed by a
.Sy probe_failure
event.
.It Sy vdev.bad_label
Issued when the label is OK but invalid.
.It Sy vdev.bad_ashift
Issued when the ashift alignment requirement has increased.
.It Sy vdev.remove
Issued when a vdev is detached from a mirror (or a spare detached from a
vdev where it have been used to replace a failed drive - only works if
the original drive have been readded).
.It Sy vdev.clear
Issued when clearing device errors in a pool.
Such as running
.Nm zpool Cm clear
on a device in the pool.
.It Sy vdev.check
Issued when a check to see if a given vdev could be opened is started.
.It Sy vdev.spare
Issued when a spare have kicked in to replace a failed device.
.It Sy vdev.autoexpand
Issued when a vdev can be automatically expanded.
.It Sy io_failure
Issued when there is an I/O failure in a vdev in the pool.
.It Sy probe_failure
Issued when a probe fails on a vdev.
This would occur if a vdev
have been kicked from the system outside of ZFS (such as the kernel
have removed the device).
.It Sy log_replay
Issued when the intent log cannot be replayed.
The can occur in the case of a missing or damaged log device.
.It Sy resilver.start
Issued when a resilver is started.
.It Sy resilver.finish
Issued when the running resilver have finished.
.It Sy scrub.start
Issued when a scrub is started on a pool.
.It Sy scrub.finish
Issued when a pool has finished scrubbing.
.It Sy scrub.abort
Issued when a scrub is aborted on a pool.
.It Sy scrub.resume
Issued when a scrub is resumed on a pool.
.It Sy scrub.paused
Issued when a scrub is paused on a pool.
.It Sy bootfs.vdev.attach
.El
.
.Sh PAYLOADS
This is the payload (data, information) that accompanies an
event.
.Pp
For
.Xr zed 8 ,
these are set to uppercase and prefixed with
.Sy ZEVENT_ .
.Pp
.Bl -tag -compact -width "vdev_cksum_errors"
.It Sy pool
Pool name.
.It Sy pool_failmode
Failmode -
.Sy wait ,
.Sy continue ,
or
.Sy panic .
See the
.Sy failmode
property in
.Xr zpoolprops 7
for more information.
.It Sy pool_guid
The GUID of the pool.
.It Sy pool_context
The load state for the pool (0=none, 1=open, 2=import, 3=tryimport, 4=recover
5=error).
.It Sy vdev_guid
The GUID of the vdev in question (the vdev failing or operated upon with
.Nm zpool Cm clear ,
etc.).
.It Sy vdev_type
Type of vdev -
.Sy disk ,
.Sy file ,
.Sy mirror ,
etc.
See the
.Sy Virtual Devices
section of
.Xr zpoolconcepts 7
for more information on possible values.
.It Sy vdev_path
Full path of the vdev, including any
.Em -partX .
.It Sy vdev_devid
ID of vdev (if any).
.It Sy vdev_fru
Physical FRU location.
.It Sy vdev_state
State of vdev (0=uninitialized, 1=closed, 2=offline, 3=removed, 4=failed to open, 5=faulted, 6=degraded, 7=healthy).
.It Sy vdev_ashift
The ashift value of the vdev.
.It Sy vdev_complete_ts
The time the last I/O request completed for the specified vdev.
.It Sy vdev_delta_ts
The time since the last I/O request completed for the specified vdev.
.It Sy vdev_spare_paths
List of spares, including full path and any
.Em -partX .
.It Sy vdev_spare_guids
GUID(s) of spares.
.It Sy vdev_read_errors
How many read errors that have been detected on the vdev.
.It Sy vdev_write_errors
How many write errors that have been detected on the vdev.
.It Sy vdev_cksum_errors
How many checksum errors that have been detected on the vdev.
.It Sy parent_guid
GUID of the vdev parent.
.It Sy parent_type
Type of parent.
See
.Sy vdev_type .
.It Sy parent_path
Path of the vdev parent (if any).
.It Sy parent_devid
ID of the vdev parent (if any).
.It Sy zio_objset
The object set number for a given I/O request.
.It Sy zio_object
The object number for a given I/O request.
.It Sy zio_level
The indirect level for the block.
Level 0 is the lowest level and includes data blocks.
Values > 0 indicate metadata blocks at the appropriate level.
.It Sy zio_blkid
The block ID for a given I/O request.
.It Sy zio_err
The error number for a failure when handling a given I/O request,
compatible with
.Xr errno 3
with the value of
.Sy EBADE
used to indicate a ZFS checksum error.
.It Sy zio_offset
The offset in bytes of where to write the I/O request for the specified vdev.
.It Sy zio_size
The size in bytes of the I/O request.
.It Sy zio_flags
The current flags describing how the I/O request should be handled.
See the
.Sy I/O FLAGS
section for the full list of I/O flags.
.It Sy zio_stage
The current stage of the I/O in the pipeline.
See the
.Sy I/O STAGES
section for a full list of all the I/O stages.
.It Sy zio_pipeline
The valid pipeline stages for the I/O.
See the
.Sy I/O STAGES
section for a full list of all the I/O stages.
.It Sy zio_delay
The time elapsed (in nanoseconds) waiting for the block layer to complete the
I/O request.
Unlike
.Sy zio_delta ,
this does not include any vdev queuing time and is
therefore solely a measure of the block layer performance.
.It Sy zio_timestamp
The time when a given I/O request was submitted.
.It Sy zio_delta
The time required to service a given I/O request.
.It Sy prev_state
The previous state of the vdev.
.It Sy cksum_expected
The expected checksum value for the block.
.It Sy cksum_actual
The actual checksum value for an errant block.
.It Sy cksum_algorithm
Checksum algorithm used.
See
.Xr zfsprops 7
for more information on the available checksum algorithms.
.It Sy cksum_byteswap
Whether or not the data is byteswapped.
.It Sy bad_ranges
.No [\& Ns Ar start , end )
pairs of corruption offsets.
Offsets are always aligned on a 64-bit boundary,
and can include some gaps of non-corruption.
(See
.Sy bad_ranges_min_gap )
.It Sy bad_ranges_min_gap
In order to bound the size of the
.Sy bad_ranges
array, gaps of non-corruption
less than or equal to
.Sy bad_ranges_min_gap
bytes have been merged with
adjacent corruption.
Always at least 8 bytes, since corruption is detected on a 64-bit word basis.
.It Sy bad_range_sets
This array has one element per range in
.Sy bad_ranges .
Each element contains
the count of bits in that range which were clear in the good data and set
in the bad data.
.It Sy bad_range_clears
This array has one element per range in
.Sy bad_ranges .
Each element contains
the count of bits for that range which were set in the good data and clear in
the bad data.
.It Sy bad_set_bits
If this field exists, it is an array of
.Pq Ar bad data No & ~( Ns Ar good data ) ;
that is, the bits set in the bad data which are cleared in the good data.
Each element corresponds a byte whose offset is in a range in
.Sy bad_ranges ,
and the array is ordered by offset.
Thus, the first element is the first byte in the first
.Sy bad_ranges
range, and the last element is the last byte in the last
.Sy bad_ranges
range.
.It Sy bad_cleared_bits
Like
.Sy bad_set_bits ,
but contains
.Pq Ar good data No & ~( Ns Ar bad data ) ;
that is, the bits set in the good data which are cleared in the bad data.
.It Sy bad_set_histogram
If this field exists, it is an array of counters.
Each entry counts bits set in a particular bit of a big-endian uint64 type.
The first entry counts bits
set in the high-order bit of the first byte, the 9th byte, etc, and the last
entry counts bits set of the low-order bit of the 8th byte, the 16th byte, etc.
This information is useful for observing a stuck bit in a parallel data path,
such as IDE or parallel SCSI.
.It Sy bad_cleared_histogram
If this field exists, it is an array of counters.
Each entry counts bit clears in a particular bit of a big-endian uint64 type.
The first entry counts bits
clears of the high-order bit of the first byte, the 9th byte, etc, and the
last entry counts clears of the low-order bit of the 8th byte, the 16th byte, etc.
This information is useful for observing a stuck bit in a parallel data
path, such as IDE or parallel SCSI.
.El
.
.Sh I/O STAGES
The ZFS I/O pipeline is comprised of various stages which are defined below.
The individual stages are used to construct these basic I/O
operations: Read, Write, Free, Claim, and Ioctl.
These stages may be
set on an event to describe the life cycle of a given I/O request.
.Pp
.TS
tab(:);
l l l .
Stage:Bit Mask:Operations
_:_:_
ZIO_STAGE_OPEN:0x00000001:RWFCI
ZIO_STAGE_READ_BP_INIT:0x00000002:R----
ZIO_STAGE_WRITE_BP_INIT:0x00000004:-W---
ZIO_STAGE_FREE_BP_INIT:0x00000008:--F--
ZIO_STAGE_ISSUE_ASYNC:0x00000010:RWF--
ZIO_STAGE_WRITE_COMPRESS:0x00000020:-W---
ZIO_STAGE_ENCRYPT:0x00000040:-W---
ZIO_STAGE_CHECKSUM_GENERATE:0x00000080:-W---
ZIO_STAGE_NOP_WRITE:0x00000100:-W---
ZIO_STAGE_DDT_READ_START:0x00000200:R----
ZIO_STAGE_DDT_READ_DONE:0x00000400:R----
ZIO_STAGE_DDT_WRITE:0x00000800:-W---
ZIO_STAGE_DDT_FREE:0x00001000:--F--
ZIO_STAGE_GANG_ASSEMBLE:0x00002000:RWFC-
ZIO_STAGE_GANG_ISSUE:0x00004000:RWFC-
ZIO_STAGE_DVA_THROTTLE:0x00008000:-W---
ZIO_STAGE_DVA_ALLOCATE:0x00010000:-W---
ZIO_STAGE_DVA_FREE:0x00020000:--F--
ZIO_STAGE_DVA_CLAIM:0x00040000:---C-
ZIO_STAGE_READY:0x00080000:RWFCI
ZIO_STAGE_VDEV_IO_START:0x00100000:RW--I
ZIO_STAGE_VDEV_IO_DONE:0x00200000:RW--I
ZIO_STAGE_VDEV_IO_ASSESS:0x00400000:RW--I
ZIO_STAGE_CHECKSUM_VERIFY:0x00800000:R----
ZIO_STAGE_DONE:0x01000000:RWFCI
.TE
.
.Sh I/O FLAGS
Every I/O request in the pipeline contains a set of flags which describe its
function and are used to govern its behavior.
These flags will be set in an event as a
.Sy zio_flags
payload entry.
.Pp
.TS
tab(:);
l l .
Flag:Bit Mask
_:_
ZIO_FLAG_DONT_AGGREGATE:0x00000001
ZIO_FLAG_IO_REPAIR:0x00000002
ZIO_FLAG_SELF_HEAL:0x00000004
ZIO_FLAG_RESILVER:0x00000008
ZIO_FLAG_SCRUB:0x00000010
ZIO_FLAG_SCAN_THREAD:0x00000020
ZIO_FLAG_PHYSICAL:0x00000040
ZIO_FLAG_CANFAIL:0x00000080
ZIO_FLAG_SPECULATIVE:0x00000100
ZIO_FLAG_CONFIG_WRITER:0x00000200
ZIO_FLAG_DONT_RETRY:0x00000400
ZIO_FLAG_DONT_CACHE:0x00000800
ZIO_FLAG_NODATA:0x00001000
ZIO_FLAG_INDUCE_DAMAGE:0x00002000
ZIO_FLAG_IO_ALLOCATING:0x00004000
ZIO_FLAG_IO_RETRY:0x00008000
ZIO_FLAG_PROBE:0x00010000
ZIO_FLAG_TRYHARD:0x00020000
ZIO_FLAG_OPTIONAL:0x00040000
ZIO_FLAG_DONT_QUEUE:0x00080000
ZIO_FLAG_DONT_PROPAGATE:0x00100000
ZIO_FLAG_IO_BYPASS:0x00200000
ZIO_FLAG_IO_REWRITE:0x00400000
ZIO_FLAG_RAW_COMPRESS:0x00800000
ZIO_FLAG_RAW_ENCRYPT:0x01000000
ZIO_FLAG_GANG_CHILD:0x02000000
ZIO_FLAG_DDT_CHILD:0x04000000
ZIO_FLAG_GODFATHER:0x08000000
ZIO_FLAG_NOPWRITE:0x10000000
ZIO_FLAG_REEXECUTED:0x20000000
ZIO_FLAG_DELEGATED:0x40000000
ZIO_FLAG_FASTWRITE:0x80000000
.TE
.
.Sh SEE ALSO
.Xr zfs-events 5 ,
.Xr zfs-module-parameters 5 ,
.Xr zfs 4 ,
.Xr zed 8 ,
.Xr zpool-wait 8
man/man8/zpool-get.8
+5 -5
View File
@@ -76,7 +76,7 @@ Property source, either
.El
.Pp
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for more information on the available pool properties.
.Bl -tag -compact -offset Ds -width "-o field"
.It Fl H
@@ -97,12 +97,12 @@ Display numbers in parsable (exact) values.
.Xc
Sets the given property on the specified pool.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for more information on what properties can be set and acceptable
values.
.El
.
.Sh SEE ALSO
.Xr zpool-features 5 ,
.Xr zpool-list 8 ,
.Xr zpoolprops 8
.Xr zpool-features 7 ,
.Xr zpoolprops 7 ,
.Xr zpool-list 8
man/man8/zpool-import.8
+2 -2
View File
@@ -201,7 +201,7 @@ for a description of dataset properties and mount options.
.It Fl o Ar property Ns = Ns Ar value
Sets the specified property on the imported pool.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for more information on the available pool properties.
.It Fl R Ar root
Sets the
@@ -347,7 +347,7 @@ for a description of dataset properties and mount options.
.It Fl o Ar property Ns = Ns Ar value
Sets the specified property on the imported pool.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for more information on the available pool properties.
.It Fl R Ar root
Sets the
man/man8/zpool-list.8
+1 -1
View File
@@ -69,7 +69,7 @@ space.
.It Fl o Ar property
Comma-separated list of properties to display.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for a list of valid properties.
The default list is
.Sy name , size , allocated , free , checkpoint, expandsize , fragmentation ,
man/man8/zpool-remove.8
+1 -1
View File
@@ -70,7 +70,7 @@ If an IO error is encountered during the removal process it will be cancelled.
The
.Sy device_removal
feature flag must be enabled to remove a top-level vdev, see
.Xr zpool-features 5 .
.Xr zpool-features 7 .
.Pp
A mirrored top-level device (log or data) can be removed by specifying the top-level mirror for the
same.
man/man8/zpool-replace.8
+1 -1
View File
@@ -77,7 +77,7 @@ Not all devices can be overridden in this manner.
.It Fl o Ar property Ns = Ns Ar value
Sets the given pool properties.
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for a list of valid properties that can be set.
The only property supported at the moment is
.Sy ashift .
man/man8/zpool-split.8
+1 -1
View File
@@ -98,7 +98,7 @@ flag.
Sets the specified property for
.Ar newpool .
See the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page for more information on the available pool properties.
.It Fl R Ar root
Set
man/man8/zpool-status.8
+1 -1
View File
@@ -50,7 +50,7 @@ is specified, then the status of each pool in the system is displayed.
For more information on pool and device health, see the
.Sx Device Failure and Recovery
section of
.Xr zpoolconcepts 8 .
.Xr zpoolconcepts 7 .
.Pp
If a scrub or resilver is in progress, this command reports the percentage done
and the estimated time to completion.
man/man8/zpool-sync.8
+2 -2
View File
@@ -48,6 +48,6 @@ will sync all pools on the system.
Otherwise, it will sync only the specified pools.
.
.Sh SEE ALSO
.Xr zpoolconcepts 7 ,
.Xr zpool-export 8 ,
.Xr zpool-iostat 8 ,
.Xr zpoolconcepts 8
.Xr zpool-iostat 8
man/man8/zpool-trim.8
+2 -2
View File
@@ -86,6 +86,6 @@ Wait until the devices are done being trimmed before returning.
.El
.
.Sh SEE ALSO
.Xr zpoolprops 7 ,
.Xr zpool-initialize 8 ,
.Xr zpool-wait 8 ,
.Xr zpoolprops 8
.Xr zpool-wait 8
man/man8/zpool-upgrade.8
+6 -6
View File
@@ -66,7 +66,7 @@ property).
.Xc
Displays legacy ZFS versions supported by the this version of ZFS.
See
.Xr zpool-features 5
.Xr zpool-features 7
for a description of feature flags features supported by this version of ZFS.
.It Xo
.Nm zpool
@@ -87,7 +87,7 @@ then no upgrade will take place.
Once this is done, the pool will no longer be accessible on systems that do not
support feature flags.
See
.Xr zpool-features 5
.Xr zpool-features 7
for details on compatibility with systems that support feature flags, but do not
support all features enabled on the pool.
.Bl -tag -width Ds
@@ -103,7 +103,7 @@ supported legacy version number.
.El
.
.Sh SEE ALSO
.Xr zpool-features 5 ,
.Xr zpool-history 8 ,
.Xr zpoolconcepts 8 ,
.Xr zpoolprops 8
.Xr zpool-features 7 ,
.Xr zpoolconcepts 7 ,
.Xr zpoolprops 7 ,
.Xr zpool-history 8
man/man8/zpool.8
+9 -12
View File
@@ -54,7 +54,7 @@ See
for information on managing datasets.
.Pp
For an overview of creating and managing ZFS storage pools see the
.Xr zpoolconcepts 8
.Xr zpoolconcepts 7
manual page.
.
.Sh SUBCOMMANDS
@@ -126,7 +126,7 @@ Creates a new pool by splitting all mirrors in an existing pool (which decreases
.
.Ss Properties
Available pool properties listed in the
.Xr zpoolprops 8
.Xr zpoolprops 7
manual page.
.Bl -tag -width Ds
.It Xr zpool-list 8
@@ -157,10 +157,8 @@ These events are consumed by the
.Xr zed 8
and used to automate administrative tasks such as replacing a failed device
with a hot spare.
For more information about the subclasses and event payloads
that can be generated see the
.Xr zfs-events 5
man page.
That manual page also describes the subclasses and event payloads
that can be generated.
.It Xr zpool-history 8
Displays the command history of the specified pool(s) or all pools if no pool is
specified.
@@ -523,9 +521,10 @@ is not set, it is assumed that the user is allowed to run
.Sy Evolving
.
.Sh SEE ALSO
.Xr zfs-events 5 ,
.Xr zfs-module-parameters 5 ,
.Xr zpool-features 5 ,
.Xr zfs 4 ,
.Xr zpool-features 7 ,
.Xr zpoolconcepts 7 ,
.Xr zpoolprops 7 ,
.Xr zed 8 ,
.Xr zfs 8 ,
.Xr zpool-add 8 ,
@@ -558,6 +557,4 @@ is not set, it is assumed that the user is allowed to run
.Xr zpool-sync 8 ,
.Xr zpool-trim 8 ,
.Xr zpool-upgrade 8 ,
.Xr zpool-wait 8 ,
.Xr zpoolconcepts 8 ,
.Xr zpoolprops 8
.Xr zpool-wait 8
man/man8/zpoolconcepts.8
-512
View File
@@ -1,512 +0,0 @@
.\"
.\" CDDL HEADER START
.\"
.\" 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]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. 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) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\"
.Dd June 2, 2021
.Dt ZPOOLCONCEPTS 8
.Os
.
.Sh NAME
.Nm zpoolconcepts
.Nd overview of ZFS storage pools
.
.Sh DESCRIPTION
.Ss Virtual Devices (vdevs)
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:
.Bl -tag -width "special"
.It Sy disk
A block device, typically located under
.Pa /dev .
ZFS 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
.Po the relative portion of the path under
.Pa /dev
.Pc .
A whole disk can be specified by omitting the slice or partition designation.
For example,
.Pa sda
is equivalent to
.Pa /dev/sda .
When given a whole disk, ZFS automatically labels the disk, if necessary.
.It Sy file
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 on which it resides.
A file must be specified by a full path.
.It Sy mirror
A mirror of two or more devices.
Data is replicated in an identical fashion across all components of a mirror.
A mirror with
.Em N No disks of size Em X No can hold Em X No bytes and can withstand Em N-1
devices failing without losing data.
.It Sy raidz , raidz1 , raidz2 , raidz3
A variation on RAID-5 that allows for better distribution of parity and
eliminates the RAID-5
.Qq write hole
.Pq in which data and parity become inconsistent after a power loss .
Data and parity is striped across all disks within a raidz group.
.Pp
A raidz group can have single, double, or triple parity, meaning that the
raidz group can sustain one, two, or three failures, respectively, without
losing any data.
The
.Sy raidz1
vdev type specifies a single-parity raidz group; the
.Sy raidz2
vdev type specifies a double-parity raidz group; and the
.Sy raidz3
vdev type specifies a triple-parity raidz group.
The
.Sy raidz
vdev type is an alias for
.Sy raidz1 .
.Pp
A raidz group with
.Em N No disks of size Em X No with Em P No parity disks can hold approximately
.Em (N-P)*X No bytes and can withstand Em P No devices failing without losing data.
The minimum number of devices in a raidz group is one more than the number of
parity disks.
The recommended number is between 3 and 9 to help increase performance.
.It Sy draid , draid1 , draid2 , draid3
A variant of raidz that provides integrated distributed hot spares which
allows for faster resilvering while retaining the benefits of raidz.
A dRAID vdev is constructed from multiple internal raidz groups, each with
.Em D No data devices and Em P No parity devices.
These groups are distributed over all of the children in order to fully
utilize the available disk performance.
.Pp
Unlike raidz, dRAID uses a fixed stripe width (padding as necessary with
zeros) to allow fully sequential resilvering.
This fixed stripe width significantly effects both usable capacity and IOPS.
For example, with the default
.Em D=8 No and Em 4kB No disk sectors the minimum allocation size is Em 32kB .
If using compression, this relatively large allocation size can reduce the
effective compression ratio.
When using ZFS volumes and dRAID, the default of the
.Sy volblocksize
property is increased to account for the allocation size.
If a dRAID pool will hold a significant amount of small blocks, it is
recommended to also add a mirrored
.Sy special
vdev to store those blocks.
.Pp
In regards to I/O, performance is similar to raidz since for any read all
.Em D No data disks must be accessed.
Delivered random IOPS can be reasonably approximated as
.Sy floor((N-S)/(D+P))*single_drive_IOPS .
.Pp
Like raidzm a dRAID can have single-, double-, or triple-parity.
The
.Sy draid1 ,
.Sy draid2 ,
and
.Sy draid3
types can be used to specify the parity level.
The
.Sy draid
vdev type is an alias for
.Sy draid1 .
.Pp
A dRAID with
.Em N No disks of size Em X , D No data disks per redundancy group, Em P
.No parity level, and Em S No distributed hot spares can hold approximately
.Em (N-S)*(D/(D+P))*X No bytes and can withstand Em P
devices failing without losing data.
.It Sy draid Ns Oo Ar parity Oc Ns Oo Sy \&: Ns Ar data Ns Sy d Oc Ns Oo Sy \&: Ns Ar children Ns Sy c Oc Ns Oo Sy \&: Ns Ar spares Ns Sy s Oc
A non-default dRAID configuration can be specified by appending one or more
of the following optional arguments to the
.Sy draid
keyword:
.Bl -tag -compact -width "children"
.It Ar parity
The parity level (1-3).
.It Ar data
The number of data devices per redundancy group.
In general, a smaller value of
.Em D No will increase IOPS, improve the compression ratio,
and speed up resilvering at the expense of total usable capacity.
Defaults to
.Em 8 , No unless Em N-P-S No is less than Em 8 .
.It Ar children
The expected number of children.
Useful as a cross-check when listing a large number of devices.
An error is returned when the provided number of children differs.
.It Ar spares
The number of distributed hot spares.
Defaults to zero.
.El
.It Sy spare
A pseudo-vdev which keeps track of available hot spares for a pool.
For more information, see the
.Sx Hot Spares
section.
.It Sy log
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, raidz vdev types are not supported for the intent log.
For more information, see the
.Sx Intent Log
section.
.It Sy dedup
A device dedicated solely for deduplication tables.
The redundancy of this device should match the redundancy of the other normal
devices in the pool.
If more than one dedup device is specified, then
allocations are load-balanced between those devices.
.It Sy special
A device dedicated solely for allocating various kinds of internal metadata,
and optionally small file blocks.
The redundancy of this device should match the redundancy of the other normal
devices in the pool.
If more than one special device is specified, then
allocations are load-balanced between those devices.
.Pp
For more information on special allocations, see the
.Sx Special Allocation Class
section.
.It Sy cache
A device used to cache storage pool data.
A cache device cannot be configured as a mirror or raidz group.
For more information, see the
.Sx Cache Devices
section.
.El
.Pp
Virtual devices cannot be nested, so a mirror or raidz virtual device can only
contain files or disks.
Mirrors of mirrors
.Pq or other combinations
are not allowed.
.Pp
A pool can have any number of virtual devices at the top of the configuration
.Po known as
.Qq root vdevs
.Pc .
Data is dynamically distributed across all top-level devices to balance data
among devices.
As new virtual devices are added, ZFS automatically places data on the newly
available devices.
.Pp
Virtual devices are specified one at a time on the command line,
separated by whitespace.
Keywords like
.Sy mirror No and Sy raidz
are used to distinguish where a group ends and another begins.
For example, the following creates a pool with two root vdevs,
each a mirror of two disks:
.Dl # Nm zpool Cm create Ar mypool Sy mirror Ar sda sdb Sy mirror Ar sdc sdd
.
.Ss Device Failure and Recovery
ZFS supports a rich set of mechanisms for handling device failure and data
corruption.
All metadata and data is checksummed, and ZFS automatically repairs bad data
from a good copy when corruption is detected.
.Pp
In order to take advantage of these features, a pool must make use of some form
of redundancy, using either mirrored or raidz groups.
While ZFS 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.
.Pp
A pool's health status is described by one of three states:
.Sy online , degraded , No or Sy 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.
.Pp
The health of the top-level vdev, such as a mirror or raidz 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:
.Bl -tag -width "DEGRADED"
.It Sy DEGRADED
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.
.Pp
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:
.Bl -bullet -compact
.It
The number of checksum errors exceeds acceptable levels and the device is
degraded as an indication that something may be wrong.
ZFS continues to use the device as necessary.
.It
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.
.El
.It Sy FAULTED
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.
.Pp
One or more component devices is in the faulted state, and insufficient
replicas exist to continue functioning.
The underlying conditions are as follows:
.Bl -bullet -compact
.It
The device could be opened, but the contents did not match expected values.
.It
The number of I/O errors exceeds acceptable levels and the device is faulted to
prevent further use of the device.
.El
.It Sy OFFLINE
The device was explicitly taken offline by the
.Nm zpool Cm offline
command.
.It Sy ONLINE
The device is online and functioning.
.It Sy REMOVED
The device was physically removed while the system was running.
Device removal detection is hardware-dependent and may not be supported on all
platforms.
.It Sy UNAVAIL
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.
.El
.Pp
Checksum errors represent events where a disk returned data that was expected
to be correct, but was not.
In other words, these are instances of silent data corruption.
The checksum errors are reported in
.Nm zpool Cm status
and
.Nm zpool Cm events .
When a block is stored redundantly, a damaged block may be reconstructed
(e.g. from raidz parity or a mirrored copy).
In this case, ZFS reports the checksum error against the disks that contained
damaged data.
If a block is unable to be reconstructed (e.g. due to 3 disks being damaged
in a raidz2 group), it is not possible to determine which disks were silently
corrupted.
In this case, checksum errors are reported for all disks on which the block
is stored.
.Pp
If a device is removed and later re-attached to the system,
ZFS attempts online the device automatically.
Device attachment detection is hardware-dependent
and might not be supported on all platforms.
.
.Ss Hot Spares
ZFS allows devices to be associated with pools as
.Qq 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
.Sy spare
vdev with any number of devices.
For example,
.Dl # Nm zpool Cm create Ar pool Sy mirror Ar sda sdb Sy spare Ar sdc sdd
.Pp
Spares can be shared across multiple pools, and can be added with the
.Nm zpool Cm add
command and removed with the
.Nm zpool Cm remove
command.
Once a spare replacement is initiated, a new
.Sy spare
vdev 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.
.Pp
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.
.Pp
Shared spares add some risk.
If the pools are imported on different hosts,
and both pools suffer a device failure at the same time,
both could attempt to use the spare at the same time.
This may not be detected, resulting in data corruption.
.Pp
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.
.Pp
The
.Sy draid
vdev type provides distributed hot spares.
These hot spares are named after the dRAID vdev they're a part of
.Po Sy draid1 Ns - Ns Ar 2 Ns - Ns Ar 3 No specifies spare Ar 3 No of vdev Ar 2 ,
.No which is a single parity dRAID Pc
and may only be used by that dRAID vdev.
Otherwise, they behave the same as normal hot spares.
.Pp
Spares cannot replace log devices.
.
.Ss Intent Log
The ZFS Intent Log (ZIL) satisfies POSIX requirements for synchronous
transactions.
For instance, databases often require their transactions to be on stable storage
devices when returning from a system call.
NFS and other applications can also use
.Xr fsync 2
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 NVRAM or a dedicated disk.
For example:
.Dl # Nm zpool Cm create Ar pool sda sdb Sy log Ar sdc
.Pp
Multiple log devices can also be specified, and they can be mirrored.
See the
.Sx EXAMPLES
section for an example of mirroring multiple log devices.
.Pp
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 .
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 allows 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.
.Pp
To create a pool with cache devices, specify a
.Sy cache
vdev with any number of devices.
For example:
.Dl # Nm zpool Cm create Ar pool sda sdb Sy cache Ar sdc sdd
.Pp
Cache devices cannot be mirrored or part of a raidz configuration.
If a read error is encountered on a cache device, that read I/O is reissued to
the original storage pool device, which might be part of a mirrored or raidz
configuration.
.Pp
The content of the cache devices is persistent across reboots and restored
asynchronously when importing the pool in L2ARC (persistent L2ARC).
This can be disabled by setting
.Sy l2arc_rebuild_enabled Ns = Ns Sy 0 .
For cache devices smaller than
.Em 1GB ,
we do not write the metadata structures
required for rebuilding the L2ARC in order not to waste space.
This can be changed with
.Sy l2arc_rebuild_blocks_min_l2size .
The cache device header
.Pq Em 512B
is updated even if no metadata structures are written.
Setting
.Sy l2arc_headroom Ns = Ns Sy 0
will result in scanning the full-length ARC lists for cacheable content to be
written in L2ARC (persistent ARC).
If a cache device is added with
.Nm zpool Cm add
its label and header will be overwritten and its contents are not going to be
restored in L2ARC, even if the device was previously part of the pool.
If a cache device is onlined with
.Nm zpool Cm online
its contents will be restored in L2ARC.
This is useful in case of memory pressure
where the contents of the cache device are not fully restored in L2ARC.
The user can off- and online the cache device when there is less memory pressure
in order to fully restore its contents to L2ARC.
.
.Ss Pool checkpoint
Before starting critical procedures that include destructive actions
.Pq like 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, certain operations are not allowed while a pool has a checkpoint.
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:
.Dl # Nm zpool Cm checkpoint Ar pool
.Pp
To later rewind to its checkpointed state, you need to first export it and
then rewind it during import:
.Dl # Nm zpool Cm export Ar pool
.Dl # Nm zpool Cm import Fl -rewind-to-checkpoint Ar pool
.Pp
To discard the checkpoint from a pool:
.Dl # Nm zpool Cm checkpoint Fl d Ar pool
.Pp
Dataset reservations (controlled by the
.Sy reservation No and Sy refreservation
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 Special Allocation Class
Allocations in the special class are dedicated to specific block types.
By default this includes all metadata, the indirect blocks of user data, and
any deduplication tables.
The class can also be provisioned to accept small file blocks.
.Pp
A pool must always have at least one normal
.Pq non- Ns Sy dedup Ns /- Ns Sy special
vdev before
other devices can be assigned to the special class.
If the
.Sy special
class becomes full, then allocations intended for it
will spill back into the normal class.
.Pp
Deduplication tables can be excluded from the special class by unsetting the
.Sy zfs_ddt_data_is_special
ZFS module parameter.
.Pp
Inclusion of small file blocks in the special class is opt-in.
Each dataset can control the size of small file blocks allowed
in the special class by setting the
.Sy special_small_blocks
property to nonzero.
See
.Xr zfsprops 8
for more info on this property.
man/man8/zpoolprops.8
-412
View File
@@ -1,412 +0,0 @@
.\"
.\" CDDL HEADER START
.\"
.\" 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]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright (c) 2007, Sun Microsystems, Inc. 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) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\"
.Dd May 27, 2021
.Dt ZPOOLPROPS 8
.Os
.
.Sh NAME
.Nm zpoolprops
.Nd properties of ZFS storage pools
.
.Sh DESCRIPTION
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.
.Pp
The following are read-only properties:
.Bl -tag -width "unsupported@guid"
.It Cm allocated
Amount of storage used within the pool.
See
.Sy fragmentation
and
.Sy free
for more information.
.It Sy capacity
Percentage of pool space used.
This property can also be referred to by its shortened column name,
.Sy cap .
.It Sy expandsize
Amount of uninitialized space within the pool or device that can be used to
increase the total capacity of the pool.
On whole-disk vdevs, this is the space beyond the end of the GPT –
typically occurring when a LUN is dynamically expanded
or a disk replaced with a larger one.
On partition vdevs, this is the space appended to the partition after it was
added to the pool – most likely by resizing it in-place.
The space can be claimed for the pool by bringing it online with
.Sy autoexpand=on
or using
.Nm zpool Cm online Fl e .
.It Sy fragmentation
The amount of fragmentation in the pool.
As the amount of space
.Sy allocated
increases, it becomes more difficult to locate
.Sy free
space.
This may result in lower write performance compared to pools with more
unfragmented free space.
.It Sy free
The amount of free space available in the pool.
By contrast, the
.Xr zfs 8
.Sy available
property describes how much new data can be written to ZFS filesystems/volumes.
The zpool
.Sy free
property is not generally useful for this purpose, and can be substantially more than the zfs
.Sy available
space.
This discrepancy is due to several factors, including raidz parity;
zfs reservation, quota, refreservation, and refquota properties; and space set aside by
.Sy spa_slop_shift
(see
.Xr zfs-module-parameters 5
for more information).
.It Sy freeing
After a file system or snapshot is destroyed, the space it was using is
returned to the pool asynchronously.
.Sy freeing
is the amount of space remaining to be reclaimed.
Over time
.Sy freeing
will decrease while
.Sy free
increases.
.It Sy health
The current health of the pool.
Health can be one of
.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 (i.e. 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 guid
Information about unsupported features that are enabled on the pool.
See
.Xr zpool-features 5
for details.
.El
.Pp
The space usage properties report actual physical space available to the
storage pool.
The physical space can be different from the total amount of space that any
contained datasets can actually use.
The amount of space used in a raidz configuration depends on the characteristics
of the data being written.
In addition, ZFS reserves some space for internal accounting that the
.Xr zfs 8
command takes into account, but the
.Nm
command does not.
For non-full pools of a reasonable size, these effects should be invisible.
For small pools, or pools that are close to being completely full, these
discrepancies may become more noticeable.
.Pp
The following property can be set at creation time and import time:
.Bl -tag -width Ds
.It Sy altroot
Alternate root directory.
If set, this directory is prepended to any mount points within the pool.
This can be used when examining an unknown pool where the mount points cannot be
trusted, or in an alternate boot environment, where the typical paths are not
valid.
.Sy altroot
is not a persistent property.
It is valid only while the system is up.
Setting
.Sy altroot
defaults to using
.Sy cachefile Ns = Ns Sy none ,
though this may be overridden using an explicit setting.
.El
.Pp
The following property can be set only at import time:
.Bl -tag -width Ds
.It Sy readonly Ns = Ns Sy on Ns | Ns Sy off
If set to
.Sy on ,
the pool will be imported in read-only mode.
This property can also be referred to by its shortened column name,
.Sy rdonly .
.El
.Pp
The following properties can be set at creation time and import time, and later
changed with the
.Nm zpool Cm set
command:
.Bl -tag -width Ds
.It Sy ashift Ns = Ns Sy ashift
Pool sector size exponent, to the power of
.Sy 2
(internally referred to as
.Sy ashift ) .
Values from 9 to 16, inclusive, are valid; also, the
value 0 (the default) means to auto-detect using the kernel's block
layer and a ZFS internal exception list.
I/O operations will be aligned to the specified size boundaries.
Additionally, the minimum (disk)
write size will be set to the specified size, so this represents a
space vs. performance trade-off.
For optimal performance, the pool sector size should be greater than
or equal to the sector size of the underlying disks.
The typical case for setting this property is when
performance is important and the underlying disks use 4KiB sectors but
report 512B sectors to the OS (for compatibility reasons); in that
case, set
.Sy ashift Ns = Ns Sy 12
(which is
.Sy 1<<12 No = Sy 4096 ) .
When set, this property is
used as the default hint value in subsequent vdev operations (add,
attach and replace).
Changing this value will not modify any existing
vdev, not even on disk replacement; however it can be used, for
instance, to replace a dying 512B sectors disk with a newer 4KiB
sectors device: this will probably result in bad performance but at the
same time could prevent loss of data.
.It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off
Controls automatic pool expansion when the underlying LUN is grown.
If set to
.Sy on ,
the pool will be resized according to the size of the expanded device.
If the device is part of a mirror or raidz then all devices within that
mirror/raidz group must be expanded before the new space is made available to
the pool.
The default behavior is
.Sy off .
This property can also be referred to by its shortened column name,
.Sy expand .
.It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off
Controls automatic device replacement.
If set to
.Sy off ,
device replacement must be initiated by the administrator by using the
.Nm zpool Cm replace
command.
If set to
.Sy on ,
any new device, found in the same physical location as a device that previously
belonged to the pool, is automatically formatted and replaced.
The default behavior is
.Sy off .
This property can also be referred to by its shortened column name,
.Sy replace .
Autoreplace can also be used with virtual disks (like device
mapper) provided that you use the /dev/disk/by-vdev paths setup by
vdev_id.conf.
See the
.Xr vdev_id 8
manual page for more details.
Autoreplace and autoonline require the ZFS Event Daemon be configured and
running.
See the
.Xr zed 8
manual page for more details.
.It Sy autotrim Ns = Ns Sy on Ns | Ns Sy off
When set to
.Sy on
space which has been recently freed, and is no longer allocated by the pool,
will be periodically trimmed.
This allows block device vdevs which support
BLKDISCARD, such as SSDs, or file vdevs on which the underlying file system
supports hole-punching, to reclaim unused blocks.
The default value for this property is
.Sy off .
.Pp
Automatic TRIM does not immediately reclaim blocks after a free.
Instead, it will optimistically delay allowing smaller ranges to be aggregated
into a few larger ones.
These can then be issued more efficiently to the storage.
TRIM on L2ARC devices is enabled by setting
.Sy l2arc_trim_ahead > 0 .
.Pp
Be aware that automatic trimming of recently freed data blocks can put
significant stress on the underlying storage devices.
This will vary depending of how well the specific device handles these commands.
For lower-end devices it is often possible to achieve most of the benefits
of automatic trimming by running an on-demand (manual) TRIM periodically
using the
.Nm zpool Cm trim
command.
.It Sy bootfs Ns = Ns Sy (unset) Ns | Ns Ar pool Ns Op / Ns Ar dataset
Identifies the default bootable dataset for the root pool.
This property is expected to be set mainly by the installation and upgrade programs.
Not all Linux distribution boot processes use the bootfs property.
.It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none
Controls the location of where the pool configuration is cached.
Discovering all pools on system startup requires a cached copy of the
configuration data that is stored on the root file system.
All pools in this cache are automatically imported when the system boots.
Some environments, such as install and clustering, need to cache this
information in a different location so that pools are not automatically
imported.
Setting this property caches the pool configuration in a different location that
can later be imported with
.Nm zpool Cm import Fl c .
Setting it to the value
.Sy none
creates a temporary pool that is never cached, and the
.Qq
.Pq empty string
uses the default location.
.Pp
Multiple pools can share the same cache file.
Because the kernel destroys and recreates this file when pools are added and
removed, care should be taken when attempting to access this file.
When the last pool using a
.Sy cachefile
is exported or destroyed, the file will be empty.
.It Sy comment Ns = Ns Ar text
A text string consisting of printable ASCII characters that will be stored
such that it is available even if the pool becomes faulted.
An administrator can provide additional information about a pool using this
property.
.It Sy compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns …
Specifies that the pool maintain compatibility with specific feature sets.
When set to
.Sy off
(or unset) compatibility is disabled (all features may be enabled); when set to
.Sy legacy Ns
no features may be enabled.
When set to a comma-separated list of filenames
(each filename may either be an absolute path, or relative to
.Pa /etc/zfs/compatibility.d
or
.Pa /usr/share/zfs/compatibility.d )
the lists of requested features are read from those files, separated by
whitespace and/or commas.
Only features present in all files may be enabled.
.Pp
See
.Xr zpool-features 5 ,
.Xr zpool-create 8
and
.Xr zpool-upgrade 8
for more information on the operation of compatibility feature sets.
.It Sy dedupditto Ns = Ns Ar number
This property is deprecated and no longer has any effect.
.It Sy delegation Ns = Ns Sy on Ns | Ns Sy off
Controls whether a non-privileged user is granted access based on the dataset
permissions defined on the dataset.
See
.Xr zfs 8
for more information on ZFS delegated administration.
.It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic
Controls the system behavior in the event of catastrophic pool failure.
This condition is typically a result of a loss of connectivity to the underlying
storage device(s) or a failure of all devices within the pool.
The behavior of such an event is determined as follows:
.Bl -tag -width "continue"
.It Sy wait
Blocks all I/O access until the device connectivity is recovered and the errors
are cleared.
This is the default behavior.
.It Sy continue
Returns
.Er EIO
to any new write I/O requests but allows reads to any of the remaining healthy
devices.
Any write requests that have yet to be committed to disk would be blocked.
.It Sy panic
Prints out a message to the console and generates a system crash dump.
.El
.It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled
The value of this property is the current state of
.Ar feature_name .
The only valid value when setting this property is
.Sy enabled
which moves
.Ar feature_name
to the enabled state.
See
.Xr zpool-features 5
for details on feature states.
.It Sy listsnapshots Ns = Ns Sy on Ns | Ns Sy off
Controls whether information about snapshots associated with this pool is
output when
.Nm zfs Cm list
is run without the
.Fl t
option.
The default value is
.Sy off .
This property can also be referred to by its shortened name,
.Sy listsnaps .
.It Sy multihost Ns = Ns Sy on Ns | Ns Sy off
Controls whether a pool activity check should be performed during
.Nm zpool Cm import .
When a pool is determined to be active it cannot be imported, even with the
.Fl f
option.
This property is intended to be used in failover configurations
where multiple hosts have access to a pool on shared storage.
.Pp
Multihost provides protection on import only.
It does not protect against an
individual device being used in multiple pools, regardless of the type of vdev.
See the discussion under
.Nm zpool Cm create .
.Pp
When this property is on, periodic writes to storage occur to show the pool is
in use.
See
.Sy zfs_multihost_interval
in the
.Xr zfs-module-parameters 5
manual page.
In order to enable this property each host must set a unique hostid.
See
.Xr genhostid 1
.Xr zgenhostid 8
.Xr spl-module-parameters 5
for additional details.
The default value is
.Sy off .
.It Sy version Ns = Ns Ar version
The current on-disk version of the pool.
This can be increased, but never decreased.
The preferred method of updating pools is with the
.Nm zpool Cm upgrade
command, though this property can be used when a specific version is needed for
backwards compatibility.
Once feature flags are enabled on a pool this property will no longer have a
value.
.El