Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZPOOLPROPS(7)	   FreeBSD Miscellaneous Information Manual	 ZPOOLPROPS(7)

NAME
     zpoolprops	-- properties of ZFS storage pools

DESCRIPTION
     Each pool has several properties associated with it.  Some	properties are
     read-only statistics while	others are configurable	and change the behav-
     ior of the	pool.

     The following are read-only properties:

     allocated	       Amount of storage used within the pool.	See
		       fragmentation and free for more information.

     capacity	       Percentage of pool space	used.  This property can also
		       be referred to by its shortened column name, cap.

     expandsize	       Amount of uninitialized space within the	pool or	device
		       that can	be used	to increase the	total capacity of the
		       pool.  On whole-disk vdevs, this	is the space beyond
		       the end of the GPT a typically occurring	when a LUN is
		       dynamically expanded or a disk replaced with a larger
		       one.  On	partition vdevs, this is the space appended to
		       the partition after it was added	to the pool a most
		       likely by resizing it in-place.	The space can be
		       claimed for the pool by bringing	it online with
		       autoexpand=on or	using zpool online -e.

     fragmentation     The amount of fragmentation in the pool.	 As the	amount
		       of space	allocated increases, it	becomes	more difficult
		       to locate free space.  This may result in lower write
		       performance compared to pools with more unfragmented
		       free space.

     free	       The amount of free space	available in the pool.	By
		       contrast, the zfs(8) available property describes how
		       much new	data can be written to ZFS filesystems/vol-
		       umes.  The zpool	free property is not generally useful
		       for this	purpose, and can be substantially more than
		       the zfs available space.	 This discrepancy is due to
		       several factors,	including raidz	parity;	zfs reserva-
		       tion, quota, refreservation, and	refquota properties;
		       and space set aside by spa_slop_shift (see zfs(4) for
		       more information).

     freeing	       After a file system or snapshot is destroyed, the space
		       it was using is returned	to the pool asynchronously.
		       freeing is the amount of	space remaining	to be re-
		       claimed.	 Over time freeing will	decrease while free
		       increases.

     leaked	       Space not released while	freeing	due to corruption, now
		       permanently leaked into the pool.

     health	       The current health of the pool.	Health can be one of
		       ONLINE, DEGRADED, FAULTED, OFFLINE, REMOVED, UNAVAIL.

     guid	       A unique	identifier for the pool.

     load_guid	       A unique	identifier for the pool.  Unlike the guid
		       property, this identifier is generated every time we
		       load the	pool (i.e. does	not persist across imports/ex-
		       ports) and never	changes	while the pool is loaded (even
		       if a reguid operation takes place).

     size	       Total size of the storage pool.

     unsupported@guid  Information about unsupported features that are enabled
		       on the pool.  See zpool-features(7) for details.

     The space usage properties	report actual physical space available to the
     storage pool.  The	physical space can be different	from the total amount
     of	space that any contained datasets can actually use.  The amount	of
     space used	in a raidz configuration depends on the	characteristics	of the
     data being	written.  In addition, ZFS reserves some space for internal
     accounting	that the zfs(8)	command	takes into account, but	the zpoolprops
     command does not.	For non-full pools of a	reasonable size, these effects
     should be invisible.  For small pools, or pools that are close to being
     completely	full, these discrepancies may become more noticeable.

     The following property can	be set at creation time	and import time:

     altroot
	     Alternate root directory.	If set,	this directory is prepended to
	     any mount points within the pool.	This can be used when examin-
	     ing an unknown pool where the mount points	cannot be trusted, or
	     in	an alternate boot environment, where the typical paths are not
	     valid.  altroot is	not a persistent property.  It is valid	only
	     while the system is up.  Setting altroot defaults to using
	     cachefile=none, though this may be	overridden using an explicit
	     setting.

     The following property can	be set only at import time:

     readonly=on|off
	     If	set to on, the pool will be imported in	read-only mode.	 This
	     property can also be referred to by its shortened column name,
	     rdonly.

     The following properties can be set at creation time and import time, and
     later changed with	the zpool set command:

     ashift=ashift
	     Pool sector size exponent,	to the power of	2 (internally referred
	     to	as ashift).  Values from 9 to 16, inclusive, are valid;	also,
	     the value 0 (the default) means to	auto-detect using the kernel's
	     block layer and a ZFS internal exception list.  I/O operations
	     will be aligned to	the specified size boundaries.	Additionally,
	     the minimum (disk)	write size will	be set to the specified	size,
	     so	this represents	a space	vs. performance	trade-off.  For	opti-
	     mal performance, the pool sector size should be greater than or
	     equal to the sector size of the underlying	disks.	The typical
	     case for setting this property is when performance	is important
	     and the underlying	disks use 4KiB sectors but report 512B sectors
	     to	the OS (for compatibility reasons); in that case, set
	     ashift=12 (which is 1<<12 = 4096).	 When set, this	property is
	     used as the default hint value in subsequent vdev operations
	     (add, attach and replace).	 Changing this value will not modify
	     any existing vdev,	not even on disk replacement; however it can
	     be	used, for instance, to replace a dying 512B sectors disk with
	     a newer 4KiB sectors device: this will probably result in bad
	     performance but at	the same time could prevent loss of data.

     autoexpand=on|off
	     Controls automatic	pool expansion when the	underlying LUN is
	     grown.  If	set to on, the pool will be resized according to the
	     size of the expanded device.  If the device is part of a mirror
	     or	raidz then all devices within that mirror/raidz	group must be
	     expanded before the new space is made available to	the pool.  The
	     default behavior is off.  This property can also be referred to
	     by	its shortened column name, expand.

     autoreplace=on|off
	     Controls automatic	device replacement.  If	set to off, device re-
	     placement must be initiated by the	administrator by using the
	     zpool replace command.  If	set to on, any new device, found in
	     the same physical location	as a device that previously belonged
	     to	the pool, is automatically formatted and replaced.  The	de-
	     fault behavior is off.  This property can also be referred	to by
	     its shortened column name,	replace.  Autoreplace can also be used
	     with virtual disks	(like device mapper) provided that you use the
	     /dev/disk/by-vdev paths setup by vdev_id.conf.  See the
	     vdev_id(8)	manual page for	more details.  Autoreplace and autoon-
	     line require the ZFS Event	Daemon be configured and running.  See
	     the zed(8)	manual page for	more details.

     autotrim=on|off
	     When set to on space which	has been recently freed, and is	no
	     longer allocated by the pool, will	be periodically	trimmed.  This
	     allows block device vdevs which support BLKDISCARD, such as SSDs,
	     or	file vdevs on which the	underlying file	system supports	hole-
	     punching, to reclaim unused blocks.  The default value for	this
	     property is off.

	     Automatic TRIM does not immediately reclaim blocks	after a	free.
	     Instead, it will optimistically delay allowing smaller ranges to
	     be	aggregated into	a few larger ones.  These can then be issued
	     more efficiently to the storage.  TRIM on L2ARC devices is	en-
	     abled by setting l2arc_trim_ahead > 0.

	     Be	aware that automatic trimming of recently freed	data blocks
	     can put significant stress	on the underlying storage devices.
	     This will vary depending of how well the specific device handles
	     these commands.  For lower-end devices it is often	possible to
	     achieve most of the benefits of automatic trimming	by running an
	     on-demand (manual)	TRIM periodically using	the zpool trim com-
	     mand.

     bootfs=(unset)|pool[/dataset]
	     Identifies	the default bootable dataset for the root pool.	 This
	     property is expected to be	set mainly by the installation and up-
	     grade programs.  Not all Linux distribution boot processes	use
	     the bootfs	property.

     cachefile=path|none
	     Controls the location of where the	pool configuration is cached.
	     Discovering all pools on system startup requires a	cached copy of
	     the configuration data that is stored on the root file system.
	     All pools in this cache are automatically imported	when the sys-
	     tem boots.	 Some environments, such as install and	clustering,
	     need to cache this	information in a different location so that
	     pools are not automatically imported.  Setting this property
	     caches the	pool configuration in a	different location that	can
	     later be imported with zpool import -c.  Setting it to the	value
	     none creates a temporary pool that	is never cached, and the ""
	     (empty string) uses the default location.

	     Multiple pools can	share the same cache file.  Because the	kernel
	     destroys and recreates this file when pools are added and re-
	     moved, care should	be taken when attempting to access this	file.
	     When the last pool	using a	cachefile is exported or destroyed,
	     the file will be empty.

     comment=text
	     A text string consisting of printable ASCII characters that will
	     be	stored such that it is available even if the pool becomes
	     faulted.  An administrator	can provide additional information
	     about a pool using	this property.

     compatibility=off|legacy|file[,file]a|
	     Specifies that the	pool maintain compatibility with specific fea-
	     ture sets.	 When set to off (or unset) compatibility is disabled
	     (all features may be enabled); when set to	legacyno features may
	     be	enabled.  When set to a	comma-separated	list of	filenames
	     (each filename may	either be an absolute path, or relative	to
	     /etc/zfs/compatibility.d or /usr/share/zfs/compatibility.d) the
	     lists of requested	features are read from those files, separated
	     by	whitespace and/or commas.  Only	features present in all	files
	     may be enabled.

	     See zpool-features(7), zpool-create(8) and	zpool-upgrade(8) for
	     more information on the operation of compatibility	feature	sets.

     dedupditto=number
	     This property is deprecated and no	longer has any effect.

     delegation=on|off
	     Controls whether a	non-privileged user is granted access based on
	     the dataset permissions defined on	the dataset.  See zfs(8) for
	     more information on ZFS delegated administration.

     failmode=wait|continue|panic
	     Controls the system behavior in the event of catastrophic pool
	     failure.  This condition is typically a result of a loss of con-
	     nectivity to the underlying storage device(s) or a	failure	of all
	     devices within the	pool.  The behavior of such an event is	deter-
	     mined as follows:

	     wait      Blocks all I/O access until the device connectivity is
		       recovered and the errors	are cleared with zpool clear.
		       This is the default behavior.

	     continue  Returns EIO to any new write I/O	requests but allows
		       reads to	any of the remaining healthy devices.  Any
		       write requests that have	yet to be committed to disk
		       would be	blocked.

	     panic     Prints out a message to the console and generates a
		       system crash dump.

     feature@feature_name=enabled
	     The value of this property	is the current state of	feature_name.
	     The only valid value when setting this property is	enabled	which
	     moves feature_name	to the enabled state.  See zpool-features(7)
	     for details on feature states.

     listsnapshots=on|off
	     Controls whether information about	snapshots associated with this
	     pool is output when zfs list is run without the -t	option.	 The
	     default value is off.  This property can also be referred to by
	     its shortened name, listsnaps.

     multihost=on|off
	     Controls whether a	pool activity check should be performed	during
	     zpool import.  When a pool	is determined to be active it cannot
	     be	imported, even with the	-f option.  This property is intended
	     to	be used	in failover configurations where multiple hosts	have
	     access to a pool on shared	storage.

	     Multihost provides	protection on import only.  It does not	pro-
	     tect against an individual	device being used in multiple pools,
	     regardless	of the type of vdev.  See the discussion under zpool
	     create.

	     When this property	is on, periodic	writes to storage occur	to
	     show the pool is in use.  See zfs_multihost_interval in the
	     zfs(4) manual page.  In order to enable this property each	host
	     must set a	unique hostid.	See genhostid(1) zgenhostid(8) spl(4)
	     for additional details.  The default value	is off.

     version=version
	     The current on-disk version of the	pool.  This can	be increased,
	     but never decreased.  The preferred method	of updating pools is
	     with the zpool upgrade command, though this property can be used
	     when a specific version is	needed for backwards compatibility.
	     Once feature flags	are enabled on a pool this property will no
	     longer have a value.

FreeBSD	13.0			 May 27, 2021			  FreeBSD 13.0

NAME | DESCRIPTION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zpoolprops&sektion=7&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help