c5ebfbbe19
Moved subcommand topics into individual manpages. Reordered and grouped the list of subcommands by topic. Moved concepts overview to `zpoolconcepts.8` and the long list of available pool properties to `zpoolprops.8`. Internal cross-references copied from `zpool.8` needed to be converted to `.Xr` external references to new subcommand manual pages. Move `autotrim` into lexical order, autotrim tacked onto the end of a list. Now it is in alphabetical order. Clarify attach/detach description. Description was too specific to command syntax. Overview clarifies reason for attaching or detaching a device. Clarify replace description, don't refer to subcommand arguments. Clarify split command description, say what split actually does and why you'd want to do it. Clarify description of upgrade, and simplify the zpool.8 wording of the zpool-upgrade(8) description. Clarify description of import, detail what zpool-import(8) actually does. Add appropriate SEE ALSO sections. Divided zpool subcommand manual pages need their own SEE ALSO sections. Also modified fsck.zfs.8 to point directly to zfs-scrub.8 and zed.8.in to include a direct reference to zfs-events.8 Reviewed-by: Matt Ahrens <matt@delphix.com> Reviewed-by: Kjeld Schouten <kjeld@schouten-lebbing.nl> Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Signed-off-by: Ross Williams <ross@ross-williams.net> Closes #9564
367 lines
13 KiB
Groff
367 lines
13 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 Linux
|
|
.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.
|
|
Uninitialized space consists of any space on an EFI labeled vdev which has not
|
|
been brought online
|
|
.Po e.g, using
|
|
.Nm zpool Cm online Fl e
|
|
.Pc .
|
|
This space occurs when a LUN is dynamically expanded.
|
|
.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 party; 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.
|
|
.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
|