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