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