]>
Commit | Line | Data |
---|---|---|
c5ebfbbe RW |
1 | .\" |
2 | .\" CDDL HEADER START | |
3 | .\" | |
4 | .\" The contents of this file are subject to the terms of the | |
5 | .\" Common Development and Distribution License (the "License"). | |
6 | .\" You may not use this file except in compliance with the License. | |
7 | .\" | |
8 | .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE | |
1d3ba0bf | 9 | .\" or https://opensource.org/licenses/CDDL-1.0. |
c5ebfbbe RW |
10 | .\" See the License for the specific language governing permissions |
11 | .\" and limitations under the License. | |
12 | .\" | |
13 | .\" When distributing Covered Code, include this CDDL HEADER in each | |
14 | .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. | |
15 | .\" If applicable, add the following below this CDDL HEADER, with the | |
16 | .\" fields enclosed by brackets "[]" replaced with your own identifying | |
17 | .\" information: Portions Copyright [yyyy] [name of copyright owner] | |
18 | .\" | |
19 | .\" CDDL HEADER END | |
20 | .\" | |
c5ebfbbe RW |
21 | .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. |
22 | .\" Copyright (c) 2012, 2018 by Delphix. All rights reserved. | |
23 | .\" Copyright (c) 2012 Cyril Plisko. All Rights Reserved. | |
24 | .\" Copyright (c) 2017 Datto Inc. | |
25 | .\" Copyright (c) 2018 George Melikov. All Rights Reserved. | |
26 | .\" Copyright 2017 Nexenta Systems, Inc. | |
27 | .\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved. | |
658fb802 | 28 | .\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org> |
c5ebfbbe | 29 | .\" |
f84fe3fc | 30 | .Dd May 27, 2021 |
2badb345 | 31 | .Dt ZPOOLPROPS 7 |
6706552e | 32 | .Os |
f84fe3fc | 33 | . |
c5ebfbbe RW |
34 | .Sh NAME |
35 | .Nm zpoolprops | |
f84fe3fc AZ |
36 | .Nd properties of ZFS storage pools |
37 | . | |
c5ebfbbe RW |
38 | .Sh DESCRIPTION |
39 | Each pool has several properties associated with it. | |
40 | Some properties are read-only statistics while others are configurable and | |
41 | change the behavior of the pool. | |
42 | .Pp | |
43 | The following are read-only properties: | |
f84fe3fc | 44 | .Bl -tag -width "unsupported@guid" |
c5ebfbbe RW |
45 | .It Cm allocated |
46 | Amount of storage used within the pool. | |
47 | See | |
48 | .Sy fragmentation | |
49 | and | |
50 | .Sy free | |
51 | for more information. | |
52 | .It Sy capacity | |
53 | Percentage of pool space used. | |
54 | This property can also be referred to by its shortened column name, | |
55 | .Sy cap . | |
56 | .It Sy expandsize | |
57 | Amount of uninitialized space within the pool or device that can be used to | |
58 | increase the total capacity of the pool. | |
b60ae3a5 AZ |
59 | On whole-disk vdevs, this is the space beyond the end of the GPT – |
60 | typically occurring when a LUN is dynamically expanded | |
61 | or a disk replaced with a larger one. | |
62 | On partition vdevs, this is the space appended to the partition after it was | |
63 | added to the pool – most likely by resizing it in-place. | |
64 | The space can be claimed for the pool by bringing it online with | |
65 | .Sy autoexpand=on | |
66 | or using | |
67 | .Nm zpool Cm online Fl e . | |
c5ebfbbe | 68 | .It Sy fragmentation |
f84fe3fc AZ |
69 | The amount of fragmentation in the pool. |
70 | As the amount of space | |
c5ebfbbe RW |
71 | .Sy allocated |
72 | increases, it becomes more difficult to locate | |
73 | .Sy free | |
f84fe3fc AZ |
74 | space. |
75 | This may result in lower write performance compared to pools with more | |
c5ebfbbe RW |
76 | unfragmented free space. |
77 | .It Sy free | |
78 | The amount of free space available in the pool. | |
79 | By contrast, the | |
80 | .Xr zfs 8 | |
81 | .Sy available | |
82 | property describes how much new data can be written to ZFS filesystems/volumes. | |
83 | The zpool | |
84 | .Sy free | |
b46be903 DS |
85 | property is not generally useful for this purpose, and can be substantially more |
86 | than the zfs | |
c5ebfbbe | 87 | .Sy available |
f84fe3fc AZ |
88 | space. |
89 | This discrepancy is due to several factors, including raidz parity; | |
b46be903 DS |
90 | zfs reservation, quota, refreservation, and refquota properties; and space set |
91 | aside by | |
c5ebfbbe RW |
92 | .Sy spa_slop_shift |
93 | (see | |
2badb345 | 94 | .Xr zfs 4 |
c5ebfbbe RW |
95 | for more information). |
96 | .It Sy freeing | |
97 | After a file system or snapshot is destroyed, the space it was using is | |
98 | returned to the pool asynchronously. | |
99 | .Sy freeing | |
100 | is the amount of space remaining to be reclaimed. | |
101 | Over time | |
102 | .Sy freeing | |
103 | will decrease while | |
104 | .Sy free | |
105 | increases. | |
17fd8f6b AZ |
106 | .It Sy leaked |
107 | Space not released while | |
108 | .Sy freeing | |
109 | due to corruption, now permanently leaked into the pool. | |
c5ebfbbe RW |
110 | .It Sy health |
111 | The current health of the pool. | |
112 | Health can be one of | |
113 | .Sy ONLINE , DEGRADED , FAULTED , OFFLINE, REMOVED , UNAVAIL . | |
114 | .It Sy guid | |
115 | A unique identifier for the pool. | |
116 | .It Sy load_guid | |
117 | A unique identifier for the pool. | |
118 | Unlike the | |
119 | .Sy guid | |
f84fe3fc | 120 | property, this identifier is generated every time we load the pool (i.e. does |
c5ebfbbe RW |
121 | not persist across imports/exports) and never changes while the pool is loaded |
122 | (even if a | |
123 | .Sy reguid | |
124 | operation takes place). | |
125 | .It Sy size | |
126 | Total size of the storage pool. | |
f84fe3fc | 127 | .It Sy unsupported@ Ns Em guid |
c5ebfbbe RW |
128 | Information about unsupported features that are enabled on the pool. |
129 | See | |
2badb345 | 130 | .Xr zpool-features 7 |
c5ebfbbe RW |
131 | for details. |
132 | .El | |
133 | .Pp | |
134 | The space usage properties report actual physical space available to the | |
135 | storage pool. | |
136 | The physical space can be different from the total amount of space that any | |
137 | contained datasets can actually use. | |
138 | The amount of space used in a raidz configuration depends on the characteristics | |
139 | of the data being written. | |
140 | In addition, ZFS reserves some space for internal accounting that the | |
141 | .Xr zfs 8 | |
142 | command takes into account, but the | |
143 | .Nm | |
144 | command does not. | |
145 | For non-full pools of a reasonable size, these effects should be invisible. | |
146 | For small pools, or pools that are close to being completely full, these | |
147 | discrepancies may become more noticeable. | |
148 | .Pp | |
149 | The following property can be set at creation time and import time: | |
150 | .Bl -tag -width Ds | |
151 | .It Sy altroot | |
152 | Alternate root directory. | |
153 | If set, this directory is prepended to any mount points within the pool. | |
154 | This can be used when examining an unknown pool where the mount points cannot be | |
155 | trusted, or in an alternate boot environment, where the typical paths are not | |
156 | valid. | |
157 | .Sy altroot | |
158 | is not a persistent property. | |
159 | It is valid only while the system is up. | |
160 | Setting | |
161 | .Sy altroot | |
162 | defaults to using | |
163 | .Sy cachefile Ns = Ns Sy none , | |
164 | though this may be overridden using an explicit setting. | |
165 | .El | |
166 | .Pp | |
167 | The following property can be set only at import time: | |
168 | .Bl -tag -width Ds | |
169 | .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off | |
170 | If set to | |
171 | .Sy on , | |
172 | the pool will be imported in read-only mode. | |
173 | This property can also be referred to by its shortened column name, | |
174 | .Sy rdonly . | |
175 | .El | |
176 | .Pp | |
177 | The following properties can be set at creation time and import time, and later | |
178 | changed with the | |
179 | .Nm zpool Cm set | |
180 | command: | |
181 | .Bl -tag -width Ds | |
fa22ec56 | 182 | .It Sy ashift Ns = Ns Ar ashift |
c5ebfbbe RW |
183 | Pool sector size exponent, to the power of |
184 | .Sy 2 | |
185 | (internally referred to as | |
defa5a0a AZ |
186 | .Sy ashift ) . |
187 | Values from 9 to 16, inclusive, are valid; also, the | |
c5ebfbbe | 188 | value 0 (the default) means to auto-detect using the kernel's block |
f84fe3fc AZ |
189 | layer and a ZFS internal exception list. |
190 | I/O operations will be aligned to the specified size boundaries. | |
191 | Additionally, the minimum (disk) | |
c5ebfbbe | 192 | write size will be set to the specified size, so this represents a |
2d232ca8 | 193 | space/performance trade-off. |
f84fe3fc AZ |
194 | For optimal performance, the pool sector size should be greater than |
195 | or equal to the sector size of the underlying disks. | |
196 | The typical case for setting this property is when | |
c5ebfbbe RW |
197 | performance is important and the underlying disks use 4KiB sectors but |
198 | report 512B sectors to the OS (for compatibility reasons); in that | |
199 | case, set | |
f84fe3fc AZ |
200 | .Sy ashift Ns = Ns Sy 12 |
201 | (which is | |
202 | .Sy 1<<12 No = Sy 4096 ) . | |
203 | When set, this property is | |
c5ebfbbe | 204 | used as the default hint value in subsequent vdev operations (add, |
f84fe3fc AZ |
205 | attach and replace). |
206 | Changing this value will not modify any existing | |
c5ebfbbe RW |
207 | vdev, not even on disk replacement; however it can be used, for |
208 | instance, to replace a dying 512B sectors disk with a newer 4KiB | |
209 | sectors device: this will probably result in bad performance but at the | |
210 | same time could prevent loss of data. | |
211 | .It Sy autoexpand Ns = Ns Sy on Ns | Ns Sy off | |
212 | Controls automatic pool expansion when the underlying LUN is grown. | |
213 | If set to | |
214 | .Sy on , | |
215 | the pool will be resized according to the size of the expanded device. | |
216 | If the device is part of a mirror or raidz then all devices within that | |
217 | mirror/raidz group must be expanded before the new space is made available to | |
218 | the pool. | |
219 | The default behavior is | |
220 | .Sy off . | |
221 | This property can also be referred to by its shortened column name, | |
222 | .Sy expand . | |
223 | .It Sy autoreplace Ns = Ns Sy on Ns | Ns Sy off | |
224 | Controls automatic device replacement. | |
225 | If set to | |
226 | .Sy off , | |
227 | device replacement must be initiated by the administrator by using the | |
228 | .Nm zpool Cm replace | |
229 | command. | |
230 | If set to | |
231 | .Sy on , | |
232 | any new device, found in the same physical location as a device that previously | |
233 | belonged to the pool, is automatically formatted and replaced. | |
234 | The default behavior is | |
235 | .Sy off . | |
236 | This property can also be referred to by its shortened column name, | |
237 | .Sy replace . | |
238 | Autoreplace can also be used with virtual disks (like device | |
239 | mapper) provided that you use the /dev/disk/by-vdev paths setup by | |
f84fe3fc AZ |
240 | vdev_id.conf. |
241 | See the | |
c5ebfbbe | 242 | .Xr vdev_id 8 |
f84fe3fc | 243 | manual page for more details. |
c5ebfbbe | 244 | Autoreplace and autoonline require the ZFS Event Daemon be configured and |
f84fe3fc AZ |
245 | running. |
246 | See the | |
c5ebfbbe | 247 | .Xr zed 8 |
f84fe3fc | 248 | manual page for more details. |
c5ebfbbe RW |
249 | .It Sy autotrim Ns = Ns Sy on Ns | Ns Sy off |
250 | When set to | |
251 | .Sy on | |
252 | space which has been recently freed, and is no longer allocated by the pool, | |
f84fe3fc AZ |
253 | will be periodically trimmed. |
254 | This allows block device vdevs which support | |
c5ebfbbe | 255 | BLKDISCARD, such as SSDs, or file vdevs on which the underlying file system |
f84fe3fc AZ |
256 | supports hole-punching, to reclaim unused blocks. |
257 | The default value for this property is | |
c5ebfbbe RW |
258 | .Sy off . |
259 | .Pp | |
f84fe3fc AZ |
260 | Automatic TRIM does not immediately reclaim blocks after a free. |
261 | Instead, it will optimistically delay allowing smaller ranges to be aggregated | |
262 | into a few larger ones. | |
263 | These can then be issued more efficiently to the storage. | |
b7654bd7 GA |
264 | TRIM on L2ARC devices is enabled by setting |
265 | .Sy l2arc_trim_ahead > 0 . | |
c5ebfbbe RW |
266 | .Pp |
267 | Be aware that automatic trimming of recently freed data blocks can put | |
f84fe3fc AZ |
268 | significant stress on the underlying storage devices. |
269 | This will vary depending of how well the specific device handles these commands. | |
270 | For lower-end devices it is often possible to achieve most of the benefits | |
c5ebfbbe RW |
271 | of automatic trimming by running an on-demand (manual) TRIM periodically |
272 | using the | |
273 | .Nm zpool Cm trim | |
274 | command. | |
f84fe3fc AZ |
275 | .It Sy bootfs Ns = Ns Sy (unset) Ns | Ns Ar pool Ns Op / Ns Ar dataset |
276 | Identifies the default bootable dataset for the root pool. | |
b46be903 DS |
277 | This property is expected to be set mainly by the installation and upgrade |
278 | programs. | |
c5ebfbbe RW |
279 | Not all Linux distribution boot processes use the bootfs property. |
280 | .It Sy cachefile Ns = Ns Ar path Ns | Ns Sy none | |
281 | Controls the location of where the pool configuration is cached. | |
282 | Discovering all pools on system startup requires a cached copy of the | |
283 | configuration data that is stored on the root file system. | |
284 | All pools in this cache are automatically imported when the system boots. | |
285 | Some environments, such as install and clustering, need to cache this | |
286 | information in a different location so that pools are not automatically | |
287 | imported. | |
288 | Setting this property caches the pool configuration in a different location that | |
289 | can later be imported with | |
290 | .Nm zpool Cm import Fl c . | |
291 | Setting it to the value | |
292 | .Sy none | |
293 | creates a temporary pool that is never cached, and the | |
294 | ||
295 | .Pq empty string | |
296 | uses the default location. | |
297 | .Pp | |
298 | Multiple pools can share the same cache file. | |
299 | Because the kernel destroys and recreates this file when pools are added and | |
300 | removed, care should be taken when attempting to access this file. | |
301 | When the last pool using a | |
302 | .Sy cachefile | |
303 | is exported or destroyed, the file will be empty. | |
304 | .It Sy comment Ns = Ns Ar text | |
305 | A text string consisting of printable ASCII characters that will be stored | |
306 | such that it is available even if the pool becomes faulted. | |
307 | An administrator can provide additional information about a pool using this | |
308 | property. | |
f84fe3fc | 309 | .It Sy compatibility Ns = Ns Sy off Ns | Ns Sy legacy Ns | Ns Ar file Ns Oo , Ns Ar file Oc Ns … |
658fb802 CB |
310 | Specifies that the pool maintain compatibility with specific feature sets. |
311 | When set to | |
312 | .Sy off | |
f84fe3fc AZ |
313 | (or unset) compatibility is disabled (all features may be enabled); when set to |
314 | .Sy legacy Ns | |
315 | no features may be enabled. | |
316 | When set to a comma-separated list of filenames | |
317 | (each filename may either be an absolute path, or relative to | |
318 | .Pa /etc/zfs/compatibility.d | |
319 | or | |
320 | .Pa /usr/share/zfs/compatibility.d ) | |
658fb802 | 321 | the lists of requested features are read from those files, separated by |
f84fe3fc AZ |
322 | whitespace and/or commas. |
323 | Only features present in all files may be enabled. | |
324 | .Pp | |
658fb802 | 325 | See |
2badb345 | 326 | .Xr zpool-features 7 , |
658fb802 CB |
327 | .Xr zpool-create 8 |
328 | and | |
329 | .Xr zpool-upgrade 8 | |
330 | for more information on the operation of compatibility feature sets. | |
c5ebfbbe RW |
331 | .It Sy dedupditto Ns = Ns Ar number |
332 | This property is deprecated and no longer has any effect. | |
333 | .It Sy delegation Ns = Ns Sy on Ns | Ns Sy off | |
334 | Controls whether a non-privileged user is granted access based on the dataset | |
335 | permissions defined on the dataset. | |
336 | See | |
337 | .Xr zfs 8 | |
338 | for more information on ZFS delegated administration. | |
339 | .It Sy failmode Ns = Ns Sy wait Ns | Ns Sy continue Ns | Ns Sy panic | |
340 | Controls the system behavior in the event of catastrophic pool failure. | |
341 | This condition is typically a result of a loss of connectivity to the underlying | |
342 | storage device(s) or a failure of all devices within the pool. | |
343 | The behavior of such an event is determined as follows: | |
344 | .Bl -tag -width "continue" | |
345 | .It Sy wait | |
346 | Blocks all I/O access until the device connectivity is recovered and the errors | |
7adc1900 BB |
347 | are cleared with |
348 | .Nm zpool Cm clear . | |
c5ebfbbe RW |
349 | This is the default behavior. |
350 | .It Sy continue | |
351 | Returns | |
352 | .Er EIO | |
353 | to any new write I/O requests but allows reads to any of the remaining healthy | |
354 | devices. | |
355 | Any write requests that have yet to be committed to disk would be blocked. | |
356 | .It Sy panic | |
357 | Prints out a message to the console and generates a system crash dump. | |
358 | .El | |
359 | .It Sy feature@ Ns Ar feature_name Ns = Ns Sy enabled | |
360 | The value of this property is the current state of | |
361 | .Ar feature_name . | |
362 | The only valid value when setting this property is | |
363 | .Sy enabled | |
364 | which moves | |
365 | .Ar feature_name | |
366 | to the enabled state. | |
367 | See | |
2badb345 | 368 | .Xr zpool-features 7 |
c5ebfbbe RW |
369 | for details on feature states. |
370 | .It Sy listsnapshots Ns = Ns Sy on Ns | Ns Sy off | |
371 | Controls whether information about snapshots associated with this pool is | |
372 | output when | |
373 | .Nm zfs Cm list | |
374 | is run without the | |
375 | .Fl t | |
376 | option. | |
377 | The default value is | |
378 | .Sy off . | |
379 | This property can also be referred to by its shortened name, | |
380 | .Sy listsnaps . | |
381 | .It Sy multihost Ns = Ns Sy on Ns | Ns Sy off | |
382 | Controls whether a pool activity check should be performed during | |
383 | .Nm zpool Cm import . | |
384 | When a pool is determined to be active it cannot be imported, even with the | |
385 | .Fl f | |
f84fe3fc AZ |
386 | option. |
387 | This property is intended to be used in failover configurations | |
c5ebfbbe RW |
388 | where multiple hosts have access to a pool on shared storage. |
389 | .Pp | |
f84fe3fc AZ |
390 | Multihost provides protection on import only. |
391 | It does not protect against an | |
c5ebfbbe RW |
392 | individual device being used in multiple pools, regardless of the type of vdev. |
393 | See the discussion under | |
f84fe3fc | 394 | .Nm zpool Cm create . |
c5ebfbbe RW |
395 | .Pp |
396 | When this property is on, periodic writes to storage occur to show the pool is | |
f84fe3fc AZ |
397 | in use. |
398 | See | |
c5ebfbbe RW |
399 | .Sy zfs_multihost_interval |
400 | in the | |
2badb345 | 401 | .Xr zfs 4 |
f84fe3fc AZ |
402 | manual page. |
403 | In order to enable this property each host must set a unique hostid. | |
c5ebfbbe RW |
404 | See |
405 | .Xr genhostid 1 | |
406 | .Xr zgenhostid 8 | |
2badb345 | 407 | .Xr spl 4 |
f84fe3fc AZ |
408 | for additional details. |
409 | The default value is | |
c5ebfbbe RW |
410 | .Sy off . |
411 | .It Sy version Ns = Ns Ar version | |
412 | The current on-disk version of the pool. | |
413 | This can be increased, but never decreased. | |
414 | The preferred method of updating pools is with the | |
415 | .Nm zpool Cm upgrade | |
416 | command, though this property can be used when a specific version is needed for | |
417 | backwards compatibility. | |
418 | Once feature flags are enabled on a pool this property will no longer have a | |
419 | value. | |
420 | .El |