aboutsummaryrefslogtreecommitdiff
path: root/sys/contrib/openzfs/man
diff options
context:
space:
mode:
authorMartin Matuska <mm@FreeBSD.org>2021-02-18 14:17:31 +0000
committerMartin Matuska <mm@FreeBSD.org>2021-02-18 14:19:35 +0000
commitee36e25a86cbe2a9474c1d61f2c4b450da8ef952 (patch)
tree1f9e503fe3f154ff3ebc542840b892419ad85314 /sys/contrib/openzfs/man
parentfa2528ac643519072c498b483d0dcc1fa5d99bc1 (diff)
parent62ceb3c592a54fc54d9cb3beee91906979c3df14 (diff)
downloadsrc-ee36e25a86cbe2a9474c1d61f2c4b450da8ef952.tar.gz
src-ee36e25a86cbe2a9474c1d61f2c4b450da8ef952.zip
zfs: merge OpenZFS master-bf156c966
Notable upstream changes: bf156c966 Remove unused abd_alloc_scatter_offset_chunkcnt 658fb8020 Add "compatibility" property for zpool feature sets This update introduces a new pool property called "compatibility" that can be used to enable a limited set of pool features on pool creation and "stick" to it, so the "zpool upgrade" does not accidentally enable features that are not desired. The value of this property may then be changed later. See zpool-features(5) for more information about the "compatibility" pool property. Obtained from: OpenZFS MFC after: 2 weeks
Diffstat (limited to 'sys/contrib/openzfs/man')
-rw-r--r--sys/contrib/openzfs/man/man5/zpool-features.559
-rw-r--r--sys/contrib/openzfs/man/man8/zpool-create.816
-rw-r--r--sys/contrib/openzfs/man/man8/zpool-upgrade.816
-rw-r--r--sys/contrib/openzfs/man/man8/zpoolprops.819
4 files changed, 104 insertions, 6 deletions
diff --git a/sys/contrib/openzfs/man/man5/zpool-features.5 b/sys/contrib/openzfs/man/man5/zpool-features.5
index 2e5ab4c37642..c56b31e2d715 100644
--- a/sys/contrib/openzfs/man/man5/zpool-features.5
+++ b/sys/contrib/openzfs/man/man5/zpool-features.5
@@ -16,6 +16,7 @@
.\" Portions Copyright [yyyy] [name of copyright owner]
.\" Copyright (c) 2019, Klara Inc.
.\" Copyright (c) 2019, Allan Jude
+.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.TH ZPOOL-FEATURES 5 "Aug 24, 2020" OpenZFS
.SH NAME
zpool\-features \- ZFS pool feature descriptions
@@ -26,7 +27,8 @@ 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 \fBupgrade\fR subcommand of the
zpool(8) command, or set the \fBfeature@\fR\fIfeature_name\fR property
-to \fBenabled\fR.
+to \fBenabled\fR. Please also see the \fB"Compatibility feature sets"\fR
+section for information on how sets of features may be enabled together.
.sp
.LP
The pool format does not affect file system version compatibility or the ability
@@ -140,6 +142,61 @@ read\-only mode.
Some features depend on other features being enabled in order to function
properly. Enabling a feature will automatically enable any features it
depends on.
+
+.SS "Compatibility feature sets"
+.sp
+.LP
+It is sometimes necessary for a pool to maintain compatibility with a
+specific on\-disk format, by enabling and disabling particular features. The
+\fBcompatibility\fR feature facilitates this by allowing feature sets to
+be read from text files. When set to \fBoff\fR (the default); compatibility
+feature sets are disabled (ie: all features are enabled); when set to
+\fBlegacy\fR; no features are enabled. When set to a comma\-separated list
+of filenames (each filename may either be an absolute path, or relative to
+\fB/etc/zfs/compatibility.d\fR or \fB/usr/share/zfs/compatibility.d\fR)
+the lists of requested features are read from those files, separated by
+whitespace and/or commas. Only features present in all files are enabled.
+.LP
+Simple sanity checks are applied to the files; they must be between 1 and
+16,384 bytes in size, and must end with a newline character.
+.LP
+The requested features are applied when a pool is created using
+\fBzpool create \-o compatibility=...\fR and controls which features are
+enabled when using \fBzpool upgrade\fR. \fBzpool status\fR
+will not show a warning about disabled features which are not part
+of the requested feature set.
+.LP
+By convention, compatibility files in \fB/usr/share/zfs/compatibility.d\fR
+are provided by the distribution package, and include feature sets
+supported by important versions of popular distribtions, and feature
+sets commonly supported at the start of each year. Compatibility files
+in \fB/etc/zfs/compatibility.d\fR, if present, will take precedence over
+files with the same name in \fB/usr/share/zfs/compatibility.d\fR.
+.LP
+Compatibility files may include comments; any text from \fB#\fR to the end
+of the line is ignored.
+.LP
+\fBExample:\fR
+.EX
+# \fBcat /usr/share/zfs/compatibility.d/grub2\fR
+# Features which are supported by GRUB2
+async_destroy
+bookmarks
+embedded_data
+empty_bpobj
+enabled_txg
+extensible_dataset
+filesystem_limits
+hole_birth
+large_blocks
+lz4_compress
+spacemap_histogram
+
+# \fBzpool create \-o compatibility=grub2 bootpool vdev\fR
+.EE
+.LP
+See \fBzpool\-create(8)\fR and \fBzpool\-upgrade(8)\fR for more information
+on how these commands are affected by feature sets.
.SH FEATURES
.sp
.LP
diff --git a/sys/contrib/openzfs/man/man8/zpool-create.8 b/sys/contrib/openzfs/man/man8/zpool-create.8
index 7406a493e377..fe35ab8db3ea 100644
--- a/sys/contrib/openzfs/man/man8/zpool-create.8
+++ b/sys/contrib/openzfs/man/man8/zpool-create.8
@@ -26,6 +26,7 @@
.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
+.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\"
.Dd August 9, 2019
.Dt ZPOOL-CREATE 8
@@ -40,6 +41,7 @@
.Op Fl m Ar mountpoint
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc
+.Op Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ...
.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
.Ar pool vdev Ns ...
@@ -52,6 +54,7 @@
.Op Fl m Ar mountpoint
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
.Oo Fl o Ar feature@feature Ns = Ns Ar value Oc Ns ...
+.Op Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ...
.Oo Fl O Ar file-system-property Ns = Ns Ar value Oc Ns ...
.Op Fl R Ar root
.Op Fl t Ar tname
@@ -135,9 +138,14 @@ This can be overridden with the
.Fl m
option.
.Pp
-By default all supported features are enabled on the new pool unless the
+By default all supported features are enabled on the new pool. The
.Fl d
-option is specified.
+option or the
+.Fl o Ar compatibility
+property (eg:
+.Fl o Ar compatibility=2020
+) can be used to restrict the features that are enabled, so that the
+pool can be imported on other releases of the ZFS software.
.Bl -tag -width Ds
.It Fl d
Do not enable any features on the new pool.
@@ -179,6 +187,10 @@ Sets the given pool properties.
See the
.Xr zpoolprops
manual page for a list of valid properties that can be set.
+.It Fl o Ar compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ...
+Specifies compatibility feature sets. See
+.Xr zpool-features 5
+for more information about compatibility feature sets.
.It Fl o Ar feature@feature Ns = Ns Ar value
Sets the given pool feature. See the
.Xr zpool-features 5
diff --git a/sys/contrib/openzfs/man/man8/zpool-upgrade.8 b/sys/contrib/openzfs/man/man8/zpool-upgrade.8
index b9d023b22d3f..face5b138ff3 100644
--- a/sys/contrib/openzfs/man/man8/zpool-upgrade.8
+++ b/sys/contrib/openzfs/man/man8/zpool-upgrade.8
@@ -26,6 +26,7 @@
.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
+.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\"
.Dd August 9, 2019
.Dt ZPOOL-UPGRADE 8
@@ -54,7 +55,11 @@ formatted using a legacy ZFS version number.
These pools can continue to be used, but some features may not be available.
Use
.Nm zpool Cm upgrade Fl a
-to enable all features on all pools.
+to enable all features on all pools. (If a pool has specified compatibility
+feature sets using the
+.Fl o Ar compatibility
+property, only the features present in all requested compatibility sets will
+be enabled on that pool.)
.It Xo
.Nm zpool
.Cm upgrade
@@ -70,7 +75,11 @@ for a description of feature flags features supported by the current software.
.Op Fl V Ar version
.Fl a Ns | Ns Ar pool Ns ...
.Xc
-Enables all supported features on the given pool.
+Enables all supported features on the given pool. (If the pool has specified
+compatibility feature sets using the
+.Fl o Ar compatibility
+property, only the features present in all requested compatibility sets will be
+enabled.)
Once this is done, the pool will no longer be accessible on systems that do not
support feature flags.
See
@@ -79,7 +88,8 @@ for details on compatibility with systems that support feature flags, but do not
support all features enabled on the pool.
.Bl -tag -width Ds
.It Fl a
-Enables all supported features on all pools.
+Enables all supported features (from specified compatibility sets, if any) on all
+pools.
.It Fl V Ar version
Upgrade to the specified legacy version.
If the
diff --git a/sys/contrib/openzfs/man/man8/zpoolprops.8 b/sys/contrib/openzfs/man/man8/zpoolprops.8
index f78acaa46505..20e0d74421ae 100644
--- a/sys/contrib/openzfs/man/man8/zpoolprops.8
+++ b/sys/contrib/openzfs/man/man8/zpoolprops.8
@@ -26,6 +26,7 @@
.\" Copyright (c) 2018 George Melikov. All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright (c) 2017 Open-E, Inc. All Rights Reserved.
+.\" Copyright (c) 2021, Colm Buckley <colm@tuatha.org>
.\"
.Dd August 9, 2019
.Dt ZPOOLPROPS 8
@@ -285,6 +286,24 @@ A text string consisting of printable ASCII characters that will be stored
such that it is available even if the pool becomes faulted.
An administrator can provide additional information about a pool using this
property.
+.It Sy compatibility Ns = Ns Ar off | legacy | file Bq , Ns Ar file Ns ...
+Specifies that the pool maintain compatibility with specific feature sets.
+When set to
+.Sy off
+(or unset); compatibility is disabled (all features are enabled); when set to
+.Sy legacy Ns ;
+no features are enabled. When set to a comma-separated list of
+filenames (each filename may either be an absolute path, or relative to
+.Pa /etc/zfs/compatibility.d or Pa /usr/share/zfs/compatibility.d Ns )
+the lists of requested features are read from those files, separated by
+whitespace and/or commas. Only features present in all files are enabled.
+
+See
+.Xr zpool-features 5 Ns ,
+.Xr zpool-create 8
+and
+.Xr zpool-upgrade 8
+for more information on the operation of compatibility feature sets.
.It Sy dedupditto Ns = Ns Ar number
This property is deprecated and no longer has any effect.
.It Sy delegation Ns = Ns Sy on Ns | Ns Sy off