372 lines
14 KiB
Groff
372 lines
14 KiB
Groff
.\"
|
||
.\" 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 August 9, 2019
|
||
.Dt ZPOOLPROPS 8
|
||
.Os
|
||
.Sh NAME
|
||
.Nm zpoolprops
|
||
.Nd available properties for 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 Ds
|
||
.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 (e.g. 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 feature_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=12
|
||
(which is 1<<12 = 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
|
||
man page for more details.
|
||
Autoreplace and autoonline require the ZFS Event Daemon be configured and
|
||
running. See the
|
||
.Xr zed 8
|
||
man 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 setting 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 in to
|
||
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 / 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 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
|
||
.Sy zpool 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
|
||
man 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
|