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