From add6fbdfeed329cf035e6f6a34e95bb8ee21ca5d Mon Sep 17 00:00:00 2001 From: mm Date: Wed, 14 Nov 2012 01:16:29 +0000 Subject: Move zpool-features manual page from section 5 to section 7 and fix references Reported by: pluknet MFC after: 1 week --- .../contrib/opensolaris/cmd/zpool/zpool-features.5 | 206 --------------------- .../contrib/opensolaris/cmd/zpool/zpool-features.7 | 206 +++++++++++++++++++++ cddl/contrib/opensolaris/cmd/zpool/zpool.8 | 12 +- cddl/contrib/opensolaris/cmd/zpool/zpool_main.c | 6 +- cddl/sbin/zpool/Makefile | 2 +- 5 files changed, 216 insertions(+), 216 deletions(-) delete mode 100644 cddl/contrib/opensolaris/cmd/zpool/zpool-features.5 create mode 100644 cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 (limited to 'cddl') diff --git a/cddl/contrib/opensolaris/cmd/zpool/zpool-features.5 b/cddl/contrib/opensolaris/cmd/zpool/zpool-features.5 deleted file mode 100644 index 8c02325..0000000 --- a/cddl/contrib/opensolaris/cmd/zpool/zpool-features.5 +++ /dev/null @@ -1,206 +0,0 @@ -'\" te -.\" Copyright (c) 2012, Martin Matuska . -.\" 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. -.\" -.\" $FreeBSD$ -.\" -.Dd Aug 28, 2012 -.Dt ZPOOL-FEATURES 5 -.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. -.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 . 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..999212c --- /dev/null +++ b/cddl/contrib/opensolaris/cmd/zpool/zpool-features.7 @@ -0,0 +1,206 @@ +'\" te +.\" Copyright (c) 2012, Martin Matuska . +.\" 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. +.\" +.\" $FreeBSD$ +.\" +.Dd Aug 28, 2012 +.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. +.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 . diff --git a/cddl/contrib/opensolaris/cmd/zpool/zpool.8 b/cddl/contrib/opensolaris/cmd/zpool/zpool.8 index 88fc79b..0a4de1f 100644 --- a/cddl/contrib/opensolaris/cmd/zpool/zpool.8 +++ b/cddl/contrib/opensolaris/cmd/zpool/zpool.8 @@ -567,7 +567,7 @@ Total size of the storage pool. .It Sy unsupported@ Ns Ar feature_guid Information about unsupported features that are enabled on the pool. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details. .It Sy used Amount of storage space used within the pool. @@ -717,7 +717,7 @@ which moves .Ar feature_name to the enabled state. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details on feature states. .It Sy listsnaps Ns = Ns Cm on No | Cm off Controls whether information about snapshots associated with this pool is @@ -915,7 +915,7 @@ with the .Fl o option. See -.Xr zpool-features 5 +.Xr zpool-features 7 for details about feature properties. .It Xo .Fl o Ar property Ns = Ns Ar value @@ -1651,7 +1651,7 @@ Displays legacy .Tn ZFS versions supported by the current software. See -.Xr zpool-features.5 +.Xr zpool-features 7 for a description of feature flags features supported by the current software. .El .It Xo @@ -1665,7 +1665,7 @@ Enables all supported features on the given pool. Once this is done, the pool will no longer be accessible on systems that do not support feature flags. See -.Xr zpool-features.5 +.Xr zpool-features 7 for details on compatability with system sthat support feature flags, but do not support all features enabled on the pool. .Bl -tag -width indent @@ -1928,7 +1928,7 @@ Discarded approximately 29 seconds of transactions. .El .Sh SEE ALSO .Xr zfs 8 -.Xr zpool-features 5 +.Xr zpool-features 7 .Sh AUTHORS This manual page is a .Xr mdoc 7 diff --git a/cddl/contrib/opensolaris/cmd/zpool/zpool_main.c b/cddl/contrib/opensolaris/cmd/zpool/zpool_main.c index b57c816..3c2a625 100644 --- a/cddl/contrib/opensolaris/cmd/zpool/zpool_main.c +++ b/cddl/contrib/opensolaris/cmd/zpool/zpool_main.c @@ -345,7 +345,7 @@ usage(boolean_t requested) (void) fprintf(fp, "YES disabled | enabled | active\n"); (void) fprintf(fp, gettext("\nThe feature@ properties must be " - "appended with a feature name.\nSee zpool-features(5).\n")); + "appended with a feature name.\nSee zpool-features(7).\n")); } /* @@ -4170,7 +4170,7 @@ status_callback(zpool_handle_t *zhp, void *data) (void) printf(gettext("action: Enable all features using " "'zpool upgrade'. Once this is done,\n\tthe pool may no " "longer be accessible by software that does not support\n\t" - "the features. See zpool-features(5) for details.\n")); + "the features. See zpool-features(7) for details.\n")); break; case ZPOOL_STATUS_UNSUP_FEAT_READ: @@ -4630,7 +4630,7 @@ upgrade_list_disabled_cb(zpool_handle_t *zhp, void *arg) "pool may become incompatible with " "software\nthat does not support " "the feature. See " - "zpool-features(5) for " + "zpool-features(7) for " "details.\n\n")); (void) printf(gettext("POOL " "FEATURE\n")); diff --git a/cddl/sbin/zpool/Makefile b/cddl/sbin/zpool/Makefile index 327f6dc..b9d44b6 100644 --- a/cddl/sbin/zpool/Makefile +++ b/cddl/sbin/zpool/Makefile @@ -5,7 +5,7 @@ .PATH: ${.CURDIR}/../../../sys/cddl/contrib/opensolaris/common/zfs PROG= zpool -MAN= zpool.8 zpool-features.5 +MAN= zpool.8 zpool-features.7 SRCS= zpool_main.c zpool_vdev.c zpool_iter.c zpool_util.c zfs_comutil.c SRCS+= timestamp.c -- cgit v1.1