Use macros for quotes and such

Use Dq,Pq/Po/Pc macros. illumos dumpadm is now in section 8.

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Toomas Soome <tsoome@me.com>
Closes #13586
This commit is contained in:
Toomas Soome 2022-06-24 19:48:10 +03:00 committed by GitHub
parent ad8b9f940c
commit 83691bebf0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -18,7 +18,7 @@
.\" Copyright (c) 2019, Allan Jude .\" Copyright (c) 2019, Allan Jude
.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org> .\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\" .\"
.Dd May 31, 2021 .Dd June 23, 2022
.Dt ZPOOL-FEATURES 7 .Dt ZPOOL-FEATURES 7
.Os .Os
. .
@ -27,8 +27,10 @@
.Nd description of ZFS pool features .Nd description of ZFS pool features
. .
.Sh DESCRIPTION .Sh DESCRIPTION
ZFS pool on-disk format versions are specified via "features" which replace ZFS pool on-disk format versions are specified via
the old on-disk format numbers (the last supported on-disk format number is 28). .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 To enable a feature on a pool use the
.Nm zpool Cm upgrade , .Nm zpool Cm upgrade ,
or set the or set the
@ -62,10 +64,12 @@ implementation that created the pool for information about those features.
Each supported feature also has a short name. Each supported feature also has a short name.
By convention a feature's short name is the portion of its GUID which follows the By convention a feature's short name is the portion of its GUID which follows the
.Sq \&: .Sq \&:
(i.e. .Po
i.e.
.Ar com.example : Ns Ar feature-name .Ar com.example : Ns Ar feature-name
would have the short 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 however a feature's short name may differ across ZFS implementations if
following the convention would result in name conflicts. following the convention would result in name conflicts.
. .
@ -110,9 +114,11 @@ These features are referred to as
If all unsupported features on a pool are 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 the pool can be imported in read-only mode by setting the
.Sy readonly .Sy readonly
property during import (see property during import
.Po see
.Xr zpool-import 8 .Xr zpool-import 8
for details on importing pools). for details on importing pools
.Pc .
. .
.Ss Unsupported features .Ss Unsupported features
For each unsupported feature enabled on an imported pool, a pool property For each unsupported feature enabled on an imported pool, a pool property
@ -143,15 +149,19 @@ The
feature facilitates this by allowing feature sets to be read from text files. feature facilitates this by allowing feature sets to be read from text files.
When set to When set to
.Sy off .Sy off
(the default), compatibility feature sets are disabled .Pq the default ,
(i.e. all features are enabled); when set to compatibility feature sets are disabled
.Pq i.e. all features are enabled ;
when set to
.Sy legacy , .Sy legacy ,
no features are enabled. no features are enabled.
When set to a comma-separated list of filenames 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 .Pa /etc/zfs/compatibility.d
or or
.Pa /usr/share/zfs/compatibility.d ) , .Pa /usr/share/zfs/compatibility.d
.Pc ,
the lists of requested features are read from those files, the lists of requested features are read from those files,
separated by whitespace and/or commas. separated by whitespace and/or commas.
Only features present in all files are enabled. Only features present in all files are enabled.
@ -291,7 +301,9 @@ This feature enables support for separate allocation classes.
.Pp .Pp
This feature becomes This feature becomes
.Sy active .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 . .Nm zpool Cm create No or Nm zpool Cm add No commands .
With device removal, it can be returned to the With device removal, it can be returned to the
.Sy enabled .Sy enabled
@ -356,8 +368,9 @@ state when all v2 bookmarks are destroyed.
.feature com.delphix bookmark_written no bookmark extensible_dataset bookmark_v2 .feature com.delphix bookmark_written no bookmark extensible_dataset bookmark_v2
This feature enables additional bookmark accounting fields, enabling the This feature enables additional bookmark accounting fields, enabling the
.Sy written Ns # Ns Ar bookmark .Sy written Ns # Ns Ar bookmark
property (space written since a bookmark) and estimates of property
send stream sizes for incrementals from bookmarks. .Pq space written since a bookmark
and estimates of send stream sizes for incrementals from bookmarks.
.Pp .Pp
This feature becomes This feature becomes
.Sy active .Sy active
@ -372,7 +385,8 @@ This feature enables the ability for the
and and
.Nm zpool Cm replace .Nm zpool Cm replace
commands to perform sequential reconstruction commands to perform sequential reconstruction
(instead of healing reconstruction) when resilvering. .Pq instead of healing reconstruction
when resilvering.
.Pp .Pp
Sequential reconstruction resilvers a device in LBA order without immediately Sequential reconstruction resilvers a device in LBA order without immediately
verifying the checksums. verifying the checksums.
@ -424,8 +438,10 @@ vdev to an existing pool.
. .
.feature org.illumos edonr no extensible_dataset .feature org.illumos edonr no extensible_dataset
This feature enables the use of the Edon-R hash algorithm for checksum, This feature enables the use of the Edon-R hash algorithm for checksum,
including for nopwrite (if compression is also enabled, an overwrite of including for nopwrite
a block whose checksum matches the data being written will be ignored). .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 In an abundance of caution, Edon-R requires verification when used with
dedup: dedup:
.Nm zfs Cm set Sy dedup Ns = Ns Sy edonr , Ns Sy verify .Nm zfs Cm set Sy dedup Ns = Ns Sy edonr , Ns Sy verify
@ -433,13 +449,15 @@ dedup:
.Pp .Pp
Edon-R is a very high-performance hash algorithm that was part Edon-R is a very high-performance hash algorithm that was part
of the NIST SHA-3 competition. 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 but was not selected because of its unsuitability
as a general purpose secure hash algorithm. as a general purpose secure hash algorithm.
This implementation utilizes the new salted checksumming functionality This implementation utilizes the new salted checksumming functionality
in ZFS, which means that the checksum is pre-seeded with a secret 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 256-bit random key
to be checksummed. .Pq stored on the pool
before being fed the data block to be checksummed.
Thus the produced checksums are unique to a given pool, Thus the produced checksums are unique to a given pool,
preventing hash collision attacks on systems with dedup. preventing hash collision attacks on systems with dedup.
.Pp .Pp
@ -452,10 +470,15 @@ Blocks whose contents can compress to 112 bytes
or smaller can take advantage of this feature. or smaller can take advantage of this feature.
.Pp .Pp
When this feature is enabled, the contents of highly-compressible blocks are 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 stored in the block
the compressed data, rather than a pointer to its location on disk). .Dq pointer
Thus the space of the block (one sector, typically 512 B or 4 KiB) is saved, itself
and no additional I/O is needed to read and write the data block. .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] \*[instant-never]
. .
@ -465,7 +488,9 @@ number of snapshots of a single filesystem or volume, and also reduces
the disk space required. the disk space required.
.Pp .Pp
When there are many snapshots, each snapshot uses many Block Pointer 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. However, in common use cases, most of these bpobjs are empty.
This feature allows us to create each bpobj on-demand, This feature allows us to create each bpobj on-demand,
thus eliminating the empty bpobjs. thus eliminating the empty bpobjs.
@ -536,7 +561,12 @@ will not match the source.
Its use by Its use by
.Nm zfs Cm send Fl i .Nm zfs Cm send Fl i
has been disabled by default 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 .Pp
This feature improves performance of incremental sends This feature improves performance of incremental sends
.Pq Nm zfs Cm send Fl i .Pq Nm zfs Cm send Fl i
@ -549,8 +579,10 @@ contains information about every block that changed between
.Sy A No and Sy B . .Sy A No and Sy B .
Blocks which did not change between those snapshots can be Blocks which did not change between those snapshots can be
identified and omitted from the stream using a piece of metadata called identified and omitted from the stream using a piece of metadata called
the "block birth time", but birth times are not recorded for holes the
(blocks filled only with zeroes). .Dq block birth time ,
but birth times are not recorded for holes
.Pq blocks filled only with zeroes .
Since holes created after Since holes created after
.Sy A No cannot be distinguished from holes created before Sy A , .Sy A No cannot be distinguished from holes created before Sy A ,
information about every hole in the entire filesystem or zvol information about every hole in the entire filesystem or zvol
@ -558,9 +590,9 @@ is included in the send stream.
.Pp .Pp
For workloads where holes are rare this is not a problem. For workloads where holes are rare this is not a problem.
However, when incrementally replicating filesystems or zvols with many holes However, when incrementally replicating filesystems or zvols with many holes
(for example a zvol formatted with another filesystem) a lot of time will .Pq for example a zvol formatted with another filesystem
be spent sending and receiving unnecessary information about holes that a lot of time will be spent sending and receiving unnecessary information
already exist on the receiving side. about holes that already exist on the receiving side.
.Pp .Pp
Once the Once the
.Sy hole_birth .Sy hole_birth
@ -657,7 +689,7 @@ When the
feature is set to feature is set to
.Sy enabled , .Sy enabled ,
the administrator can use the administrator can use
.Xr dumpadm 1M .Xr dumpadm 8
to configure a dump device on a pool comprised of multiple vdevs. to configure a dump device on a pool comprised of multiple vdevs.
.Pp .Pp
Under Under
@ -677,7 +709,9 @@ This feature is an enhancement of
.Sy device_removal , .Sy device_removal ,
which will over time reduce the memory used to track removed devices. which will over time reduce the memory used to track removed devices.
When indirect blocks are freed or remapped, 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 .Pp
This feature becomes This feature becomes
.Sy active .Sy active
@ -688,7 +722,8 @@ command is used on a top-level vdev, and will never return to being
. .
.feature org.zfsonlinux project_quota yes extensible_dataset .feature org.zfsonlinux project_quota yes extensible_dataset
This feature allows administrators to account the spaces and objects usage 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 .Pp
The project ID is an object-based attribute. The project ID is an object-based attribute.
When upgrading an existing filesystem, When upgrading an existing filesystem,
@ -698,7 +733,8 @@ their parent directories' project ID if the parent's inherit flag is set
.Pq via Nm chattr Sy [+-]P No or Nm zfs Cm project Fl s Ns | Ns Fl C . .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. Otherwise, the new object's project ID will be zero.
An object's project ID can be changed at any time by the owner 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 .Nm chattr Fl p Ar prjid
or or
.Nm zfs Cm project Fl p Ar prjid . .Nm zfs Cm project Fl p Ar prjid .
@ -740,7 +776,8 @@ when the deferred resilver begins.
. .
.feature org.illumos sha512 no extensible_dataset .feature org.illumos sha512 no extensible_dataset
This feature enables the use of the SHA-512/256 truncated hash algorithm 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% The native 64-bit arithmetic of SHA-512 provides an approximate 50%
performance boost over SHA-256 on 64-bit hardware performance boost over SHA-256 on 64-bit hardware
and is thus a good minimum-change replacement candidate and is thus a good minimum-change replacement candidate
@ -756,11 +793,12 @@ This feature enables the use of the Skein hash algorithm for checksum and dedup.
Skein is a high-performance secure hash algorithm that was a Skein is a high-performance secure hash algorithm that was a
finalist in the NIST SHA-3 competition. finalist in the NIST SHA-3 competition.
It provides a very high security margin and high performance on 64-bit hardware 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 This implementation also utilizes the new salted checksumming
functionality in ZFS, which means that the checksum is pre-seeded with a 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 secret 256-bit random key
block to be checksummed. .Pq stored on the pool
before being fed the data block to be checksummed.
Thus the produced checksums are unique to a given pool, Thus the produced checksums are unique to a given pool,
preventing hash collision attacks on systems with dedup. preventing hash collision attacks on systems with dedup.
.Pp .Pp
@ -778,7 +816,9 @@ and never returns back to being
. .
.feature com.delphix spacemap_v2 yes .feature com.delphix spacemap_v2 yes
This feature enables the use of the new space map encoding which 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 The new encoding allows space maps to represent large regions of
space more efficiently on-disk while also increasing their maximum space more efficiently on-disk while also increasing their maximum
addressable offset. addressable offset.
@ -872,4 +912,5 @@ are destroyed.
.El .El
. .
.Sh SEE ALSO .Sh SEE ALSO
.Xr zfs 8 ,
.Xr zpool 8 .Xr zpool 8