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, and 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 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 are 10 errors in 600 seconds. 131.It Sy comment 132A text comment up to 8192 characters long 133.It Sy bootsize 134The amount of space to reserve for the EFI system partition 135.It Sy failfast 136If this device should propage BIO errors back to ZFS, used to disable 137failfast. 138.It Sy path 139The path to the device for this vdev 140.It Sy allocating 141If this device should perform new allocations, used to disable a device 142when it is scheduled for later removal. 143See 144.Xr zpool-remove 8 . 145.El 146.Ss User Properties 147In addition to the standard native properties, ZFS supports arbitrary user 148properties. 149User properties have no effect on ZFS behavior, but applications or 150administrators can use them to annotate vdevs. 151.Pp 152User property names must contain a colon 153.Pq Qq Sy \&: 154character to distinguish them from native properties. 155They may contain lowercase letters, numbers, and the following punctuation 156characters: colon 157.Pq Qq Sy \&: , 158dash 159.Pq Qq Sy - , 160period 161.Pq Qq Sy \&. , 162and underscore 163.Pq Qq Sy _ . 164The expected convention is that the property name is divided into two portions 165such as 166.Ar module : Ns Ar property , 167but this namespace is not enforced by ZFS. 168User property names can be at most 256 characters, and cannot begin with a dash 169.Pq Qq Sy - . 170.Pp 171When making programmatic use of user properties, it is strongly suggested to use 172a reversed DNS domain name for the 173.Ar module 174component of property names to reduce the chance that two 175independently-developed packages use the same property name for different 176purposes. 177.Pp 178The values of user properties are arbitrary strings and 179are never validated. 180Use the 181.Nm zpool Cm set 182command with a blank value to clear a user property. 183Property values are limited to 8192 bytes. 184.Sh SEE ALSO 185.Xr zpoolprops 7 , 186.Xr zpool-set 8 187