1.\" SPDX-License-Identifier: CDDL-1.0 2.\" 3.\" CDDL HEADER START 4.\" 5.\" The contents of this file are subject to the terms of the 6.\" Common Development and Distribution License (the "License"). 7.\" You may not use this file except in compliance with the License. 8.\" 9.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10.\" or https://opensource.org/licenses/CDDL-1.0. 11.\" See the License for the specific language governing permissions 12.\" and limitations under the License. 13.\" 14.\" When distributing Covered Code, include this CDDL HEADER in each 15.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16.\" If applicable, add the following below this CDDL HEADER, with the 17.\" fields enclosed by brackets "[]" replaced with your own identifying 18.\" information: Portions Copyright [yyyy] [name of copyright owner] 19.\" 20.\" CDDL HEADER END 21.\" 22.\" Copyright (c) 2021, 2025, Klara, Inc. 23.\" 24.Dd July 23, 2024 25.Dt VDEVPROPS 7 26.Os 27. 28.Sh NAME 29.Nm vdevprops 30.Nd native and user-defined properties of ZFS vdevs 31. 32.Sh DESCRIPTION 33Properties are divided into two types, native properties and user-defined 34.Pq or Qq user 35properties. 36Native properties either export internal statistics or control ZFS behavior. 37In addition, native properties are either editable or read-only. 38User properties have no effect on ZFS behavior, but you can use them to annotate 39vdevs in a way that is meaningful in your environment. 40For more information about user properties, see the 41.Sx User Properties 42section, below. 43. 44.Ss Native Properties 45Every vdev has a set of properties that export statistics about the vdev 46as well as control various behaviors. 47Properties are not inherited from top-level vdevs, with the exception of 48checksum_n, checksum_t, io_n, io_t, slow_io_n, and slow_io_t. 49.Pp 50The values of numeric properties can be specified using human-readable suffixes 51.Po for example, 52.Sy k , KB , M , Gb , 53and so forth, up to 54.Sy Z 55for zettabyte 56.Pc . 57The following are all valid 58.Pq and equal 59specifications: 60.Li 1536M , 1.5g , 1.50GB . 61.Pp 62The values of non-numeric properties are case sensitive and must be lowercase. 63.Pp 64The following native properties consist of read-only statistics about the 65vdev. 66These properties can not be changed. 67.Bl -tag -width "fragmentation" 68.It Sy capacity 69Percentage of vdev space used 70.It Sy state 71state of this vdev such as online, faulted, or offline 72.It Sy guid 73globally unique id of this vdev 74.It Sy asize 75The allocatable size of this vdev 76.It Sy psize 77The physical size of this vdev 78.It Sy ashift 79The physical sector size of this vdev expressed as the power of two 80.It Sy size 81The total size of this vdev 82.It Sy free 83The amount of remaining free space on this vdev 84.It Sy allocated 85The amount of allocated space on this vdev 86.It Sy expandsize 87How much this vdev can expand by 88.It Sy fragmentation 89Percent of fragmentation in this vdev 90.It Sy parity 91The level of parity for this vdev 92.It Sy devid 93The device id for this vdev 94.It Sy physpath 95The physical path to the device 96.It Sy encpath 97The enclosure path to the device 98.It Sy fru 99Field Replaceable Unit, usually a model number 100.It Sy parent 101Parent of this vdev 102.It Sy children 103Comma separated list of children of this vdev 104.It Sy numchildren 105The number of children belonging to this vdev 106.It Sy read_errors , write_errors , checksum_errors , initialize_errors , trim_errors 107The number of errors of each type encountered by this vdev 108.It Sy slow_ios 109This indicates the number of slow I/O operations encountered by this vdev. 110A slow I/O is defined as an operation that did not complete within the 111.Sy zio_slow_io_ms 112threshold in milliseconds 113.Pq Sy 30000 No by default . 114For 115.Sy RAIDZ 116and 117.Sy DRAID 118configurations, this value also represents the number of times the vdev was 119identified as an outlier and excluded from participating in read I/O operations. 120.It Sy null_ops , read_ops , write_ops , free_ops , claim_ops , trim_ops 121The number of I/O operations of each type performed by this vdev 122.It Xo 123.Sy null_bytes , read_bytes , write_bytes , free_bytes , claim_bytes , 124.Sy trim_bytes 125.Xc 126The cumulative size of all operations of each type performed by this vdev 127.It Sy removing 128If this device is currently being removed from the pool 129.It Sy trim_support 130Indicates if a leaf device supports trim operations. 131.El 132.Pp 133The following native properties can be used to change the behavior of a vdev. 134.Bl -tag -width "allocating" 135.It Sy checksum_n , checksum_t , io_n , io_t , slow_io_n , slow_io_t 136Tune the fault management daemon by specifying checksum/io thresholds of <N> 137errors in <T> seconds, respectively. 138These properties can be set on leaf and top-level vdevs. 139When the property is set on the leaf and top-level vdev, the value of the leaf 140vdev will be used. 141If the property is only set on the top-level vdev, this value will be used. 142The value of these properties do not persist across vdev replacement. 143For this reason, it is advisable to set the property on the top-level vdev - 144not on the leaf vdev itself. 145The default values for 146.Sy OpenZFS on Linux 147are 10 errors in 600 seconds. 148For 149.Sy OpenZFS on FreeBSD 150defaults see 151.Xr zfsd 8 . 152.It Sy comment 153A text comment up to 8192 characters long 154.It Sy bootsize 155The amount of space to reserve for the EFI system partition 156.It Sy failfast 157If this device should propagate BIO errors back to ZFS, used to disable 158failfast. 159.It Sy sit_out 160Only valid for 161.Sy RAIDZ 162and 163.Sy DRAID 164vdevs. 165True when a slow disk outlier was detected and the vdev is currently in a sit 166out state. 167This property can be manually set to cause vdevs to sit out. 168It will also be automatically set by the 169.Sy autosit 170logic if that is enabled. 171While sitting out, the vdev will not participate in normal reads, instead its 172data will be reconstructed as needed from parity. 173.It Sy autosit 174Only valid for 175.Sy RAIDZ 176and 177.Sy DRAID 178vdevs. 179If set, this enables the kernel-level slow disk detection logic. 180This logic automatically causes any vdevs that are significant negative 181performance outliers to sit out, as described in the 182.Sy sit_out 183property. 184.It Sy path 185The path to the device for this vdev 186.It Sy allocating 187If this device should perform new allocations, used to disable a device 188when it is scheduled for later removal. 189See 190.Xr zpool-remove 8 . 191.El 192.Ss User Properties 193In addition to the standard native properties, ZFS supports arbitrary user 194properties. 195User properties have no effect on ZFS behavior, but applications or 196administrators can use them to annotate vdevs. 197.Pp 198User property names must contain a colon 199.Pq Qq Sy \&: 200character to distinguish them from native properties. 201They may contain lowercase letters, numbers, and the following punctuation 202characters: colon 203.Pq Qq Sy \&: , 204dash 205.Pq Qq Sy - , 206period 207.Pq Qq Sy \&. , 208and underscore 209.Pq Qq Sy _ . 210The expected convention is that the property name is divided into two portions 211such as 212.Ar module : Ns Ar property , 213but this namespace is not enforced by ZFS. 214User property names can be at most 256 characters, and cannot begin with a dash 215.Pq Qq Sy - . 216.Pp 217When making programmatic use of user properties, it is strongly suggested to use 218a reversed DNS domain name for the 219.Ar module 220component of property names to reduce the chance that two 221independently-developed packages use the same property name for different 222purposes. 223.Pp 224The values of user properties are arbitrary strings and 225are never validated. 226Use the 227.Nm zpool Cm set 228command with a blank value to clear a user property. 229Property values are limited to 8192 bytes. 230.Sh SEE ALSO 231.Xr zpoolprops 7 , 232.Xr zpool-set 8 233