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 106The number of errors of each type encountered by this vdev 107.It Sy null_ops , read_ops , write_ops , free_ops , claim_ops , trim_ops 108The number of I/O operations of each type performed by this vdev 109.It Xo 110.Sy null_bytes , read_bytes , write_bytes , free_bytes , claim_bytes , 111.Sy trim_bytes 112.Xc 113The cumulative size of all operations of each type performed by this vdev 114.It Sy removing 115If this device is currently being removed from the pool 116.El 117.Pp 118The following native properties can be used to change the behavior of a vdev. 119.Bl -tag -width "allocating" 120.It Sy checksum_n , checksum_t , io_n , io_t , slow_io_n , slow_io_t 121Tune the fault management daemon by specifying checksum/io thresholds of <N> 122errors in <T> seconds, respectively. 123These properties can be set on leaf and top-level vdevs. 124When the property is set on the leaf and top-level vdev, the value of the leaf 125vdev will be used. 126If the property is only set on the top-level vdev, this value will be used. 127The value of these properties do not persist across vdev replacement. 128For this reason, it is advisable to set the property on the top-level vdev - 129not on the leaf vdev itself. 130The default values for 131.Sy OpenZFS on Linux 132are 10 errors in 600 seconds. 133For 134.Sy OpenZFS on FreeBSD 135defaults see 136.Xr zfsd 8 . 137.It Sy comment 138A text comment up to 8192 characters long 139.It Sy bootsize 140The amount of space to reserve for the EFI system partition 141.It Sy failfast 142If this device should propage BIO errors back to ZFS, used to disable 143failfast. 144.It Sy path 145The path to the device for this vdev 146.It Sy allocating 147If this device should perform new allocations, used to disable a device 148when it is scheduled for later removal. 149See 150.Xr zpool-remove 8 . 151.El 152.Ss User Properties 153In addition to the standard native properties, ZFS supports arbitrary user 154properties. 155User properties have no effect on ZFS behavior, but applications or 156administrators can use them to annotate vdevs. 157.Pp 158User property names must contain a colon 159.Pq Qq Sy \&: 160character to distinguish them from native properties. 161They may contain lowercase letters, numbers, and the following punctuation 162characters: colon 163.Pq Qq Sy \&: , 164dash 165.Pq Qq Sy - , 166period 167.Pq Qq Sy \&. , 168and underscore 169.Pq Qq Sy _ . 170The expected convention is that the property name is divided into two portions 171such as 172.Ar module : Ns Ar property , 173but this namespace is not enforced by ZFS. 174User property names can be at most 256 characters, and cannot begin with a dash 175.Pq Qq Sy - . 176.Pp 177When making programmatic use of user properties, it is strongly suggested to use 178a reversed DNS domain name for the 179.Ar module 180component of property names to reduce the chance that two 181independently-developed packages use the same property name for different 182purposes. 183.Pp 184The values of user properties are arbitrary strings and 185are never validated. 186Use the 187.Nm zpool Cm set 188command with a blank value to clear a user property. 189Property values are limited to 8192 bytes. 190.Sh SEE ALSO 191.Xr zpoolprops 7 , 192.Xr zpool-set 8 193