diff options
Diffstat (limited to 'static/freebsd/man7/zpoolprops.7')
| -rw-r--r-- | static/freebsd/man7/zpoolprops.7 | 687 |
1 files changed, 687 insertions, 0 deletions
diff --git a/static/freebsd/man7/zpoolprops.7 b/static/freebsd/man7/zpoolprops.7 new file mode 100644 index 00000000..c383805a --- /dev/null +++ b/static/freebsd/man7/zpoolprops.7 @@ -0,0 +1,687 @@ +.\" SPDX-License-Identifier: CDDL-1.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 https://opensource.org/licenses/CDDL-1.0. +.\" 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> +.\" Copyright (c) 2023, 2026, Klara Inc. +.\" +.Dd March 2, 2026 +.Dt ZPOOLPROPS 7 +.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 +User properties have no effect on ZFS behavior. +Use them to annotate pools in a way that is meaningful in your environment. +For more information about user properties, see the +.Sx User Properties +section. +.Pp +The following are read-only properties: +.Bl -tag -width "last_scrubbed_txg" +.It Sy allocated +Amount of storage used within the pool. +See +.Sy fragmentation +and +.Sy free +for more information. +.It Sy available +The amount of free space available in the pool, adjusted for raidz parity +overhead. +The +.Sy available +property is calculated as: +.Pp +.Sy usable - used +.Pp +See +.Sy usable , +.Sy used , +and +.Sy free +for more information. +.It Sy bcloneratio +The ratio of the total amount of storage that would be required to store all +the cloned blocks without cloning to the actual storage used. +The +.Sy bcloneratio +property is calculated as: +.Pp +.Sy ( ( bclonesaved + bcloneused ) * 100 ) / bcloneused +.It Sy bclonesaved +The amount of additional storage that would be required if block cloning +was not used. +.It Sy bcloneused +The amount of storage used by cloned blocks. +.It Sy capacity +Percentage of pool space used. +This property can also be referred to by its shortened column name, +.Sy cap . +.It Sy dedupcached +Total size of the deduplication table currently loaded into the ARC. +See +.Xr zpool-prefetch 8 . +.It Sy dedup_table_size +Total on-disk size of the deduplication table. +.It Sy dedupratio +The ratio of the total amount of storage that would be required to store all +the deduplicated blocks without deduplication to the actual storage used. +The +.Sy dedupratio +property is calculated as: +.Pp +.Sy ( ( dedupsaved + dedupused ) * 100 ) / dedupused +.It Sy dedupsaved +The amount of additional storage that would be required if deduplication +was not used. +This represents the space saved by deduplication. +.It Sy dedupused +The amount of storage used by deduplicated blocks. +This is the actual physical space occupied on disk after deduplication. +.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 4 +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 guid +A unique identifier for the pool. +.It Sy health +The current health of the pool. +Health can be one of +.Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL . +.It Sy last_scrubbed_txg +Indicates the transaction group (TXG) up to which the most recent scrub +operation has checked and repaired the dataset. +This provides insight into the data integrity status of their pool at +a specific point in time. +.Xr zpool-scrub 8 +can utilize this property to scan only data that has changed since the last +scrub completed, when given the +.Fl C +flag. +This property is not updated when performing an error scrub with the +.Fl e +flag. +.It Sy leaked +Space not released while +.Sy freeing +due to corruption, now permanently leaked into 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 7 +for details. +.It Sy usable +Estimate of total storage pool size, adjusted for raidz parity overhead. +The adjustment assumes a fixed 128KiB record size to compute a data-to-parity +ratio. +.Sy usable +is a heuristic for allocation and should not be interpreted as an exact measure +of usable space. +.It Sy used +Estimate of storage used within the storage pool, adjusted for raidz parity +overhead. +The adjustment assumes a fixed 128KiB record size to compute a data-to-parity +ratio. +.Sy used +is a heuristic for allocation and should not be interpreted as an exact measure +of used space. +.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 properties are read-only metrics for allocation classes: +.Bl -ohang +.It Xo Sy class_dedup_allocated , class_dedup_available , class_dedup_capacity , +.Sy class_dedup_expandsize , class_dedup_fragmentation , class_dedup_free , +.Sy class_dedup_size , class_dedup_usable , class_dedup_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy dedup +metaslab allocator class. +.Ed +.It Xo Sy class_elog_allocated , class_elog_available , class_elog_capacity , +.Sy class_elog_expandsize , class_elog_fragmentation , class_elog_free , +.Sy class_elog_size , class_elog_usable , class_elog_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy embedded_log +metaslab allocator class. +.Ed +.It Xo Sy class_log_allocated , class_log_available , class_log_capacity , +.Sy class_log_expandsize , class_log_fragmentation , class_log_free , +.Sy class_log_size , class_log_usable , class_log_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy log +metaslab allocator class. +.Ed +.It Xo Sy class_normal_allocated , class_normal_available , +.Sy class_normal_capacity , class_normal_expandsize , +.Sy class_normal_fragmentation , class_normal_free , class_normal_size , +.Sy class_normal_usable , class_normal_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy normal +metaslab allocator class. +.Ed +.It Xo Sy class_special_allocated , class_special_available , +.Sy class_special_capacity , class_special_expandsize , +.Sy class_special_fragmentation , class_special_free , class_special_size , +.Sy class_special_usable , class_special_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy special +metaslab allocator class. +.Ed +.It Xo Sy class_special_elog_allocated , class_special_elog_available , +.Sy class_special_elog_capacity , class_special_elog_expandsize , +.Sy class_special_elog_fragmentation , class_special_elog_free , +.Sy class_special_elog_size , class_special_elog_usable , +.Sy class_special_elog_used +.Xc +.Bd -ragged -offset Ds -compact +Space usage properties of the pool's +.Sy special_embedded_log +metaslab allocator class. +.Ed +.El +.Pp +Each allocation class is described by these values: +.Bl -tag -width "fragmentation" +.It Sy allocated +Amount of storage used within the allocation class. +.It Sy available +Estimate of free space available in the allocation class, adjusted for raidz +parity overhead. +The adjustment assumes a fixed 128KiB record size to compute a data-to-parity +ratio. +.Sy available +is a heuristic for allocation and should not be interpreted as an exact measure +of usable space. +Actual usable space depends on a variety of factors such as dataset record size +and compression. +.It Sy capacity +Percentage of allocation class space used. +.It Sy expandsize +Amount of uninitialized space within the allocation class that can be used to +increase the capacity of the allocator. +See the pool-wide +.Sy expandsize +property. +.It Sy fragmentation +The amount of free space fragmentation in the allocation class. +See the pool-wide +.Sy fragmentation +property. +.It Sy free +The amount of free space available in the allocation class. +This value is not adjusted for factors such as dataset record size, compression, +or raidz parity overhead. +See the pool-wide +.Sy free +property. +.It Sy size +Total size of the allocation class. +.It Sy usable +Estimate of total allocation class size, adjusted for raidz parity overhead. +The adjustment assumes a fixed 128KiB record size to compute a data-to-parity +ratio. +.Sy usable +is a heuristic for allocation and should not be interpreted as an exact measure +of usable space. +.It Sy used +Estimate of storage used within the allocation class, adjusted for raidz parity +overhead. +The adjustment assumes a fixed 128KiB record size to compute a data-to-parity +ratio. +.Sy used +is a heuristic for allocation and should not be interpreted as an exact measure +of used space. +.El +.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 Ar 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/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 +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 7 , +.Xr zpool-create 8 +and +.Xr zpool-upgrade 8 +for more information on the operation of compatibility feature sets. +.It Sy dedup_table_quota Ns = Ns Ar number Ns | Ns Sy none Ns | Ns Sy auto +This property sets a limit on the on-disk size of the pool's dedup table. +Entries will not be added to the dedup table once this size is reached; +if a dedup table already exists, and is larger than this size, they +will not be removed as part of setting this property. +Existing entries will still have their reference counts updated. +.Pp +The actual size limit of the table may be above or below the quota, +depending on the actual on-disk size of the entries (which may be +approximated for purposes of calculating the quota). +That is, setting a quota size of 1M may result in the maximum size being +slightly below, or slightly above, that value. +Set to +.Sy 'none' +to disable. +In automatic mode, which is the default, the size of a dedicated dedup vdev +is used as the quota limit. +.Pp +The +.Sy dedup_table_quota +property works for both legacy and fast dedup tables. +.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 with +.Nm zpool Cm clear . +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 7 +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 4 +manual page. +In order to enable this property each host must set a unique hostid. +See +.Xr genhostid 1 +.Xr zgenhostid 8 +.Xr spl 4 +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 +. +.Ss User Properties +In addition to the standard native properties, ZFS supports arbitrary user +properties. +User properties have no effect on ZFS behavior, but applications or +administrators can use them to annotate pools. +.Pp +User property names must contain a colon +.Pq Qq Sy \&: +character to distinguish them from native properties. +They may contain lowercase letters, numbers, and the following punctuation +characters: colon +.Pq Qq Sy \&: , +dash +.Pq Qq Sy - , +period +.Pq Qq Sy \&. , +and underscore +.Pq Qq Sy _ . +The expected convention is that the property name is divided into two portions +such as +.Ar module : Ns Ar property , +but this namespace is not enforced by ZFS. +User property names can be at most 255 characters, and cannot begin with a dash +.Pq Qq Sy - . +.Pp +When making programmatic use of user properties, it is strongly suggested to use +a reversed DNS domain name for the +.Ar module +component of property names to reduce the chance that two +independently-developed packages use the same property name for different +purposes. +.Pp +The values of user properties are arbitrary strings and +are never validated. +All of the commands that operate on properties +.Po Nm zpool Cm list , +.Nm zpool Cm get , +.Nm zpool Cm set , +and so forth +.Pc +can be used to manipulate both native properties and user properties. +Use +.Nm zpool Cm set Ar name Ns = +to clear a user property. +Property values are limited to 8192 bytes. |