diff options
Diffstat (limited to 'cddl/contrib/opensolaris/cmd/zpool/zpool-features.7')
-rw-r--r-- | cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 b/cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 new file mode 100644 index 0000000..c1ac479 --- /dev/null +++ b/cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 @@ -0,0 +1,250 @@ +'\" te +.\" Copyright (c) 2012, Martin Matuska <mm@FreeBSD.org>. +.\" 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 by Delphix. All rights reserved. +.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. +.\" +.\" $FreeBSD$ +.\" +.Dd February 8, 2013 +.Dt ZPOOL-FEATURES 7 +.Os +.Sh NAME +.Nm zpool-features +.Nd ZFS pool feature descriptions +.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). +To enable a feature on a pool use the +.Cm upgrade +subcommand of the +.Xr zpool 8 +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 +to send file systems between pools. +.Pp +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 +.Sy active +on the pool. If the pool was created by another software version this set may +include unsupported features. +.Ss Identifying features +Every feature has a guid of the form +.Sy 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 features. +.Pp +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 +following the convention would result in name conflicts. +.Ss Feature states +Features can be in one of three states: +.Bl -tag -width "XXXXXXXX" +.It Sy 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 compatible, support is also required to +import the pool in read\-only mode (see "Read\-only compatibility"). +.It Sy 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 +.Sy active +state. +Some features may support returning to the +.Sy enabled +state after becoming +.Sy active . +See feature\-specific documentation for details. +.It Sy 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 +.Sy enabled +state. +Features cannot be disabled once they have been enabled. +.El +.Pp +The state of supported features is exposed through pool properties of the form +.Sy feature@short_name . +.Ss 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 +.Sy readonly +property during import (see +.Xr zpool 8 +for details on importing pools). +.Ss Unsupported features +For each unsupported feature enabled on an imported pool a pool property +named +.Sy unsupported@feature_guid +will indicate why the import was allowed despite the unsupported feature. +Possible values for this property are: +.Bl -tag -width "XXXXXXXX" +.It Sy inactive +The feature is in the +.Sy enabled +state and therefore the pool's on\-disk format is still compatible with +software that does not support this feature. +.It Sy readonly +The feature is read\-only compatible and the pool has been imported in +read\-only mode. +.El +.Ss 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. +.Sh FEATURES +The following features are supported on this system: +.Bl -tag -width "XXXXXXXX" +.It Sy async_destroy +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:async_destroy" +.It GUID Ta com.delphix:async_destroy +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +Destroying a file system requires traversing all of its data in order to +return its used space to the pool. +Without +.Sy async_destroy +the file system is not fully removed until all space has been reclaimed. +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 +synchronously. +.Pp +When +.Sy async_destroy +is enabled the file system's data will be reclaimed by a background process, +allowing the destroy operation 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 +.Sy freeing +property. +.Pp +This feature is only +.Sy active +while +.Sy freeing +is non\-zero. +.It Sy empty_bpobj +.Bl -column "READ\-ONLY COMPATIBLE" "com.delphix:empty_bpobj" +.It GUID Ta com.delphix:empty_bpobj +.It READ\-ONLY COMPATIBLE Ta yes +.It DEPENDENCIES Ta none +.El +.Pp +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. +.Pp +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. +.Pp +This feature is +.Sy active +while there are any filesystems, volumes, or snapshots which were created +after enabling this feature. +.It Sy lz4_compress +.Bl -column "READ\-ONLY COMPATIBLE" "org.illumos:lz4_compress" +.It GUID Ta org.illumos:lz4_compress +.It READ\-ONLY COMPATIBLE Ta no +.It DEPENDENCIES Ta none +.El +.Pp +.Sy 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 +.Sy lzjb +compression. +Typically, +.Sy lz4 +compression is approximately 50% faster on +compressible data and 200% faster on incompressible data than +.Sy lzjb . +It is also approximately 80% faster on decompression, while +giving approximately 10% better compression ratio. +.Pp +When the +.Sy lz4_compress +feature is set to +.Sy enabled , +the +administrator can turn on +.Sy lz4 +compression on any dataset on the +pool using the +.Xr zfs 8 +command. Please note that doing so will +immediately activate the +.Sy lz4_compress +feature on the underlying +pool (even before any data is written). Since this feature is not +read-only compatible, this operation will render the pool unimportable +on systems without support for the +.Sy lz4_compress +feature. At the +moment, this operation cannot be reversed. Booting off of +.Sy lz4 +-compressed root pools is supported. +.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 . |