Changeset View
Changeset View
Standalone View
Standalone View
cddl/contrib/opensolaris/cmd/zpool/zpool-features.7
'\" te | '\" te | ||||
.\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>. | .\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>. All Rights Reserved. | ||||
.\" All Rights Reserved. | .\" Copyright (c) 2013, 2017 by Delphix. All rights reserved. | ||||
.\" | |||||
.\" The contents of this file are subject to the terms of the | |||||
.\" Common Development and Distribution License (the "License"). | |||||
.\" You may not use this file except in compliance with the License. | |||||
.\" | |||||
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE | |||||
.\" or http://www.opensolaris.org/os/licensing. | |||||
.\" See the License for the specific language governing permissions | |||||
.\" and limitations under the License. | |||||
.\" | |||||
.\" When distributing Covered Code, include this CDDL HEADER in each | |||||
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. | |||||
.\" If applicable, add the following below this CDDL HEADER, with the | |||||
.\" fields enclosed by brackets "[]" replaced with your own identifying | |||||
.\" information: Portions Copyright [yyyy] [name of copyright owner] | |||||
.\" | |||||
.\" Copyright (c) 2012, 2017 by Delphix. All rights reserved. | |||||
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. | .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. | ||||
.\" Copyright (c) 2013, Joyent, Inc. All rights reserved. | .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. | ||||
.\" Copyright (c) 2014 Integros [integros.com] | |||||
.\" The contents of this file are subject to the terms of the Common Development | |||||
.\" and Distribution License (the "License"). You may not use this file except | |||||
.\" in compliance with the License. You can obtain a copy of the license at | |||||
.\" usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. | |||||
.\" | .\" | ||||
.\" See the License for the specific language governing permissions and | |||||
.\" limitations under the License. When distributing Covered Code, include this | |||||
.\" CDDL HEADER in each file and include the License file at | |||||
.\" usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this | |||||
.\" CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your | |||||
.\" own identifying information: | |||||
.\" Portions Copyright [yyyy] [name of copyright owner] | |||||
.\" | |||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd June 7, 2017 | .TH ZPOOL-FEATURES 7 "Dec 9, 2018" | ||||
.Dt ZPOOL-FEATURES 7 | .SH NAME | ||||
.Os | zpool\-features \- ZFS pool feature descriptions | ||||
.Sh NAME | .SH DESCRIPTION | ||||
.Nm zpool-features | .LP | ||||
.Nd ZFS pool feature descriptions | |||||
.Sh DESCRIPTION | |||||
ZFS pool on\-disk format versions are specified via "features" which replace | 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 | the old on\-disk format numbers (the last supported on\-disk format number is | ||||
28). | 28). To enable a feature on a pool use the \fBupgrade\fR subcommand of the | ||||
To enable a feature on a pool use the | \fBzpool\fR(8) command, or set the \fBfeature@\fR\fIfeature_name\fR property | ||||
.Cm upgrade | to \fBenabled\fR. | ||||
subcommand of the | .sp | ||||
.Xr zpool 8 | .LP | ||||
command, or set the | |||||
.Sy feature@feature_name | |||||
property to | |||||
.Ar enabled . | |||||
.Pp | |||||
The pool format does not affect file system version compatibility or the ability | The pool format does not affect file system version compatibility or the ability | ||||
to send file systems between pools. | to send file systems between pools. | ||||
.Pp | .sp | ||||
.LP | |||||
Since most features can be enabled independently of each other the on\-disk | 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 | format of the pool is specified by the set of all features marked as | ||||
.Sy active | \fBactive\fR on the pool. If the pool was created by another software version | ||||
on the pool. | this set may include unsupported features. | ||||
If the pool was created by another software version this set may | .SS "Identifying features" | ||||
include unsupported features. | .LP | ||||
.Ss Identifying features | Every feature has a guid of the form \fIcom.example:feature_name\fR. The reverse | ||||
Every feature has a guid of the form | DNS name ensures that the feature's guid is unique across all ZFS | ||||
.Sy com.example:feature_name . | implementations. When unsupported features are encountered on a pool they will | ||||
The reverse DNS name ensures that the feature's guid is unique across all ZFS | be identified by their guids. Refer to the documentation for the ZFS | ||||
implementations. | implementation that created the pool for information about those features. | ||||
When unsupported features are encountered on a pool they will | .sp | ||||
be identified by their guids. | .LP | ||||
Refer to the documentation for the ZFS implementation that created the pool | Each supported feature also has a short name. By convention a feature's short | ||||
for information about those features. | name is the portion of its guid which follows the ':' (e.g. | ||||
.Pp | \fIcom.example:feature_name\fR would have the short name \fIfeature_name\fR), | ||||
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. | |||||
.Sy com.example:feature_name | |||||
would have the short name | |||||
.Sy feature_name ), | |||||
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. | ||||
.Ss Feature states | .SS "Feature states" | ||||
.LP | |||||
Features can be in one of three states: | Features can be in one of three states: | ||||
.Bl -tag -width "XXXXXXXX" | .sp | ||||
.It Sy active | .ne 2 | ||||
This feature's on\-disk format changes are in effect on the pool. | .na | ||||
Support for this feature is required to import the pool in read\-write mode. | \fB\fBactive\fR\fR | ||||
If this feature is not read-only compatible, support is also required to | .ad | ||||
import the pool in read\-only mode (see "Read\-only compatibility"). | .RS 12n | ||||
.It Sy enabled | 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 compatible, support is also required to import the pool | |||||
in read\-only mode (see "Read\-only compatibility"). | |||||
.RE | |||||
.sp | |||||
.ne 2 | |||||
.na | |||||
\fB\fBenabled\fR\fR | |||||
.ad | |||||
.RS 12n | |||||
An administrator has marked this feature as enabled on the pool, but the | An administrator has marked this feature as enabled on the pool, but the | ||||
feature's on\-disk format changes have not been made yet. | feature's on\-disk format changes have not been made yet. The pool can still be | ||||
The pool can still be imported by software that does not support this feature, | imported by software that does not support this feature, but changes may be made | ||||
but changes may be made to the on\-disk format at any time which will move | to the on\-disk format at any time which will move the feature to the | ||||
the feature to the | \fBactive\fR state. Some features may support returning to the \fBenabled\fR | ||||
.Sy active | state after becoming \fBactive\fR. See feature\-specific documentation for | ||||
state. | details. | ||||
Some features may support returning to the | .RE | ||||
.Sy enabled | |||||
state after becoming | .sp | ||||
.Sy active . | .ne 2 | ||||
See feature\-specific documentation for details. | .na | ||||
.It Sy disabled | \fBdisabled\fR | ||||
.ad | |||||
.RS 12n | |||||
This feature's on\-disk format changes have not been made and will not be made | This feature's on\-disk format changes have not been made and will not be made | ||||
unless an administrator moves the feature to the | unless an administrator moves the feature to the \fBenabled\fR state. Features | ||||
.Sy enabled | cannot be disabled once they have been enabled. | ||||
state. | .RE | ||||
Features cannot be disabled once they have been enabled. | |||||
.El | .sp | ||||
.Pp | .LP | ||||
The state of supported features is exposed through pool properties of the form | The state of supported features is exposed through pool properties of the form | ||||
.Sy feature@short_name . | \fIfeature@short_name\fR. | ||||
.Ss Read\-only compatibility | .SS "Read\-only compatibility" | ||||
.LP | |||||
Some features may make on\-disk format changes that do not interfere with other | Some features may make on\-disk format changes that do not interfere with other | ||||
software's ability to read from the pool. | software's ability to read from the pool. These features are referred to as | ||||
These features are referred to as "read\-only compatible". | "read\-only compatible". If all unsupported features on a pool are read\-only | ||||
If all unsupported features on a pool are read\-only compatible, the pool can | compatible, the pool can be imported in read\-only mode by setting the | ||||
be imported in read\-only mode by setting the | \fBreadonly\fR property during import (see \fBzpool\fR(8) for details on | ||||
.Sy readonly | importing pools). | ||||
property during import (see | .SS "Unsupported features" | ||||
.Xr zpool 8 | .LP | ||||
for details on importing pools). | |||||
.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 | ||||
named | named \fIunsupported@feature_guid\fR will indicate why the import was allowed | ||||
.Sy unsupported@feature_guid | despite the unsupported feature. Possible values for this property are: | ||||
will indicate why the import was allowed despite the unsupported feature. | |||||
Possible values for this property are: | .sp | ||||
.Bl -tag -width "XXXXXXXX" | .ne 2 | ||||
.It Sy inactive | .na | ||||
The feature is in the | \fB\fBinactive\fR\fR | ||||
.Sy enabled | .ad | ||||
state and therefore the pool's on\-disk format is still compatible with | .RS 12n | ||||
software that does not support this feature. | The feature is in the \fBenabled\fR state and therefore the pool's on\-disk | ||||
.It Sy readonly | format is still compatible with software that does not support this feature. | ||||
.RE | |||||
.sp | |||||
.ne 2 | |||||
.na | |||||
\fB\fBreadonly\fR\fR | |||||
.ad | |||||
.RS 12n | |||||
The feature is read\-only compatible and the pool has been imported in | The feature is read\-only compatible and the pool has been imported in | ||||
read\-only mode. | read\-only mode. | ||||
.El | .RE | ||||
.Ss Feature dependencies | |||||
.SS "Feature dependencies" | |||||
.LP | |||||
Some features depend on other features being enabled in order to function | Some features depend on other features being enabled in order to function | ||||
properly. | properly. Enabling a feature will automatically enable any features it | ||||
Enabling a feature will automatically enable any features it depends on. | depends on. | ||||
.Sh FEATURES | .SH FEATURES | ||||
.LP | |||||
The following features are supported on this system: | The following features are supported on this system: | ||||
.Bl -tag -width "XXXXXXXX" | .sp | ||||
.It Sy async_destroy | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:async_destroy" | .na | ||||
.It GUID Ta com.delphix:async_destroy | \fB\fBasync_destroy\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .ad | ||||
.It DEPENDENCIES Ta none | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
GUID com.delphix:async_destroy | |||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES none | |||||
.TE | |||||
Destroying a file system requires traversing all of its data in order to | Destroying a file system requires traversing all of its data in order to | ||||
return its used space to the pool. | return its used space to the pool. Without \fBasync_destroy\fR the file system | ||||
Without | is not fully removed until all space has been reclaimed. If the destroy | ||||
.Sy async_destroy | operation is interrupted by a reboot or power outage the next attempt to open | ||||
the file system is not fully removed until all space has been reclaimed. | the pool will need to complete the destroy operation synchronously. | ||||
If the destroy operation is interrupted by a reboot or power outage the next | |||||
attempt to open the pool will need to complete the destroy operation | When \fBasync_destroy\fR is enabled the file system's data will be reclaimed | ||||
synchronously. | by a background process, allowing the destroy operation to complete without | ||||
.Pp | traversing the entire file system. The background process is able to resume | ||||
When | interrupted destroys after the pool has been opened, eliminating the need | ||||
.Sy async_destroy | to finish interrupted destroys as part of the open operation. The amount | ||||
is enabled the file system's data will be reclaimed by a background process, | of space remaining to be reclaimed by the background process is available | ||||
allowing the destroy operation to complete without traversing the entire file | through the \fBfreeing\fR property. | ||||
system. | |||||
The background process is able to resume interrupted destroys after the pool | This feature is only \fBactive\fR while \fBfreeing\fR is non\-zero. | ||||
has been opened, eliminating the need to finish interrupted destroys as part | .RE | ||||
of the open operation. | |||||
The amount of space remaining to be reclaimed by the background process is | .sp | ||||
available through the | .ne 2 | ||||
.Sy freeing | .na | ||||
property. | \fB\fBempty_bpobj\fR\fR | ||||
.Pp | .ad | ||||
This feature is only | .RS 4n | ||||
.Sy active | .TS | ||||
while | l l . | ||||
.Sy freeing | GUID com.delphix:empty_bpobj | ||||
is non\-zero. | READ\-ONLY COMPATIBLE yes | ||||
.It Sy empty_bpobj | DEPENDENCIES none | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:empty_bpobj" | .TE | ||||
.It GUID Ta com.delphix:empty_bpobj | |||||
.It READ\-ONLY COMPATIBLE Ta yes | This feature increases the performance of creating and using a large | ||||
.It DEPENDENCIES Ta none | number of snapshots of a single filesystem or volume, and also reduces | ||||
.El | the disk space required. | ||||
.Pp | |||||
This feature increases the performance of creating and using a large number | When there are many snapshots, each snapshot uses many Block Pointer | ||||
of snapshots of a single filesystem or volume, and also reduces the disk | Objects (bpobj's) to track blocks associated with that snapshot. | ||||
space required. | However, in common use cases, most of these bpobj's are empty. This | ||||
.Pp | feature allows us to create each bpobj on-demand, thus eliminating the | ||||
When there are many snapshots, each snapshot uses many Block Pointer Objects | |||||
.Pq 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. | empty bpobjs. | ||||
.Pp | |||||
This feature is | This feature is \fBactive\fR while there are any filesystems, volumes, | ||||
.Sy active | or snapshots which were created after enabling this feature. | ||||
while there are any filesystems, volumes, or snapshots which were created | .RE | ||||
after enabling this feature. | |||||
.It Sy filesystem_limits | .sp | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.joyent:filesystem_limits" | .ne 2 | ||||
.It GUID Ta com.joyent:filesystem_limits | .na | ||||
.It READ\-ONLY COMPATIBLE Ta yes | \fB\fBfilesystem_limits\fR\fR | ||||
.It DEPENDENCIES Ta extensible_dataset | .ad | ||||
.El | .RS 4n | ||||
.Pp | .TS | ||||
This feature enables filesystem and snapshot limits. | l l . | ||||
These limits can be used | GUID com.joyent:filesystem_limits | ||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES extensible_dataset | |||||
.TE | |||||
This feature enables filesystem and snapshot limits. These limits can be used | |||||
to control how many filesystems and/or snapshots can be created at the point in | to control how many filesystems and/or snapshots can be created at the point in | ||||
the tree on which the limits are set. | the tree on which the limits are set. | ||||
.Pp | |||||
This feature is | This feature is \fBactive\fR once either of the limit properties has been | ||||
.Sy active | set on a dataset. Once activated the feature is never deactivated. | ||||
once either of the limit properties has been | .RE | ||||
set on a dataset. | |||||
Once activated the feature is never deactivated. | .sp | ||||
.It Sy lz4_compress | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:lz4_compress" | .na | ||||
.It GUID Ta org.illumos:lz4_compress | \fB\fBlz4_compress\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta no | .ad | ||||
.It DEPENDENCIES Ta none | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
.Sy lz4 | GUID org.illumos:lz4_compress | ||||
is a high-performance real-time compression algorithm that | READ\-ONLY COMPATIBLE no | ||||
DEPENDENCIES none | |||||
.TE | |||||
\fBlz4\fR is a high-performance real-time compression algorithm that | |||||
features significantly faster compression and decompression as well as a | features significantly faster compression and decompression as well as a | ||||
higher compression ratio than the older | higher compression ratio than the older \fBlzjb\fR compression. | ||||
.Sy lzjb | Typically, \fBlz4\fR compression is approximately 50% faster on | ||||
compression. | |||||
Typically, | |||||
.Sy lz4 | |||||
compression is approximately 50% faster on | |||||
compressible data and 200% faster on incompressible data than | compressible data and 200% faster on incompressible data than | ||||
.Sy lzjb . | \fBlzjb\fR. It is also approximately 80% faster on decompression, while | ||||
It is also approximately 80% faster on decompression, while | |||||
giving approximately 10% better compression ratio. | giving approximately 10% better compression ratio. | ||||
.Pp | |||||
When the | When the \fBlz4_compress\fR feature is set to \fBenabled\fR, the | ||||
.Sy lz4_compress | administrator can turn on \fBlz4\fR compression on any dataset on the | ||||
feature is set to | pool using the \fBzfs\fR(8) command. Also, all newly written metadata | ||||
.Sy enabled , | will be compressed with \fBlz4\fR algorithm. Since this feature is not | ||||
the | read-only compatible, this operation will render the pool unimportable | ||||
administrator can turn on | on systems without support for the \fBlz4_compress\fR feature. Booting | ||||
.Sy lz4 | off of \fBlz4\fR-compressed root pools is supported. | ||||
compression on any dataset on the | |||||
pool using the | This feature becomes \fBactive\fR as soon as it is enabled and will | ||||
.Xr zfs 8 | never return to being \fBenabled\fR. | ||||
command. | .RE | ||||
Also, all newly written metadata | |||||
will be compressed with | .sp | ||||
.Sy lz4 | .ne 2 | ||||
algorithm. | .na | ||||
Since this feature is not read-only compatible, this | \fB\fBspacemap_histogram\fR\fR | ||||
operation will render the pool unimportable on systems without support | .ad | ||||
for the | .RS 4n | ||||
.Sy lz4_compress | .TS | ||||
feature. | l l . | ||||
Booting off of | GUID com.delphix:spacemap_histogram | ||||
.Sy lz4 | READ\-ONLY COMPATIBLE yes | ||||
-compressed root pools is supported. | DEPENDENCIES none | ||||
.Pp | .TE | ||||
This feature becomes | |||||
.Sy active | This features allows ZFS to maintain more information about how free space | ||||
as soon as it is enabled and will | is organized within the pool. If this feature is \fBenabled\fR, ZFS will | ||||
never return to being | set this feature to \fBactive\fR when a new space map object is created or | ||||
.Sy enabled . | an existing space map is upgraded to the new format. Once the feature is | ||||
.It Sy multi_vdev_crash_dump | \fBactive\fR, it will remain in that state until the pool is destroyed. | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.joyent:multi_vdev_crash_dump" | .RE | ||||
.It GUID Ta com.joyent:multi_vdev_crash_dump | |||||
.It READ\-ONLY COMPATIBLE Ta no | .sp | ||||
.It DEPENDENCIES Ta none | .ne 2 | ||||
.El | .na | ||||
.Pp | \fB\fBmulti_vdev_crash_dump\fR\fR | ||||
.ad | |||||
.RS 4n | |||||
.TS | |||||
l l . | |||||
GUID com.joyent:multi_vdev_crash_dump | |||||
READ\-ONLY COMPATIBLE no | |||||
DEPENDENCIES none | |||||
.TE | |||||
This feature allows a dump device to be configured with a pool comprised | This feature allows a dump device to be configured with a pool comprised | ||||
of multiple vdevs. | of multiple vdevs. Those vdevs may be arranged in any mirrored or raidz | ||||
Those vdevs may be arranged in any mirrored or raidz | |||||
configuration. | configuration. | ||||
.\" TODO: this is not yet supported on FreeBSD. | |||||
.\" .Pp | Under FreeBSD this feature is registered for compatibility but not used. | ||||
.\" When the | New pools created under FreeBSD will have the feature \fBenabled\fR but | ||||
.\" .Sy multi_vdev_crash_dump | will never transition to \fB\fBactive\fR. Existing pools | ||||
.\" feature is set to | where this feature is \fB\fBactive\fR can be imported. | ||||
.\" .Sy enabled , | .RE | ||||
.\" the administrator can use the | |||||
.\" .Xr dumpon 8 | .sp | ||||
.\" command to configure a | .ne 2 | ||||
.\" dump device on a pool comprised of multiple vdevs. | .na | ||||
.It Sy spacemap_histogram | \fB\fBextensible_dataset\fR\fR | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:spacemap_histogram" | .ad | ||||
.It GUID Ta com.delphix:spacemap_histogram | .RS 4n | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .TS | ||||
.It DEPENDENCIES Ta none | l l . | ||||
.El | GUID com.delphix:extensible_dataset | ||||
.Pp | READ\-ONLY COMPATIBLE no | ||||
This features allows ZFS to maintain more information about how free space | DEPENDENCIES none | ||||
is organized within the pool. | .TE | ||||
If this feature is | |||||
.Sy enabled , | |||||
ZFS will | |||||
set this feature to | |||||
.Sy active | |||||
when a new space map object is created or | |||||
an existing space map is upgraded to the new format. | |||||
Once the feature is | |||||
.Sy active , | |||||
it will remain in that state until the pool is destroyed. | |||||
.It Sy extensible_dataset | |||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:extensible_dataset" | |||||
.It GUID Ta com.delphix:extensible_dataset | |||||
.It READ\-ONLY COMPATIBLE Ta no | |||||
.It DEPENDENCIES Ta none | |||||
.El | |||||
.Pp | |||||
This feature allows more flexible use of internal ZFS data structures, | This feature allows more flexible use of internal ZFS data structures, | ||||
and exists for other features to depend on. | and exists for other features to depend on. | ||||
.Pp | |||||
This feature will be | This feature will be \fBactive\fR when the first dependent feature uses it, | ||||
.Sy active | and will be returned to the \fBenabled\fR state when all datasets that use | ||||
when the first dependent feature uses it, | |||||
and will be returned to the | |||||
.Sy enabled | |||||
state when all datasets that use | |||||
this feature are destroyed. | this feature are destroyed. | ||||
.It Sy bookmarks | |||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:bookmarks" | .RE | ||||
.It GUID Ta com.delphix:bookmarks | |||||
.It READ\-ONLY COMPATIBLE Ta yes | .sp | ||||
.It DEPENDENCIES Ta extensible_dataset | .ne 2 | ||||
.El | .na | ||||
.Pp | \fB\fBbookmarks\fR\fR | ||||
This feature enables use of the | .ad | ||||
.Nm zfs | .RS 4n | ||||
.Cm bookmark | .TS | ||||
subcommand. | l l . | ||||
.Pp | GUID com.delphix:bookmarks | ||||
This feature is | READ\-ONLY COMPATIBLE yes | ||||
.Sy active | DEPENDENCIES extensible_dataset | ||||
while any bookmarks exist in the pool. | .TE | ||||
This feature enables use of the \fBzfs bookmark\fR subcommand. | |||||
This feature is \fBactive\fR while any bookmarks exist in the pool. | |||||
All bookmarks in the pool can be listed by running | All bookmarks in the pool can be listed by running | ||||
.Nm zfs | \fBzfs list -t bookmark -r \fIpoolname\fR\fR. | ||||
.Cm list | |||||
.Fl t No bookmark Fl r Ar poolname . | .RE | ||||
.It Sy enabled_txg | |||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:enabled_txg" | .sp | ||||
.It GUID Ta com.delphix:enabled_txg | .ne 2 | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .na | ||||
.It DEPENDENCIES Ta none | \fB\fBenabled_txg\fR\fR | ||||
.El | .ad | ||||
.Pp | .RS 4n | ||||
.TS | |||||
l l . | |||||
GUID com.delphix:enabled_txg | |||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES none | |||||
.TE | |||||
Once this feature is enabled ZFS records the transaction group number | Once this feature is enabled ZFS records the transaction group number | ||||
in which new features are enabled. | in which new features are enabled. This has no user-visible impact, | ||||
This has no user-visible impact, | |||||
but other features may depend on this feature. | but other features may depend on this feature. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR as soon as it is enabled and will | ||||
.Sy active | never return to being \fBenabled\fR. | ||||
as soon as it is enabled and will | |||||
never return to being | .RE | ||||
.Sy enabled . | |||||
.It Sy hole_birth | .sp | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:hole_birth" | .ne 2 | ||||
.It GUID Ta com.delphix:hole_birth | .na | ||||
.It READ\-ONLY COMPATIBLE Ta no | \fB\fBhole_birth\fR\fR | ||||
.It DEPENDENCIES Ta enabled_txg | .ad | ||||
.El | .RS 4n | ||||
.Pp | .TS | ||||
This feature improves performance of incremental sends | l l . | ||||
.Pq Dq zfs send -i | GUID com.delphix:hole_birth | ||||
and receives for objects with many holes. | READ\-ONLY COMPATIBLE no | ||||
The most common case of | DEPENDENCIES enabled_txg | ||||
.TE | |||||
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. | hole-filled objects is zvols. | ||||
.Pp | |||||
An incremental send stream from snapshot | An incremental send stream from snapshot \fBA\fR to snapshot \fBB\fR | ||||
.Sy A | contains information about every block that changed between \fBA\fR and | ||||
to snapshot | \fBB\fR. Blocks which did not change between those snapshots can be | ||||
.Sy B | |||||
contains information about every block that changed between | |||||
.Sy A | |||||
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 | 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 'block birth time', but birth times are not recorded for holes (blocks | ||||
.Pq blocks filled only with zeroes . | filled only with zeroes). Since holes created after \fBA\fR cannot be | ||||
Since holes created after | distinguished from holes created before \fBA\fR, information about every | ||||
.Sy A | |||||
cannot be | |||||
distinguished from holes created before | |||||
.Sy A , | |||||
information about every | |||||
hole in the entire filesystem or zvol is included in the send stream. | hole in the entire filesystem or zvol is included in the send stream. | ||||
.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 | ||||
However, when | incrementally replicating filesystems or zvols with many holes (for | ||||
incrementally replicating filesystems or zvols with many holes | example a zvol formatted with another filesystem) a lot of time will | ||||
.Pq for example a zvol formatted with another filesystem | |||||
a lot of time will | |||||
be spent sending and receiving unnecessary information about holes that | be spent sending and receiving unnecessary information about holes that | ||||
already exist on the receiving side. | already exist on the receiving side. | ||||
.Pp | |||||
Once the | Once the \fBhole_birth\fR feature has been enabled the block birth times | ||||
.Sy hole_birth | of all new holes will be recorded. Incremental sends between snapshots | ||||
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 | created after this feature is enabled will use this new metadata to avoid | ||||
sending information about holes that already exist on the receiving side. | sending information about holes that already exist on the receiving side. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR as soon as it is enabled and will | ||||
.Sy active | never return to being \fBenabled\fR. | ||||
as soon as it is enabled and will | |||||
never return to being | .RE | ||||
.Sy enabled . | |||||
.It Sy embedded_data | .sp | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:embedded_data" | .ne 2 | ||||
.It GUID Ta com.delphix:embedded_data | .na | ||||
.It READ\-ONLY COMPATIBLE Ta no | \fB\fBembedded_data\fR\fR | ||||
.It DEPENDENCIES Ta none | .ad | ||||
.El | .RS 4n | ||||
.Pp | .TS | ||||
l l . | |||||
GUID com.delphix:embedded_data | |||||
READ\-ONLY COMPATIBLE no | |||||
DEPENDENCIES none | |||||
.TE | |||||
This feature improves the performance and compression ratio of | This feature improves the performance and compression ratio of | ||||
highly-compressible blocks. | highly-compressible blocks. Blocks whose contents can compress to 112 bytes | ||||
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 | |||||
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 | stored in the block "pointer" itself (a misnomer in this case, as it contains | ||||
.Po a misnomer in this case, as it contains | the compresseed data, rather than a pointer to its location on disk). Thus | ||||
the compressed data, rather than a pointer to its location on disk | the space of the block (one sector, typically 512 bytes or 4KB) is saved, | ||||
.Pc . | |||||
Thus | |||||
the space of the block | |||||
.Pq one sector, typically 512 bytes or 4KB | |||||
is saved, | |||||
and no additional i/o is needed to read and write the data block. | and no additional i/o is needed to read and write the data block. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR as soon as it is enabled and will | ||||
.Sy active | never return to being \fBenabled\fR. | ||||
as soon as it is enabled and will | |||||
never return to being | .RE | ||||
.Sy enabled . | .sp | ||||
.It Sy zpool_checkpoint | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:zpool_checkpoint" | .na | ||||
.It GUID Ta com.delphix:zpool_checkpoint | \fB\fBdevice_removal\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .ad | ||||
.It DEPENDENCIES Ta none | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
This feature enables the "zpool checkpoint" subcommand that can | GUID com.delphix:device_removal | ||||
checkpoint the state of the pool at the time it was issued and later | READ\-ONLY COMPATIBLE no | ||||
rewind back to it or discard it. | DEPENDENCIES none | ||||
.Pp | .TE | ||||
This feature becomes | |||||
.Sy active | |||||
when the "zpool checkpoint" command is used to checkpoint the pool. | |||||
The feature will only return back to being | |||||
.Sy enabled | |||||
when the pool is rewound or the checkpoint has been discarded. | |||||
.It Sy device_removal | |||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:device_removal" | |||||
.It GUID Ta com.delphix:device_removal | |||||
.It READ\-ONLY COMPATIBLE Ta no | |||||
.It DEPENDENCIES Ta none | |||||
.El | |||||
.Pp | |||||
This feature enables the "zpool remove" subcommand to remove top-level | This feature enables the "zpool remove" subcommand to remove top-level | ||||
vdevs, evacuating them to reduce the total size of the pool. | vdevs, evacuating them to reduce the total size of the pool. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR when the "zpool remove" command is used | ||||
.Sy active | on a top-level vdev, and will never return to being \fBenabled\fR. | ||||
when the "zpool remove" command is used | |||||
on a top-level vdev, and will never return to being | .RE | ||||
.Sy enabled . | .sp | ||||
.It Sy obsolete_counts | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:obsolete_counts" | .na | ||||
.It GUID Ta com.delphix:obsolete_counts | \fB\fBobsolete_counts\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .ad | ||||
.It DEPENDENCIES Ta device_removal | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
GUID com.delphix:obsolete_counts | |||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES device_removal | |||||
.TE | |||||
This feature is an enhancement of device_removal, which will over time | This feature is an enhancement of device_removal, which will over time | ||||
reduce the memory used to track removed devices. When indirect blocks | reduce the memory used to track removed devices. When indirect blocks | ||||
are freed or remapped, we note that their part of the indirect mapping | are freed or remapped, we note that their part of the indirect mapping | ||||
is "obsolete", i.e. no longer needed. See also the "zfs remap" | is "obsolete", i.e. no longer needed. See also the \fBzfs remap\fR | ||||
subcommand in | subcommand in \fBzfs\fR(8). | ||||
.Xr zfs 8 . | |||||
This feature becomes | This feature becomes \fBactive\fR when the "zpool remove" command is | ||||
.Sy active | used on a top-level vdev, and will never return to being \fBenabled\fR. | ||||
when the "zpool remove" command is | |||||
used on a top-level vdev, and will never return to being | .RE | ||||
.Sy enabled . | .sp | ||||
.It Sy spacemap_v2 | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:spacemap_v2" | .na | ||||
.It GUID Ta com.delphix:spacemap_v2 | \fB\fBzpool_checkpoint\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta yes | .ad | ||||
.It DEPENDENCIES Ta none | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
GUID com.delphix:zpool_checkpoint | |||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES none | |||||
.TE | |||||
This feature enables the "zpool checkpoint" subcommand that can | |||||
checkpoint the state of the pool at the time it was issued and later | |||||
rewind back to it or discard it. | |||||
This feature becomes \fBactive\fR when the "zpool checkpoint" command | |||||
is used to checkpoint the pool. | |||||
The feature will only return back to being \fBenabled\fR when the pool | |||||
is rewound or the checkpoint has been discarded. | |||||
.RE | |||||
.sp | |||||
.ne 2 | |||||
.na | |||||
\fB\fBspacemap_v2\fR\fR | |||||
.ad | |||||
.RS 4n | |||||
.TS | |||||
l l . | |||||
GUID com.delphix:spacemap_v2 | |||||
READ\-ONLY COMPATIBLE yes | |||||
DEPENDENCIES none | |||||
.TE | |||||
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 (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. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR once it is \fBenabled\fR, and never | ||||
.Sy active | returns back to being \fBenabled\fR. | ||||
as soon as it is enabled and will | |||||
never return to being | .RE | ||||
.Sy enabled . | .sp | ||||
.It Sy large_blocks | .ne 2 | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "org.open-zfs:large_block" | .na | ||||
.It GUID Ta org.open-zfs:large_block | \fB\fBlarge_blocks\fR\fR | ||||
.It READ\-ONLY COMPATIBLE Ta no | .ad | ||||
.It DEPENDENCIES Ta extensible_dataset | .RS 4n | ||||
.El | .TS | ||||
.Pp | l l . | ||||
The | GUID org.open-zfs:large_block | ||||
.Sy large_block | READ\-ONLY COMPATIBLE no | ||||
feature allows the record size on a dataset to be | DEPENDENCIES extensible_dataset | ||||
.TE | |||||
The \fBlarge_block\fR feature allows the record size on a dataset to be | |||||
set larger than 128KB. | set larger than 128KB. | ||||
.Pp | |||||
This feature becomes | This feature becomes \fBactive\fR once a \fBrecordsize\fR property has been | ||||
.Sy active | set larger than 128KB, and will return to being \fBenabled\fR once all | ||||
once a | filesystems that have ever had their recordsize larger than 128KB are destroyed. | ||||
.Sy recordsize | .RE | ||||
property has been set larger than 128KB, and will return to being | |||||
.Sy enabled | .sp | ||||
once all filesystems that have ever had their recordsize larger than 128KB | .ne 2 | ||||
are destroyed. | .na | ||||
.Pp | \fB\fBsha512\fR\fR | ||||
Please note that booting from datasets that have recordsize greater than | .ad | ||||
128KB is | .RS 4n | ||||
.Em NOT | .TS | ||||
supported by the | l l . | ||||
.Fx | GUID org.illumos:sha512 | ||||
boot loader. | READ\-ONLY COMPATIBLE no | ||||
.It Sy sha512 | DEPENDENCIES extensible_dataset | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:sha512" | .TE | ||||
.It GUID Ta org.illumos:sha512 | |||||
.It READ\-ONLY COMPATIBLE Ta no | This feature enables the use of the SHA-512/256 truncated hash algorithm | ||||
.It DEPENDENCIES Ta none | (FIPS 180-4) for checksum and dedup. The native 64-bit arithmetic of | ||||
.El | SHA-512 provides an approximate 50% performance boost over SHA-256 on | ||||
.Pp | 64-bit hardware and is thus a good minimum-change replacement candidate | ||||
The | for systems where hash performance is important, but these systems | ||||
.Sy sha512 | cannot for whatever reason utilize the faster \fBskein\fR and | ||||
feature enables the use of the SHA-512/256 truncated hash algorithm | \fBedonr\fR algorithms. | ||||
.Pq FIPS 180-4 | |||||
for checksum and dedup. | When the \fBsha512\fR feature is set to \fBenabled\fR, the administrator | ||||
The native 64-bit arithmetic of SHA-512 provides an approximate 50% | can turn on the \fBsha512\fR checksum on any dataset using the | ||||
performance boost over SHA-256 on 64-bit hardware and is thus a good | \fBzfs set checksum=sha512\fR command. This feature becomes | ||||
minimum-change replacement candidate for systems where hash performance is | \fBactive\fR once a \fBchecksum\fR property has been set to \fBsha512\fR, | ||||
important, but these systems cannot for whatever reason utilize the faster | and will return to being \fBenabled\fR once all filesystems that have | ||||
.Sy skein | ever had their checksum set to \fBsha512\fR are destroyed. | ||||
algorithms. | |||||
.Pp | Booting off of pools utilizing SHA-512/256 is supported. | ||||
When the | |||||
.Sy sha512 | .RE | ||||
feature is set to | |||||
.Sy enabled , | .sp | ||||
the administrator can turn on the | .ne 2 | ||||
.Sy sha512 | .na | ||||
checksum on any dataset using the | \fB\fBskein\fR\fR | ||||
.Dl # zfs set checksum=sha512 Ar dataset | .ad | ||||
command. | .RS 4n | ||||
This feature becomes | .TS | ||||
.Sy active | l l . | ||||
once a | GUID org.illumos:skein | ||||
.Sy checksum | READ\-ONLY COMPATIBLE no | ||||
property has been set to | DEPENDENCIES extensible_dataset | ||||
.Sy sha512 , | .TE | ||||
and will return to being | |||||
.Sy enabled | This feature enables the use of the Skein hash algorithm for checksum | ||||
once all filesystems that have ever had their checksum set to | and dedup. Skein is a high-performance secure hash algorithm that was a | ||||
.Sy sha512 | finalist in the NIST SHA-3 competition. It provides a very high security | ||||
are destroyed. | margin and high performance on 64-bit hardware (80% faster than | ||||
.It Sy skein | SHA-256). This implementation also utilizes the new salted checksumming | ||||
.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:skein" | functionality in ZFS, which means that the checksum is pre-seeded with a | ||||
.It GUID Ta org.illumos:skein | secret 256-bit random key (stored on the pool) before being fed the data | ||||
.It READ\-ONLY COMPATIBLE Ta no | block to be checksummed. Thus the produced checksums are unique to a | ||||
.It DEPENDENCIES Ta none | given pool, preventing hash collision attacks on systems with dedup. | ||||
.El | |||||
.Pp | When the \fBskein\fR feature is set to \fBenabled\fR, the administrator | ||||
The | can turn on the \fBskein\fR checksum on any dataset using the | ||||
.Sy skein | \fBzfs set checksum=skein\fR command. This feature becomes | ||||
feature enables the use of the Skein hash algorithm for checksum and dedup. | \fBactive\fR once a \fBchecksum\fR property has been set to \fBskein\fR, | ||||
Skein is a high-performance secure hash algorithm that was a finalist in the | and will return to being \fBenabled\fR once all filesystems that have | ||||
NIST SHA-3 competition. | ever had their checksum set to \fBskein\fR are destroyed. | ||||
It provides a very high security margin and high performance on 64-bit hardware | |||||
.Pq 80% faster than SHA-256 . | Booting off of pools using \fBskein\fR is supported. | ||||
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 | .SH "SEE ALSO" | ||||
key | \fBzfs\fR(8), \fBzpool\fR(8) | ||||
.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 | |||||
When the | |||||
.Sy skein | |||||
feature is set to | |||||
.Sy enabled , | |||||
the administrator can turn on the | |||||
.Sy skein | |||||
checksum on any dataset using the | |||||
.Dl # zfs set checksum=skein Ar dataset | |||||
command. | |||||
This feature becomes | |||||
.Sy active | |||||
once a | |||||
.Sy checksum | |||||
property has been set to | |||||
.Sy skein , | |||||
and will return to being | |||||
.Sy enabled | |||||
once all filesystems that have ever had their checksum set to | |||||
.Sy skein | |||||
are destroyed. | |||||
.El | |||||
.Sh SEE ALSO | |||||
.Xr zpool 8 | |||||
.Sh AUTHORS | |||||
This manual page is a | |||||
.Xr mdoc 7 | |||||
reimplementation of the | |||||
.Tn illumos | |||||
manual page | |||||
.Em zpool-features(5) , | |||||
modified and customized for | |||||
.Fx | |||||
and licensed under the Common Development and Distribution License | |||||
.Pq Tn CDDL . | |||||
.Pp | |||||
The | |||||
.Xr mdoc 7 | |||||
implementation of this manual page was initially written by | |||||
.An Martin Matuska Aq mm@FreeBSD.org . |