]>
Commit | Line | Data |
---|---|---|
9ae529ec | 1 | '\" te |
93cf2076 | 2 | .\" Copyright (c) 2013 by Delphix. All rights reserved. |
9759c60f | 3 | .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. |
9ae529ec CS |
4 | .\" The contents of this file are subject to the terms of the Common Development |
5 | .\" and Distribution License (the "License"). You may not use this file except | |
6 | .\" in compliance with the License. You can obtain a copy of the license at | |
7 | .\" usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. | |
8 | .\" | |
9 | .\" See the License for the specific language governing permissions and | |
10 | .\" limitations under the License. When distributing Covered Code, include this | |
11 | .\" CDDL HEADER in each file and include the License file at | |
12 | .\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this | |
13 | .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your | |
14 | .\" own identifying information: | |
15 | .\" Portions Copyright [yyyy] [name of copyright owner] | |
93cf2076 | 16 | .TH ZPOOL-FEATURES 5 "Aug 27, 2013" |
9ae529ec CS |
17 | .SH NAME |
18 | zpool\-features \- ZFS pool feature descriptions | |
19 | .SH DESCRIPTION | |
20 | .sp | |
21 | .LP | |
22 | ZFS pool on\-disk format versions are specified via "features" which replace | |
23 | the old on\-disk format numbers (the last supported on\-disk format number is | |
b9b24bb4 | 24 | 28). To enable a feature on a pool use the \fBupgrade\fR subcommand of the |
a3177028 | 25 | \fBzpool\fR(8) command, or set the \fBfeature@\fR\fIfeature_name\fR property |
b9b24bb4 | 26 | to \fBenabled\fR. |
9ae529ec CS |
27 | .sp |
28 | .LP | |
29 | The pool format does not affect file system version compatibility or the ability | |
30 | to send file systems between pools. | |
31 | .sp | |
32 | .LP | |
33 | Since most features can be enabled independently of each other the on\-disk | |
34 | format of the pool is specified by the set of all features marked as | |
35 | \fBactive\fR on the pool. If the pool was created by another software version | |
36 | this set may include unsupported features. | |
37 | .SS "Identifying features" | |
38 | .sp | |
39 | .LP | |
40 | Every feature has a guid of the form \fIcom.example:feature_name\fR. The reverse | |
41 | DNS name ensures that the feature's guid is unique across all ZFS | |
42 | implementations. When unsupported features are encountered on a pool they will | |
43 | be identified by their guids. Refer to the documentation for the ZFS | |
44 | implementation that created the pool for information about those features. | |
45 | .sp | |
46 | .LP | |
47 | Each supported feature also has a short name. By convention a feature's short | |
48 | name is the portion of its guid which follows the ':' (e.g. | |
49 | \fIcom.example:feature_name\fR would have the short name \fIfeature_name\fR), | |
50 | however a feature's short name may differ across ZFS implementations if | |
51 | following the convention would result in name conflicts. | |
52 | .SS "Feature states" | |
53 | .sp | |
54 | .LP | |
55 | Features can be in one of three states: | |
56 | .sp | |
57 | .ne 2 | |
58 | .na | |
59 | \fB\fBactive\fR\fR | |
60 | .ad | |
61 | .RS 12n | |
62 | This feature's on\-disk format changes are in effect on the pool. Support for | |
63 | this feature is required to import the pool in read\-write mode. If this | |
64 | feature is not read-only compatible, support is also required to import the pool | |
65 | in read\-only mode (see "Read\-only compatibility"). | |
66 | .RE | |
67 | ||
68 | .sp | |
69 | .ne 2 | |
70 | .na | |
71 | \fB\fBenabled\fR\fR | |
72 | .ad | |
73 | .RS 12n | |
74 | An administrator has marked this feature as enabled on the pool, but the | |
75 | feature's on\-disk format changes have not been made yet. The pool can still be | |
76 | imported by software that does not support this feature, but changes may be made | |
77 | to the on\-disk format at any time which will move the feature to the | |
78 | \fBactive\fR state. Some features may support returning to the \fBenabled\fR | |
79 | state after becoming \fBactive\fR. See feature\-specific documentation for | |
80 | details. | |
81 | .RE | |
82 | ||
83 | .sp | |
84 | .ne 2 | |
85 | .na | |
86 | \fBdisabled\fR | |
87 | .ad | |
88 | .RS 12n | |
89 | This feature's on\-disk format changes have not been made and will not be made | |
90 | unless an administrator moves the feature to the \fBenabled\fR state. Features | |
91 | cannot be disabled once they have been enabled. | |
92 | .RE | |
93 | ||
94 | .sp | |
95 | .LP | |
96 | The state of supported features is exposed through pool properties of the form | |
97 | \fIfeature@short_name\fR. | |
98 | .SS "Read\-only compatibility" | |
99 | .sp | |
100 | .LP | |
101 | Some features may make on\-disk format changes that do not interfere with other | |
102 | software's ability to read from the pool. These features are referred to as | |
103 | "read\-only compatible". If all unsupported features on a pool are read\-only | |
104 | compatible, the pool can be imported in read\-only mode by setting the | |
a3177028 | 105 | \fBreadonly\fR property during import (see \fBzpool\fR(8) for details on |
9ae529ec CS |
106 | importing pools). |
107 | .SS "Unsupported features" | |
108 | .sp | |
109 | .LP | |
110 | For each unsupported feature enabled on an imported pool a pool property | |
111 | named \fIunsupported@feature_guid\fR will indicate why the import was allowed | |
112 | despite the unsupported feature. Possible values for this property are: | |
113 | ||
114 | .sp | |
115 | .ne 2 | |
116 | .na | |
117 | \fB\fBinactive\fR\fR | |
118 | .ad | |
119 | .RS 12n | |
120 | The feature is in the \fBenabled\fR state and therefore the pool's on\-disk | |
121 | format is still compatible with software that does not support this feature. | |
122 | .RE | |
123 | ||
124 | .sp | |
125 | .ne 2 | |
126 | .na | |
127 | \fB\fBreadonly\fR\fR | |
128 | .ad | |
129 | .RS 12n | |
130 | The feature is read\-only compatible and the pool has been imported in | |
131 | read\-only mode. | |
132 | .RE | |
133 | ||
134 | .SS "Feature dependencies" | |
135 | .sp | |
136 | .LP | |
137 | Some features depend on other features being enabled in order to function | |
138 | properly. Enabling a feature will automatically enable any features it | |
139 | depends on. | |
140 | .SH FEATURES | |
141 | .sp | |
142 | .LP | |
143 | The following features are supported on this system: | |
144 | .sp | |
145 | .ne 2 | |
146 | .na | |
147 | \fB\fBasync_destroy\fR\fR | |
148 | .ad | |
149 | .RS 4n | |
150 | .TS | |
151 | l l . | |
152 | GUID com.delphix:async_destroy | |
153 | READ\-ONLY COMPATIBLE yes | |
154 | DEPENDENCIES none | |
155 | .TE | |
156 | ||
157 | Destroying a file system requires traversing all of its data in order to | |
158 | return its used space to the pool. Without \fBasync_destroy\fR the file system | |
159 | is not fully removed until all space has been reclaimed. If the destroy | |
160 | operation is interrupted by a reboot or power outage the next attempt to open | |
161 | the pool will need to complete the destroy operation synchronously. | |
162 | ||
163 | When \fBasync_destroy\fR is enabled the file system's data will be reclaimed | |
164 | by a background process, allowing the destroy operation to complete without | |
165 | traversing the entire file system. The background process is able to resume | |
166 | interrupted destroys after the pool has been opened, eliminating the need | |
167 | to finish interrupted destroys as part of the open operation. The amount | |
168 | of space remaining to be reclaimed by the background process is available | |
169 | through the \fBfreeing\fR property. | |
170 | ||
171 | This feature is only \fBactive\fR while \fBfreeing\fR is non\-zero. | |
172 | .RE | |
753c3839 MA |
173 | |
174 | .sp | |
175 | .ne 2 | |
176 | .na | |
177 | \fB\fBempty_bpobj\fR\fR | |
178 | .ad | |
179 | .RS 4n | |
180 | .TS | |
181 | l l . | |
182 | GUID com.delphix:empty_bpobj | |
183 | READ\-ONLY COMPATIBLE yes | |
184 | DEPENDENCIES none | |
185 | .TE | |
186 | ||
187 | This feature increases the performance of creating and using a large | |
188 | number of snapshots of a single filesystem or volume, and also reduces | |
189 | the disk space required. | |
190 | ||
191 | When there are many snapshots, each snapshot uses many Block Pointer | |
192 | Objects (bpobj's) to track blocks associated with that snapshot. | |
193 | However, in common use cases, most of these bpobj's are empty. This | |
194 | feature allows us to create each bpobj on-demand, thus eliminating the | |
195 | empty bpobjs. | |
196 | ||
197 | This feature is \fBactive\fR while there are any filesystems, volumes, | |
198 | or snapshots which were created after enabling this feature. | |
199 | .RE | |
200 | ||
9759c60f ED |
201 | .sp |
202 | .ne 2 | |
203 | .na | |
204 | \fB\fBlz4_compress\fR\fR | |
205 | .ad | |
206 | .RS 4n | |
207 | .TS | |
208 | l l . | |
209 | GUID org.illumos:lz4_compress | |
210 | READ\-ONLY COMPATIBLE no | |
211 | DEPENDENCIES none | |
212 | .TE | |
213 | ||
214 | \fBlz4\fR is a high-performance real-time compression algorithm that | |
215 | features significantly faster compression and decompression as well as a | |
216 | higher compression ratio than the older \fBlzjb\fR compression. | |
217 | Typically, \fBlz4\fR compression is approximately 50% faster on | |
218 | compressible data and 200% faster on incompressible data than | |
219 | \fBlzjb\fR. It is also approximately 80% faster on decompression, while | |
220 | giving approximately 10% better compression ratio. | |
221 | ||
222 | When the \fBlz4_compress\fR feature is set to \fBenabled\fR, the | |
223 | administrator can turn on \fBlz4\fR compression on any dataset on the | |
a3177028 | 224 | pool using the \fBzfs\fR(8) command. Please note that doing so will |
9759c60f | 225 | immediately activate the \fBlz4_compress\fR feature on the underlying |
62bdd5eb DL |
226 | pool using the \fBzfs\fR(1M) command. Also, all newly written metadata |
227 | will be compressed with \fBlz4\fR algorithm. Since this feature is not | |
228 | read-only compatible, this operation will render the pool unimportable | |
229 | on systems without support for the \fBlz4_compress\fR feature. Booting | |
230 | off of \fBlz4\fR-compressed root pools is supported. | |
231 | ||
232 | This feature becomes \fBactive\fR as soon as it is enabled and will | |
233 | never return to being \fBenabled\fB. | |
93cf2076 GW |
234 | .RE |
235 | ||
236 | .sp | |
237 | .ne 2 | |
238 | .na | |
239 | \fB\fBspacemap_histogram\fR\fR | |
240 | .ad | |
241 | .RS 4n | |
242 | .TS | |
243 | l l . | |
244 | GUID com.delphix:spacemap_histogram | |
245 | READ\-ONLY COMPATIBLE yes | |
246 | DEPENDENCIES none | |
247 | .TE | |
248 | ||
249 | This features allows ZFS to maintain more information about how free space | |
250 | is organized within the pool. If this feature is \fBenabled\fR, ZFS will | |
251 | set this feature to \fBactive\fR when a new space map object is created or | |
252 | an existing space map is upgraded to the new format. Once the feature is | |
253 | \fBactive\fR, it will remain in that state until the pool is destroyed. | |
9759c60f ED |
254 | |
255 | .RE | |
256 | ||
fa86b5db MA |
257 | .sp |
258 | .ne 2 | |
259 | .na | |
260 | \fB\fBextensible_dataset\fR\fR | |
261 | .ad | |
262 | .RS 4n | |
263 | .TS | |
264 | l l . | |
265 | GUID com.delphix:extensible_dataset | |
266 | READ\-ONLY COMPATIBLE no | |
267 | DEPENDENCIES none | |
268 | .TE | |
269 | ||
270 | This feature allows more flexible use of internal ZFS data structures, | |
271 | and exists for other features to depend on. | |
272 | ||
273 | This feature will be \fBactive\fR when the first dependent feature uses it, | |
274 | and will be returned to the \fBenabled\fR state when all datasets that use | |
275 | this feature are destroyed. | |
276 | ||
277 | .RE | |
278 | ||
da536844 MA |
279 | .sp |
280 | .ne 2 | |
281 | .na | |
282 | \fB\fBbookmarks\fR\fR | |
283 | .ad | |
284 | .RS 4n | |
285 | .TS | |
286 | l l . | |
287 | GUID com.delphix:bookmarks | |
288 | READ\-ONLY COMPATIBLE yes | |
289 | DEPENDENCIES extensible_dataset | |
290 | .TE | |
291 | ||
292 | This feature enables use of the \fBzfs bookmark\fR subcommand. | |
293 | ||
294 | This feature is \fBactive\fR while any bookmarks exist in the pool. | |
295 | All bookmarks in the pool can be listed by running | |
296 | \fBzfs list -t bookmark -r \fIpoolname\fR\fR. | |
297 | ||
298 | .RE | |
299 | ||
b0bc7a84 MG |
300 | .sp |
301 | .ne 2 | |
302 | .na | |
303 | \fB\fBenabled_txg\fR\fR | |
304 | .ad | |
305 | .RS 4n | |
306 | .TS | |
307 | l l . | |
308 | GUID com.delphix:enabled_txg | |
309 | READ\-ONLY COMPATIBLE yes | |
310 | DEPENDENCIES none | |
311 | .TE | |
312 | ||
313 | Once this feature is enabled ZFS records the transaction group number | |
314 | in which new features are enabled. This has no user-visible impact, | |
315 | but other features may depend on this feature. | |
316 | ||
317 | This feature becomes \fBactive\fR as soon as it is enabled and will | |
318 | never return to being \fBenabled\fB. | |
319 | ||
320 | .RE | |
321 | ||
322 | .sp | |
323 | .ne 2 | |
324 | .na | |
325 | \fB\fBhole_birth\fR\fR | |
326 | .ad | |
327 | .RS 4n | |
328 | .TS | |
329 | l l . | |
330 | GUID com.delphix:hole_birth | |
331 | READ\-ONLY COMPATIBLE no | |
332 | DEPENDENCIES enabled_txg | |
333 | .TE | |
334 | ||
335 | This feature improves performance of incremental sends ("zfs send -i") | |
336 | and receives for objects with many holes. The most common case of | |
337 | hole-filled objects is zvols. | |
338 | ||
339 | An incremental send stream from snapshot \fBA\fR to snapshot \fBB\fR | |
340 | contains information about every block that changed between \fBA\fR and | |
341 | \fBB\fR. Blocks which did not change between those snapshots can be | |
342 | identified and omitted from the stream using a piece of metadata called | |
343 | the 'block birth time', but birth times are not recorded for holes (blocks | |
344 | filled only with zeroes). Since holes created after \fBA\fR cannot be | |
345 | distinguished from holes created before \fBA\fR, information about every | |
346 | hole in the entire filesystem or zvol is included in the send stream. | |
347 | ||
348 | For workloads where holes are rare this is not a problem. However, when | |
349 | incrementally replicating filesystems or zvols with many holes (for | |
350 | example a zvol formatted with another filesystem) a lot of time will | |
351 | be spent sending and receiving unnecessary information about holes that | |
352 | already exist on the receiving side. | |
353 | ||
354 | Once the \fBhole_birth\fR feature has been enabled the block birth times | |
355 | of all new holes will be recorded. Incremental sends between snapshots | |
356 | created after this feature is enabled will use this new metadata to avoid | |
357 | sending information about holes that already exist on the receiving side. | |
358 | ||
359 | This feature becomes \fBactive\fR as soon as it is enabled and will | |
360 | never return to being \fBenabled\fB. | |
361 | ||
362 | .RE | |
363 | ||
9b67f605 MA |
364 | .sp |
365 | .ne 2 | |
366 | .na | |
367 | \fB\fBembedded_data\fR\fR | |
368 | .ad | |
369 | .RS 4n | |
370 | .TS | |
371 | l l . | |
372 | GUID com.delphix:embedded_data | |
373 | READ\-ONLY COMPATIBLE no | |
374 | DEPENDENCIES none | |
375 | .TE | |
376 | ||
377 | This feature improves the performance and compression ratio of | |
378 | highly-compressible blocks. Blocks whose contents can compress to 112 bytes | |
379 | or smaller can take advantage of this feature. | |
380 | ||
381 | When this feature is enabled, the contents of highly-compressible blocks are | |
382 | stored in the block "pointer" itself (a misnomer in this case, as it contains | |
383 | the compresseed data, rather than a pointer to its location on disk). Thus | |
384 | the space of the block (one sector, typically 512 bytes or 4KB) is saved, | |
385 | and no additional i/o is needed to read and write the data block. | |
386 | ||
387 | This feature becomes \fBactive\fR as soon as it is enabled and will | |
388 | never return to being \fBenabled\fR. | |
389 | ||
390 | .RE | |
b0bc7a84 | 391 | |
9ae529ec | 392 | .SH "SEE ALSO" |
a3177028 | 393 | \fBzpool\fR(8) |