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