| .\" |
| .\" 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 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 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 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 |