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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
ZPOOL-FEATURES(7)  FreeBSD Miscellaneous Information Manual  ZPOOL-FEATURES(7)

NAME
     zpool-features -- ZFS pool	feature	descriptions

DESCRIPTION
     ZFS pool on-disk format versions are specified via	"features" which
     replace the old on-disk format numbers (the last supported	on-disk	format
     number is 28).  To	enable a feature on a pool use the upgrade subcommand
     of	the zpool(8) command, or set the feature@feature_name property to
     enabled.

     The pool format does not affect file system version compatibility or the
     ability to	send file systems between pools.

     Since most	features can be	enabled	independently of each other the
     on-disk format of the pool	is specified by	the set	of all features	marked
     as	active on the pool. If the pool	was created by another software	ver-
     sion this set may include unsupported features.

   Identifying features
     Every feature has a guid of the form com.example:feature_name.  The
     reverse DNS name ensures that the feature's guid is unique	across all ZFS
     implementations. When unsupported features	are encountered	on a pool they
     will be identified	by their guids.	 Refer to the documentation for	the
     ZFS implementation	that created the pool for information about those fea-
     tures.

     Each supported feature also has a short name.  By convention a feature's
     short name	is the portion of its guid which follows the ':' (e.g.
     com.example:feature_name would have the short name	feature_name ),	how-
     ever a feature's short name may differ across ZFS implementations if fol-
     lowing the	convention would result	in name	conflicts.

   Feature states
     Features can be in	one of three states:

     active    This feature's on-disk format changes are in effect on the
	       pool.  Support for this feature is required to import the pool
	       in read-write mode.  If this feature is not read-only compati-
	       ble, support is also required to	import the pool	in read-only
	       mode (see "Read-only compatibility").

     enabled   An administrator	has marked this	feature	as enabled on the
	       pool, but the feature's on-disk format changes have not been
	       made yet.  The pool can still be	imported by software that does
	       not support this	feature, but changes may be made to the
	       on-disk format at any time which	will move the feature to the
	       active state.  Some features may	support	returning to the
	       enabled state after becoming active.  See feature-specific doc-
	       umentation for details.

     disabled  This feature's on-disk format changes have not been made	and
	       will not	be made	unless an administrator	moves the feature to
	       the enabled state.  Features cannot be disabled once they have
	       been enabled.

     The state of supported features is	exposed	through	pool properties	of the
     form feature@short_name.

   Read-only compatibility
     Some features may make on-disk format changes that	do not interfere with
     other software's ability to read from the pool.  These features are
     referred to as "read-only compatible".  If	all unsupported	features on a
     pool are read-only	compatible, the	pool can be imported in	read-only mode
     by	setting	the readonly property during import (see zpool(8) for details
     on	importing pools).

   Unsupported features
     For each unsupported feature enabled on an	imported pool a	pool property
     named unsupported@feature_guid will indicate why the import was allowed
     despite the unsupported feature.  Possible	values for this	property are:

     inactive  The feature is in the enabled state and therefore the pool's
	       on-disk format is still compatible with software	that does not
	       support this feature.

     readonly  The feature is read-only	compatible and the pool	has been
	       imported	in read-only mode.

   Feature dependencies
     Some features depend on other features being enabled in order to function
     properly.	Enabling a feature will	automatically enable any features it
     depends on.

