FreeBSD/Linux Kernel Cross Reference
sys/contrib/openzfs/man/man7/zpoolprops.7

     .\"
     .\" 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>
    .\"
    .Dd May 27, 2021
    .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
    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 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 leaked
   Space not released while
   .Sy freeing
   due to corruption, now permanently leaked into 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 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 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
   .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 7 ,
   .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 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

Cache object: 5e07b8e4957532c60777445bcd42ed57