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 http://www.opensolaris.org/os/licensing. 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 November 27, 2021 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. 47.Pp 48The values of numeric properties can be specified using human-readable suffixes 49.Po for example, 50.Sy k , KB , M , Gb , 51and so forth, up to 52.Sy Z 53for zettabyte 54.Pc . 55The following are all valid 56.Pq and equal 57specifications: 58.Li 1536M , 1.5g , 1.50GB . 59.Pp 60The values of non-numeric properties are case sensitive and must be lowercase. 61.Pp 62The following native properties consist of read-only statistics about the 63vdev. 64These properties can not be changed. 65.Bl -tag -width "fragmentation" 66.It Sy capacity 67Percentage of vdev space used 68.It Sy state 69state of this vdev such as online, faulted, or offline 70.It Sy guid 71globaly unique id of this vdev 72.It Sy asize 73The allocable size of this vdev 74.It Sy psize 75The physical size of this vdev 76.It Sy ashift 77The physical sector size of this vdev expressed as the power of two 78.It Sy size 79The total size of this vdev 80.It Sy free 81The amount of remaining free space on this vdev 82.It Sy allocated 83The amount of allocated space on this vdev 84.It Sy expandsize 85How much this vdev can expand by 86.It Sy fragmentation 87Percent of fragmentation in this vdev 88.It Sy parity 89The level of parity for this vdev 90.It Sy devid 91The device id for this vdev 92.It Sy physpath 93The physical path to the device 94.It Sy encpath 95The enclosure path to the device 96.It Sy fru 97Field Replacable Unit, usually a model number 98.It Sy parent 99Parent of this vdev 100.It Sy children 101Comma separated list of children of this vdev 102.It Sy numchildren 103The number of children belonging to this vdev 104.It Sy read_errors , write_errors , checksum_errors , initialize_errors 105The number of errors of each type encountered by this vdev 106.It Sy null_ops , read_ops , write_ops , free_ops , claim_ops , trim_ops 107The number of I/O operations of each type performed by this vdev 108.It Xo 109.Sy null_bytes , read_bytes , write_bytes , free_bytes , claim_bytes , 110.Sy trim_bytes 111.Xc 112The cumulative size of all operations of each type performed by this vdev 113.It Sy removing 114If this device is currently being removed from the pool 115.El 116.Pp 117The following native properties can be used to change the behavior of a ZFS 118dataset. 119.Bl -tag -width "allocating" 120.It Sy comment 121A text comment up to 8192 characters long 122.It Sy bootsize 123The amount of space to reserve for the EFI system partition 124.It Sy path 125The path to the device for this vdev 126.It Sy allocating 127If this device should perform new allocations, used to disable a device 128when it is scheduled for later removal. 129See 130.Xr zpool-remove 8 . 131.El 132.Ss User Properties 133In addition to the standard native properties, ZFS supports arbitrary user 134properties. 135User properties have no effect on ZFS behavior, but applications or 136administrators can use them to annotate vdevs. 137.Pp 138User property names must contain a colon 139.Pq Qq Sy \&: 140character to distinguish them from native properties. 141They may contain lowercase letters, numbers, and the following punctuation 142characters: colon 143.Pq Qq Sy \&: , 144dash 145.Pq Qq Sy - , 146period 147.Pq Qq Sy \&. , 148and underscore 149.Pq Qq Sy _ . 150The expected convention is that the property name is divided into two portions 151such as 152.Ar module : Ns Ar property , 153but this namespace is not enforced by ZFS. 154User property names can be at most 256 characters, and cannot begin with a dash 155.Pq Qq Sy - . 156.Pp 157When making programmatic use of user properties, it is strongly suggested to use 158a reversed DNS domain name for the 159.Ar module 160component of property names to reduce the chance that two 161independently-developed packages use the same property name for different 162purposes. 163.Pp 164The values of user properties are arbitrary strings and 165are never validated. 166Use the 167.Nm zpool Cm set 168command with a blank value to clear a user property. 169Property values are limited to 8192 bytes. 170.Sh SEE ALSO 171.Xr zpoolprops 7 , 172.Xr zpool-set 8 173