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