zpoolprops.7 (18511B)
- .\"
- .\" 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, Klara Inc.
- .\"
- .Dd November 18, 2024
- .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 "unsupported@guid"
- .It Sy allocated
- Amount of storage used within the pool.
- See
- .Sy fragmentation
- 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 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.
- .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 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
- .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.