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