]>
Commit | Line | Data |
---|---|---|
9ae529ec CS |
1 | '\" te |
2 | .\" Copyright (c) 2012 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] | |
a3177028 | 16 | .TH ZPOOL-FEATURES 5 "Feb 4, 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 ED |
225 | immediately activate the \fBlz4_compress\fR feature on the underlying |
226 | pool (even before any data is written). Since this feature is not | |
227 | read-only compatible, this operation will render the pool unimportable | |
228 | on systems without support for the \fBlz4_compress\fR feature. At the | |
229 | moment, this operation cannot be reversed. Booting off of | |
230 | \fBlz4\fR-compressed root pools is supported. | |
231 | ||
232 | .RE | |
233 | ||
9ae529ec | 234 | .SH "SEE ALSO" |
a3177028 | 235 | \fBzpool\fR(8) |