src/man/man7/vdevprops.7

.\" SPDX-License-Identifier: CDDL-1.0
.\"
.\" 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) 2021, 2025, Klara, Inc.
.\"
.Dd July 23, 2024
.Dt VDEVPROPS 7
.Os
.
.Sh NAME
.Nm vdevprops
.Nd native and user-defined properties of ZFS vdevs
.
.Sh DESCRIPTION
Properties are divided into two types, native properties and user-defined
.Pq or Qq user
properties.
Native properties either export internal statistics or control ZFS behavior.
In addition, native properties are either editable or read-only.
User properties have no effect on ZFS behavior, but you can use them to annotate
vdevs in a way that is meaningful in your environment.
For more information about user properties, see the
.Sx User Properties
section, below.
.
.Ss Native Properties
Every vdev has a set of properties that export statistics about the vdev
as well as control various behaviors.
Properties are not inherited from top-level vdevs, with the exception of
checksum_n, checksum_t, io_n, io_t, slow_io_events, slow_io_n, and slow_io_t.
.Pp
The values of numeric properties can be specified using human-readable suffixes
.Po for example,
.Sy k , KB , M , Gb ,
and so forth, up to
.Sy Z
for zettabyte
.Pc .
The following are all valid
.Pq and equal
specifications:
.Li 1536M , 1.5g , 1.50GB .
.Pp
The values of non-numeric properties are case sensitive and must be lowercase.
.Pp
The following native properties consist of read-only statistics about the
vdev.
These properties can not be changed.
.Bl -tag -width "failure_domain"
.It Sy capacity
Percentage of vdev space used
.It Sy state
state of this vdev such as online, faulted, or offline
.It Sy guid
globally unique id of this vdev
.It Sy asize
The allocatable size of this vdev
.It Sy psize
The physical size of this vdev
.It Sy ashift
The physical sector size of this vdev expressed as the power of two
.It Sy size
The total size of this vdev
.It Sy free
The amount of remaining free space on this vdev
.It Sy allocated
The amount of allocated space on this vdev
.It Sy expandsize
How much this vdev can expand by
.It Sy fragmentation
Percent of fragmentation in this vdev
.It Sy parity
The level of parity for this vdev
.It Sy failure_domain
Failure domain id of this child vdev in
.Sy dRAID
vdev with failure domains feature
.It Sy failure_group
Failure group id of this child vdev in
.Sy dRAID
vdev with failure domains feature
.It Sy devid
The device id for this vdev
.It Sy physpath
The physical path to the device
.It Sy encpath
The enclosure path to the device
.It Sy fru
Field Replaceable Unit, usually a model number
.It Sy parent
Parent of this vdev
.It Sy children
Comma separated list of children of this vdev
.It Sy numchildren
The number of children belonging to this vdev
.It Sy read_errors , write_errors , checksum_errors , initialize_errors , trim_errors
The number of errors of each type encountered by this vdev
.It Sy slow_ios
This indicates the number of slow I/O operations encountered by this vdev.
A slow I/O is defined as an operation that did not complete within the
.Sy zio_slow_io_ms
threshold in milliseconds
.Pq Sy 30000 No by default .
For
.Sy RAIDZ
and
.Sy dRAID
configurations, this value also represents the number of times the vdev was
identified as an outlier and excluded from participating in read I/O operations.
.It Sy null_ops , read_ops , write_ops , free_ops , claim_ops , trim_ops
The number of I/O operations of each type performed by this vdev
.It Xo
.Sy null_bytes , read_bytes , write_bytes , free_bytes , claim_bytes ,
.Sy trim_bytes
.Xc
The cumulative size of all operations of each type performed by this vdev
.It Sy removing
If this device is currently being removed from the pool
.It Sy raidz_expanding
Set while a
.Nm zpool Cm attach
expansion is in progress on this RAID-Z vdev; cleared on completion.
See
.Xr zpool-attach 8 .
.It Sy trim_support
Indicates if a leaf device supports trim operations.
.El
.Pp
The following native properties can be used to change the behavior of a vdev.
.Bl -tag -width "allocating"
.It Sy checksum_n , checksum_t , io_n , io_t , slow_io_n , slow_io_t
Tune the fault management daemon by specifying checksum/io thresholds of <N>
errors in <T> seconds, respectively.
These properties can be set on leaf and top-level vdevs.
When the property is set on the leaf and top-level vdev, the value of the leaf
vdev will be used.
If the property is only set on the top-level vdev, this value will be used.
The value of these properties do not persist across vdev replacement.
For this reason, it is advisable to set the property on the top-level vdev -
not on the leaf vdev itself.
The
.Sy slow_io_n
and
.Sy slow_io_t
properties must be manually set to enable slow I/O diagnosis;
there are no built-in defaults.
The default values for
.Sy checksum_n , checksum_t , io_n ,
and
.Sy io_t
on
.Sy OpenZFS on Linux
are 10 errors in 600 seconds.
For
.Sy OpenZFS on FreeBSD
defaults see
.Xr zfsd 8 .
The
.It Sy slow_io_events
property controls whether slow I/O events are generated.
Even when disabled, slow I/Os will be included in the
.Nm zpool Cm status Fl s
output.
.It Sy comment
A text comment up to 8192 characters long
.It Sy bootsize
The amount of space to reserve for the EFI system partition
.It Sy failfast
If this device should propagate BIO errors back to ZFS, used to disable
failfast.
.It Sy sit_out
Only valid for
.Sy RAIDZ
and
.Sy dRAID
vdevs.
True when a slow disk outlier was detected and the vdev is currently in a sit
out state.
This property can be manually set to cause vdevs to sit out.
It will also be automatically set by the
.Sy autosit
logic if that is enabled.
While sitting out, the vdev will not participate in normal reads, instead its
data will be reconstructed as needed from parity.
.It Sy autosit
Only valid for
.Sy RAIDZ
and
.Sy dRAID
vdevs.
If set, this enables the kernel-level slow disk detection logic.
This logic automatically causes any vdevs that are significant negative
performance outliers to sit out, as described in the
.Sy sit_out
property.
.It Sy path
The path to the device for this vdev
.It Sy allocating
If this device should perform new allocations, used to disable a device
when it is scheduled for later removal.
See
.Xr zpool-remove 8 .
.It Sy alloc_bias Ns = Ns Sy none Ns | Ns Sy log Ns | Ns Sy special Ns | Ns Sy dedup
Controls the allocation class for a top-level vdev.
Changes take effect after an export and import of the pool.
Changing to/from log is not implemented, since it may lead to data loss in
case of the log device failure.
Setting to
.Sy special
and
.Sy dedup
requires
.Sy feature@allocation_classes
to be enabled.
At least one top-level vdev must remain in the normal
.Pq Sy none
class.
.It Sy scheduler Ns = Ns Sy auto Ns | Ns Sy on Ns | Ns Sy off
Controls how I/O requests are added to the vdev queue when reading or
writing to this vdev.
This property can be set on leaf vdevs.
The value of these properties do not persist across vdev replacement.
.Bl -tag -compact -width "auto"
.It Ar auto
Let ZFS choose which scheduler it thinks will be best.
Currently, the scheduler will queue I/O if the vdev is backed by a rotational
block device or file, and not queue otherwise.
.It Ar on
Always adds I/O requests to the vdev queue.
.It Ar off
Never adds I/O requests to the vdev queue.
This is not recommended for vdevs backed by spinning disks as it could
result in starvation.
.El
.El
.Ss User Properties
In addition to the standard native properties, ZFS supports arbitrary user
properties.
User properties have no effect on ZFS behavior, but applications or
administrators can use them to annotate vdevs.
.Pp
User property names must contain a colon
.Pq Qq Sy \&:
character to distinguish them from native properties.
They may contain lowercase letters, numbers, and the following punctuation
characters: colon
.Pq Qq Sy \&: ,
dash
.Pq Qq Sy - ,
period
.Pq Qq Sy \&. ,
and underscore
.Pq Qq Sy _ .
The expected convention is that the property name is divided into two portions
such as
.Ar module : Ns Ar property ,
but this namespace is not enforced by ZFS.
User property names can be at most 256 characters, and cannot begin with a dash
.Pq Qq Sy - .
.Pp
When making programmatic use of user properties, it is strongly suggested to use
a reversed DNS domain name for the
.Ar module
component of property names to reduce the chance that two
independently-developed packages use the same property name for different
purposes.
.Pp
The values of user properties are arbitrary strings and
are never validated.
Use the
.Nm zpool Cm set
command with a blank value to clear a user property.
Property values are limited to 8192 bytes.
.Sh SEE ALSO
.Xr zpoolprops 7 ,
.Xr zpool-set 8