FEATURES
     The following features are	supported on this system:

     async_destroy

	       GUID		       com.delphix:async_destroy
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       none

	       Destroying a file system	requires traversing all	of its data in
	       order to	return its used	space to the pool.  Without
	       async_destroy the file system is	not fully removed until	all
	       space has been reclaimed.  If the destroy operation is inter-
	       rupted by a reboot or power outage the next attempt to open the
	       pool will need to complete the destroy operation	synchronously.

	       When async_destroy is enabled the file system's data will be
	       reclaimed by a background process, allowing the destroy opera-
	       tion to complete	without	traversing the entire file system.
	       The background process is able to resume	interrupted destroys
	       after the pool has been opened, eliminating the need to finish
	       interrupted destroys as part of the open	operation.  The	amount
	       of space	remaining to be	reclaimed by the background process is
	       available through the freeing property.

	       This feature is only active while freeing is non-zero.

     empty_bpobj

	       GUID		       com.delphix:empty_bpobj
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       none

	       This feature increases the performance of creating and using a
	       large number of snapshots of a single filesystem	or volume, and
	       also reduces the	disk space required.

	       When there are many snapshots, each snapshot uses many Block
	       Pointer Objects (bpobj's) to track blocks associated with that
	       snapshot.  However, in common use cases,	most of	these bpobj's
	       are empty.  This	feature	allows us to create each bpobj on-
	       demand, thus eliminating	the empty bpobjs.

	       This feature is active while there are any filesystems, vol-
	       umes, or	snapshots which	were created after enabling this fea-
	       ture.

     filesystem_limits

	       GUID		       com.joyent:filesystem_limits
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       extensible_dataset

	       This feature enables filesystem and snapshot limits.  These
	       limits can be used to control how many filesystems and/or snap-
	       shots can be created at the point in the	tree on	which the lim-
	       its are set.

	       This feature is active once either of the limit properties has
	       been set	on a dataset.  Once activated the feature is never
	       deactivated.

     lz4_compress

	       GUID		       org.illumos:lz4_compress
	       READ-ONLY COMPATIBLE    no
	       DEPENDENCIES	       none

	       lz4 is a	high-performance real-time compression algorithm that
	       features	significantly faster compression and decompression as
	       well as a higher	compression ratio than the older lzjb compres-
	       sion.  Typically, lz4 compression is approximately 50% faster
	       on compressible data and	200% faster on incompressible data
	       than lzjb.  It is also approximately 80%	faster on decompres-
	       sion, while giving approximately	10% better compression ratio.

	       When the	lz4_compress feature is	set to enabled,	the adminis-
	       trator can turn on lz4 compression on any dataset on the	pool
	       using the zfs(8)	command. Please	note that doing	so will	imme-
	       diately activate	the lz4_compress feature on the	underlying
	       pool (even before any data is written), and the feature will
	       not be deactivated.  Since this feature is not read-only	com-
	       patible,	this operation will render the pool unimportable on
	       systems without support for the lz4_compress feature.  Booting
	       off of lz4 -compressed root pools is supported.

     multi_vdev_crash_dump

	       GUID		       com.joyent:multi_vdev_crash_dump
	       READ-ONLY COMPATIBLE    no
	       DEPENDENCIES	       none

	       This feature allows a dump device to be configured with a pool
	       comprised of multiple vdevs.  Those vdevs may be	arranged in
	       any mirrored or raidz configuration.

     spacemap_histogram

	       GUID		       com.delphix:spacemap_histogram
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       none

	       This features allows ZFS	to maintain more information about how
	       free space is organized within the pool.	If this	feature	is
	       enabled,	ZFS will set this feature to active when a new space
	       map object is created or	an existing space map is upgraded to
	       the new format.	Once the feature is active, it will remain in
	       that state until	the pool is destroyed.

     extensible_dataset

	       GUID		       com.delphix:extensible_dataset
	       READ-ONLY COMPATIBLE    no
	       DEPENDENCIES	       none

	       This feature allows more	flexible use of	internal ZFS data
	       structures, and exists for other	features to depend on.

	       This feature will be active when	the first dependent feature
	       uses it,	and will be returned to	the enabled state when all
	       datasets	that use this feature are destroyed.

     bookmarks

	       GUID		       com.delphix:bookmarks
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       extensible_dataset

	       This feature enables use	of the zfs bookmark subcommand.

	       This feature is active while any	bookmarks exist	in the pool.
	       All bookmarks in	the pool can be	listed by running zfs list -t
	       bookmark	-r poolname.

     enabled_txg

	       GUID		       com.delphix:enabled_txg
	       READ-ONLY COMPATIBLE    yes
	       DEPENDENCIES	       none

	       Once this feature is enabled ZFS	records	the transaction	group
	       number in which new features are	enabled. This has no user-vis-
	       ible impact, but	other features may depend on this feature.

	       This feature becomes active as soon as it is enabled and	will
	       never return to being enabled.

     hole_birth

	       GUID		       com.delphix:hole_birth
	       READ-ONLY COMPATIBLE    no
	       DEPENDENCIES	       enabled_txg

	       This feature improves performance of incremental	sends (``zfs
	       send -i'') and receives for objects with	many holes.  The most
	       common case of hole-filled objects is zvols.

	       An incremental send stream from snapshot	A to snapshot B	con-
	       tains information about every block that	changed	between	A and
	       B.  Blocks which	did not	change between those snapshots can be
	       identified and omitted from the stream using a piece of meta-
	       data called the 'block birth time', but birth times are not
	       recorded	for holes (blocks filled only with zeroes).  Since
	       holes created after A cannot be distinguished from holes	cre-
	       ated before A, information about	every hole in the entire
	       filesystem or zvol is included in the send stream.

	       For workloads where holes are rare this is not a	problem.  How-
	       ever, when incrementally	replicating filesystems	or zvols with
	       many holes (for example a zvol formatted	with another
	       filesystem) a lot of time will be spent sending and receiving
	       unnecessary information about holes that	already	exist on the
	       receiving side.

	       Once the	hole_birth feature has been enabled the	block birth
	       times of	all new	holes will be recorded.	 Incremental sends
	       between snapshots created after this feature is enabled will
	       use this	new metadata to	avoid sending information about	holes
	       that already exist on the receiving side.

	       This feature becomes active as soon as it is enabled and	will
	       never return to being enabled.

SEE ALSO
     zpool(8)

AUTHORS
     This manual page is a mdoc(7) reimplementation of the illumos manual page
     zpool-features(5),	modified and customized	for FreeBSD and	licensed under
     the Common	Development and	Distribution License (CDDL).

     The mdoc(7) implementation	of this	manual page was	initially written by
     Martin Matuska <mm@FreeBSD.org>.

FreeBSD	9.2			April 23, 2014			   FreeBSD 9.2

NAME | DESCRIPTION | FEATURES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=zpool-features&sektion=7&manpath=FreeBSD+9.3-RELEASE>

home | help