c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2024-12-25 02:49:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Use macros for quotes and such

Browse Source 
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
1 changed files with 81 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
man/man7/zpool-features.7
View File

@ -18,7 +18,7 @@
.\" 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
.
@ -27,8 +27,10 @@
.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
@ -62,10 +64,12 @@ implementation that created the pool for information about those features.
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.
.
@ -110,9 +114,11 @@ These features are referred to as
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
@ -143,15 +149,19 @@ The
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.
@ -291,7 +301,9 @@ This feature enables support for separate allocation classes.
.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
@ -356,8 +368,9 @@ state when all v2 bookmarks are destroyed.
.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
@ -372,7 +385,8 @@ This feature enables the ability for the
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.
@ -424,8 +438,10 @@ vdev to an existing pool.
.
.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
@ -433,13 +449,15 @@ dedup:
.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
@ -452,10 +470,15 @@ Blocks whose contents can compress to 112 bytes
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]
.
@ -465,7 +488,9 @@ number of snapshots of a single filesystem or volume, and also reduces
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.
@ -536,7 +561,12 @@ will not match the source.
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
@ -549,8 +579,10 @@ contains information about every block that changed between
.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
@ -558,9 +590,9 @@ is included in the send stream.
.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
@ -657,7 +689,7 @@ When the
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
@ -677,7 +709,9 @@ This feature is an enhancement of
.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
@ -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
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,
@ -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 .
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 .
@ -740,7 +776,8 @@ when the deferred resilver begins.
.
.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
@ -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
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
@ -778,7 +816,9 @@ and never returns back to being
.
.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.
@ -872,4 +912,5 @@ are destroyed.
.El
.
.Sh SEE ALSO
.Xr zfs 8 ,
.Xr zpool 8