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