.\" Copyright (c) 2019, Allan Jude
.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\"
-.Dd May 31, 2021
+.Dd June 23, 2022
.Dt ZPOOL-FEATURES 7
.Os
.
.Nd description of ZFS pool features
.
.Sh 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).
+ZFS pool on-disk format versions are specified via
+.Dq features
+which replace the old on-disk format numbers
+.Pq the last supported on-disk format number is 28 .
To enable a feature on a pool use the
.Nm zpool Cm upgrade ,
or set the
Each supported feature also has a short name.
By convention a feature's short name is the portion of its GUID which follows the
.Sq \&:
-(i.e.
+.Po
+i.e.
.Ar com.example : Ns Ar feature-name
would have the short name
-.Ar feature-name ) ,
+.Ar feature-name
+.Pc ,
however a feature's short name may differ across ZFS implementations if
following the convention would result in name conflicts.
.
If all unsupported features on a pool are read-only compatible,
the pool can be imported in read-only mode by setting the
.Sy readonly
-property during import (see
+property during import
+.Po see
.Xr zpool-import 8
-for details on importing pools).
+for details on importing pools
+.Pc .
.
.Ss Unsupported features
For each unsupported feature enabled on an imported pool, a pool property
feature facilitates this by allowing feature sets to be read from text files.
When set to
.Sy off
-(the default), compatibility feature sets are disabled
-(i.e. all features are enabled); when set to
+.Pq the default ,
+compatibility feature sets are disabled
+.Pq i.e. all features are enabled ;
+when set to
.Sy legacy ,
no features are enabled.
When set to a comma-separated list of filenames
-(each filename may either be an absolute path, or relative to
+.Po
+each filename may either be an absolute path, or relative to
.Pa /etc/zfs/compatibility.d
or
-.Pa /usr/share/zfs/compatibility.d ) ,
+.Pa /usr/share/zfs/compatibility.d
+.Pc ,
the lists of requested features are read from those files,
separated by whitespace and/or commas.
Only features present in all files are enabled.
.Pp
This feature becomes
.Sy active
-when a dedicated allocation class vdev (dedup or special) is created with the
+when a dedicated allocation class vdev
+.Pq dedup or special
+is created with the
.Nm zpool Cm create No or Nm zpool Cm add No commands .
With device removal, it can be returned to the
.Sy enabled
.feature com.delphix bookmark_written no bookmark extensible_dataset bookmark_v2
This feature enables additional bookmark accounting fields, enabling the
.Sy written Ns # Ns Ar bookmark
-property (space written since a bookmark) and estimates of
-send stream sizes for incrementals from bookmarks.
+property
+.Pq space written since a bookmark
+and estimates of send stream sizes for incrementals from bookmarks.
.Pp
This feature becomes
.Sy active
and
.Nm zpool Cm replace
commands to perform sequential reconstruction
-(instead of healing reconstruction) when resilvering.
+.Pq instead of healing reconstruction
+when resilvering.
.Pp
Sequential reconstruction resilvers a device in LBA order without immediately
verifying the checksums.
.
.feature org.illumos edonr no extensible_dataset
This feature enables the use of the Edon-R hash algorithm for checksum,
-including for nopwrite (if compression is also enabled, an overwrite of
-a block whose checksum matches the data being written will be ignored).
+including for nopwrite
+.Po if compression is also enabled, an overwrite of
+a block whose checksum matches the data being written will be ignored
+.Pc .
In an abundance of caution, Edon-R requires verification when used with
dedup:
.Nm zfs Cm set Sy dedup Ns = Ns Sy edonr , Ns Sy verify
.Pp
Edon-R is a very high-performance hash algorithm that was part
of the NIST SHA-3 competition.
-It provides extremely high hash performance (over 350% faster than SHA-256),
+It provides extremely high hash performance
+.Pq over 350% faster than SHA-256 ,
but was not selected because of its unsuitability
as a general purpose secure hash algorithm.
This implementation utilizes the new salted checksumming functionality
in ZFS, which means that the checksum is pre-seeded with a secret
-256-bit random key (stored on the pool) before being fed the data block
-to be checksummed.
+256-bit random key
+.Pq stored on the pool
+before being fed the data block to be checksummed.
Thus the produced checksums are unique to a given pool,
preventing hash collision attacks on systems with dedup.
.Pp
or smaller can take advantage of this feature.
.Pp
When this feature is enabled, the contents of highly-compressible blocks are
-stored in the block "pointer" itself (a misnomer in this case, as it contains
-the compressed data, rather than a pointer to its location on disk).
-Thus the space of the block (one sector, typically 512 B or 4 KiB) is saved,
-and no additional I/O is needed to read and write the data block.
+stored in the block
+.Dq pointer
+itself
+.Po a misnomer in this case, as it contains
+the compressed data, rather than a pointer to its location on disk
+.Pc .
+Thus the space of the block
+.Pq one sector, typically 512 B or 4 KiB
+is saved, and no additional I/O is needed to read and write the data block.
.
\*[instant-never]
.
the disk space required.
.Pp
When there are many snapshots, each snapshot uses many Block Pointer
-Objects (bpobjs) to track blocks associated with that snapshot.
+Objects
+.Pq bpobjs
+to track blocks associated with that snapshot.
However, in common use cases, most of these bpobjs are empty.
This feature allows us to create each bpobj on-demand,
thus eliminating the empty bpobjs.
Its use by
.Nm zfs Cm send Fl i
has been disabled by default
-.Pq see Sy send_holes_without_birth_time No in Xr zfs 4 .
+.Po
+see
+.Sy send_holes_without_birth_time
+in
+.Xr zfs 4
+.Pc .
.Pp
This feature improves performance of incremental sends
.Pq Nm zfs Cm send Fl i
.Sy A No and Sy B .
Blocks which did not change between those snapshots can be
identified and omitted from the stream using a piece of metadata called
-the "block birth time", but birth times are not recorded for holes
-(blocks filled only with zeroes).
+the
+.Dq block birth time ,
+but birth times are not recorded for holes
+.Pq blocks filled only with zeroes .
Since holes created after
.Sy A No cannot be distinguished from holes created before Sy A ,
information about every hole in the entire filesystem or zvol
.Pp
For workloads where holes are rare this is not a problem.
However, 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.
+.Pq 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.
.Pp
Once the
.Sy hole_birth
feature is set to
.Sy enabled ,
the administrator can use
-.Xr dumpadm 1M
+.Xr dumpadm 8
to configure a dump device on a pool comprised of multiple vdevs.
.Pp
Under
.Sy device_removal ,
which will over time reduce the memory used to track removed devices.
When indirect blocks are freed or remapped,
-we note that their part of the indirect mapping is "obsolete" – no longer needed.
+we note that their part of the indirect mapping is
+.Dq obsolete
+– no longer needed.
.Pp
This feature becomes
.Sy active
.
.feature org.zfsonlinux project_quota yes extensible_dataset
This feature allows administrators to account the spaces and objects usage
-information against the project identifier (ID).
+information against the project identifier
+.Pq ID .
.Pp
The project ID is an object-based attribute.
When upgrading an existing filesystem,
.Pq via Nm chattr Sy [+-]P No or Nm zfs Cm project Fl s Ns | Ns Fl C .
Otherwise, the new object's project ID will be zero.
An object's project ID can be changed at any time by the owner
-(or privileged user) via
+.Pq or privileged user
+via
.Nm chattr Fl p Ar prjid
or
.Nm zfs Cm project Fl p Ar prjid .
.
.feature org.illumos sha512 no extensible_dataset
This feature enables the use of the SHA-512/256 truncated hash algorithm
-(FIPS 180-4) for checksum and dedup.
+.Pq FIPS 180-4
+for checksum and dedup.
The native 64-bit arithmetic of SHA-512 provides an approximate 50%
performance boost over SHA-256 on 64-bit hardware
and is thus a good minimum-change replacement candidate
Skein is a high-performance secure hash algorithm that was a
finalist in the NIST SHA-3 competition.
It provides a very high security margin and high performance on 64-bit hardware
-(80% faster than SHA-256).
+.Pq 80% faster than SHA-256 .
This implementation also utilizes the new salted checksumming
functionality in ZFS, which means that the checksum is pre-seeded with a
-secret 256-bit random key (stored on the pool) before being fed the data
-block to be checksummed.
+secret 256-bit random key
+.Pq stored on the pool
+before being fed the data block to be checksummed.
Thus the produced checksums are unique to a given pool,
preventing hash collision attacks on systems with dedup.
.Pp
.
.feature com.delphix spacemap_v2 yes
This feature enables the use of the new space map encoding which
-consists of two words (instead of one) whenever it is advantageous.
+consists of two words
+.Pq instead of one
+whenever it is advantageous.
The new encoding allows space maps to represent large regions of
space more efficiently on-disk while also increasing their maximum
addressable offset.
.El
.
.Sh SEE ALSO
+.Xr zfs 8 ,
.Xr zpool 8
projects / mirror_zfs.git / commitdiff