]>
Commit | Line | Data |
---|---|---|
9ae529ec CS |
1 | '\" te |
2 | .\" Copyright (c) 2012 by Delphix. All rights reserved. | |
3 | .\" The contents of this file are subject to the terms of the Common Development | |
4 | .\" and Distribution License (the "License"). You may not use this file except | |
5 | .\" in compliance with the License. You can obtain a copy of the license at | |
6 | .\" usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. | |
7 | .\" | |
8 | .\" See the License for the specific language governing permissions and | |
9 | .\" limitations under the License. When distributing Covered Code, include this | |
10 | .\" CDDL HEADER in each file and include the License file at | |
11 | .\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this | |
12 | .\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your | |
13 | .\" own identifying information: | |
14 | .\" Portions Copyright [yyyy] [name of copyright owner] | |
15 | .TH ZPOOL-FEATURES 5 "Mar 16, 2012" | |
16 | .SH NAME | |
17 | zpool\-features \- ZFS pool feature descriptions | |
18 | .SH DESCRIPTION | |
19 | .sp | |
20 | .LP | |
21 | ZFS pool on\-disk format versions are specified via "features" which replace | |
22 | the old on\-disk format numbers (the last supported on\-disk format number is | |
b9b24bb4 CS |
23 | 28). To enable a feature on a pool use the \fBupgrade\fR subcommand of the |
24 | \fBzpool\fR(1M) command, or set the \fBfeature@\fR\fIfeature_name\fR property | |
25 | to \fBenabled\fR. | |
9ae529ec CS |
26 | .sp |
27 | .LP | |
28 | The pool format does not affect file system version compatibility or the ability | |
29 | to send file systems between pools. | |
30 | .sp | |
31 | .LP | |
32 | Since most features can be enabled independently of each other the on\-disk | |
33 | format of the pool is specified by the set of all features marked as | |
34 | \fBactive\fR on the pool. If the pool was created by another software version | |
35 | this set may include unsupported features. | |
36 | .SS "Identifying features" | |
37 | .sp | |
38 | .LP | |
39 | Every feature has a guid of the form \fIcom.example:feature_name\fR. The reverse | |
40 | DNS name ensures that the feature's guid is unique across all ZFS | |
41 | implementations. When unsupported features are encountered on a pool they will | |
42 | be identified by their guids. Refer to the documentation for the ZFS | |
43 | implementation that created the pool for information about those features. | |
44 | .sp | |
45 | .LP | |
46 | Each supported feature also has a short name. By convention a feature's short | |
47 | name is the portion of its guid which follows the ':' (e.g. | |
48 | \fIcom.example:feature_name\fR would have the short name \fIfeature_name\fR), | |
49 | however a feature's short name may differ across ZFS implementations if | |
50 | following the convention would result in name conflicts. | |
51 | .SS "Feature states" | |
52 | .sp | |
53 | .LP | |
54 | Features can be in one of three states: | |
55 | .sp | |
56 | .ne 2 | |
57 | .na | |
58 | \fB\fBactive\fR\fR | |
59 | .ad | |
60 | .RS 12n | |
61 | This feature's on\-disk format changes are in effect on the pool. Support for | |
62 | this feature is required to import the pool in read\-write mode. If this | |
63 | feature is not read-only compatible, support is also required to import the pool | |
64 | in read\-only mode (see "Read\-only compatibility"). | |
65 | .RE | |
66 | ||
67 | .sp | |
68 | .ne 2 | |
69 | .na | |
70 | \fB\fBenabled\fR\fR | |
71 | .ad | |
72 | .RS 12n | |
73 | An administrator has marked this feature as enabled on the pool, but the | |
74 | feature's on\-disk format changes have not been made yet. The pool can still be | |
75 | imported by software that does not support this feature, but changes may be made | |
76 | to the on\-disk format at any time which will move the feature to the | |
77 | \fBactive\fR state. Some features may support returning to the \fBenabled\fR | |
78 | state after becoming \fBactive\fR. See feature\-specific documentation for | |
79 | details. | |
80 | .RE | |
81 | ||
82 | .sp | |
83 | .ne 2 | |
84 | .na | |
85 | \fBdisabled\fR | |
86 | .ad | |
87 | .RS 12n | |
88 | This feature's on\-disk format changes have not been made and will not be made | |
89 | unless an administrator moves the feature to the \fBenabled\fR state. Features | |
90 | cannot be disabled once they have been enabled. | |
91 | .RE | |
92 | ||
93 | .sp | |
94 | .LP | |
95 | The state of supported features is exposed through pool properties of the form | |
96 | \fIfeature@short_name\fR. | |
97 | .SS "Read\-only compatibility" | |
98 | .sp | |
99 | .LP | |
100 | Some features may make on\-disk format changes that do not interfere with other | |
101 | software's ability to read from the pool. These features are referred to as | |
102 | "read\-only compatible". If all unsupported features on a pool are read\-only | |
103 | compatible, the pool can be imported in read\-only mode by setting the | |
104 | \fBreadonly\fR property during import (see \fBzpool\fR(1M) for details on | |
105 | importing pools). | |
106 | .SS "Unsupported features" | |
107 | .sp | |
108 | .LP | |
109 | For each unsupported feature enabled on an imported pool a pool property | |
110 | named \fIunsupported@feature_guid\fR will indicate why the import was allowed | |
111 | despite the unsupported feature. Possible values for this property are: | |
112 | ||
113 | .sp | |
114 | .ne 2 | |
115 | .na | |
116 | \fB\fBinactive\fR\fR | |
117 | .ad | |
118 | .RS 12n | |
119 | The feature is in the \fBenabled\fR state and therefore the pool's on\-disk | |
120 | format is still compatible with software that does not support this feature. | |
121 | .RE | |
122 | ||
123 | .sp | |
124 | .ne 2 | |
125 | .na | |
126 | \fB\fBreadonly\fR\fR | |
127 | .ad | |
128 | .RS 12n | |
129 | The feature is read\-only compatible and the pool has been imported in | |
130 | read\-only mode. | |
131 | .RE | |
132 | ||
133 | .SS "Feature dependencies" | |
134 | .sp | |
135 | .LP | |
136 | Some features depend on other features being enabled in order to function | |
137 | properly. Enabling a feature will automatically enable any features it | |
138 | depends on. | |
139 | .SH FEATURES | |
140 | .sp | |
141 | .LP | |
142 | The following features are supported on this system: | |
143 | .sp | |
144 | .ne 2 | |
145 | .na | |
146 | \fB\fBasync_destroy\fR\fR | |
147 | .ad | |
148 | .RS 4n | |
149 | .TS | |
150 | l l . | |
151 | GUID com.delphix:async_destroy | |
152 | READ\-ONLY COMPATIBLE yes | |
153 | DEPENDENCIES none | |
154 | .TE | |
155 | ||
156 | Destroying a file system requires traversing all of its data in order to | |
157 | return its used space to the pool. Without \fBasync_destroy\fR the file system | |
158 | is not fully removed until all space has been reclaimed. If the destroy | |
159 | operation is interrupted by a reboot or power outage the next attempt to open | |
160 | the pool will need to complete the destroy operation synchronously. | |
161 | ||
162 | When \fBasync_destroy\fR is enabled the file system's data will be reclaimed | |
163 | by a background process, allowing the destroy operation to complete without | |
164 | traversing the entire file system. The background process is able to resume | |
165 | interrupted destroys after the pool has been opened, eliminating the need | |
166 | to finish interrupted destroys as part of the open operation. The amount | |
167 | of space remaining to be reclaimed by the background process is available | |
168 | through the \fBfreeing\fR property. | |
169 | ||
170 | This feature is only \fBactive\fR while \fBfreeing\fR is non\-zero. | |
171 | .RE | |
172 | .SH "SEE ALSO" | |
173 | \fBzpool\fR(1M) |