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
|