|
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) |