path: root/man
diff options
authorAlexander Motin <mav@FreeBSD.org>2018-03-28 18:12:06 +0000
committerAlexander Motin <mav@FreeBSD.org>2018-03-28 18:12:06 +0000
commitb8a528e092d48ccd7c1c475a62e14ad025872911 (patch)
tree0b757156f77b89ac62803e3291047001ff71e66b /man
parent6027cbd474d526fa8651b853f89d86f9dc346ba1 (diff)
9166 zfs storage pool checkpoint
illumos/illumos-gate@8671400134a11c848244896ca51a7db4d0f69da4 The idea of Storage Pool Checkpoint (aka zpool checkpoint) deals with exactly that. It can be thought of as a “pool-wide snapshot” (or a variation of extreme rewind that doesn’t corrupt your data). It remembers the entire state of the pool at the point that it was taken and the user can revert back to it later or discard it. Its generic use case is an administrator that is about to perform a set of destructive actions to ZFS as part of a critical procedure. She takes a checkpoint of the pool before performing the actions, then rewinds back to it if one of them fails or puts the pool into an unexpected state. Otherwise, she discards it. With the assumption that no one else is making modifications to ZFS, she basically wraps all these actions into a “high-level transaction”. Reviewed by: Matthew Ahrens <mahrens@delphix.com> Reviewed by: John Kennedy <john.kennedy@delphix.com> Reviewed by: Dan Kimmel <dan.kimmel@delphix.com> Approved by: Richard Lowe <richlowe@richlowe.net> Author: Serapheim Dimitropoulos <serapheim.dimitro@delphix.com>
Notes: svn path=/vendor-sys/illumos/dist/; revision=331695
Diffstat (limited to 'man')
3 files changed, 116 insertions, 2 deletions
diff --git a/man/man1m/zdb.1m b/man/man1m/zdb.1m
index c740628f4f9d..63cfc5d7f1b8 100644
--- a/man/man1m/zdb.1m
+++ b/man/man1m/zdb.1m
@@ -21,7 +21,7 @@
.Nd display zpool debugging and consistency information
-.Op Fl AbcdDFGhiLMPsvX
+.Op Fl AbcdDFGhikLMPsvX
.Op Fl e Oo Fl V Oc Op Fl p Ar path ...
.Op Fl I Ar inflight I/Os
.Oo Fl o Ar var Ns = Ns Ar value Oc Ns ...
@@ -170,6 +170,9 @@ Display information about intent log
entries relating to each dataset.
If specified multiple times, display counts of each intent log transaction type.
+.It Fl k
+Examine the checkpointed state of the pool.
+Note, the on disk format of the pool is not reverted to the checkpointed state.
.It Fl l Ar device
Read the vdev labels from the specified device.
.Nm Fl l
diff --git a/man/man1m/zpool.1m b/man/man1m/zpool.1m
index c4cf85925dda..f1b7b579def4 100644
--- a/man/man1m/zpool.1m
+++ b/man/man1m/zpool.1m
@@ -43,6 +43,10 @@
.Op Fl f
.Ar pool device new_device
+.Cm checkpoint
+.Op Fl d, -discard
+.Ar pool
.Cm clear
.Ar pool
.Op Ar device
@@ -93,6 +97,7 @@
.Cm import
.Op Fl Dfm
.Op Fl F Op Fl n
+.Op Fl -rewind-to-checkpoint
.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
@@ -451,6 +456,50 @@ configuration.
The content of the cache devices is considered volatile, as is the case with
other system caches.
+.Ss Pool checkpoint
+Before starting critical procedures that include destructive actions (e.g
+.Nm zfs Cm destroy
+), an administrator can checkpoint the pool's state and in the case of a
+mistake or failure, rewind the entire pool back to the checkpoint.
+Otherwise, the checkpoint can be discarded when the procedure has completed
+A pool checkpoint can be thought of as a pool-wide snapshot and should be used
+with care as it contains every part of the pool's state, from properties to vdev
+Thus, while a pool has a checkpoint certain operations are not allowed.
+Specifically, vdev removal/attach/detach, mirror splitting, and
+changing the pool's guid.
+Adding a new vdev is supported but in the case of a rewind it will have to be
+added again.
+Finally, users of this feature should keep in mind that scrubs in a pool that
+has a checkpoint do not repair checkpointed data.
+To create a checkpoint for a pool:
+.Bd -literal
+# zpool checkpoint pool
+To later rewind to its checkpointed state, you need to first export it and
+then rewind it during import:
+.Bd -literal
+# zpool export pool
+# zpool import --rewind-to-checkpoint pool
+To discard the checkpoint from a pool:
+.Bd -literal
+# zpool checkpoint -d pool
+Dataset reservations (controlled by the
+.Nm reservation
+.Nm refreservation
+zfs properties) may be unenforceable while a checkpoint exists, because the
+checkpoint is allowed to consume the dataset's reservation.
+Finally, data that is part of the checkpoint but has been freed in the
+current state of the pool won't be scanned during a scrub.
.Ss Properties
Each pool has several properties associated with it.
Some properties are read-only statistics while others are configurable and
@@ -767,6 +816,39 @@ Not all devices can be overridden in this manner.
.It Xo
+.Cm checkpoint
+.Op Fl d, -discard
+.Ar pool
+Checkpoints the current state of
+.Ar pool
+, which can be later restored by
+.Nm zpool Cm import --rewind-to-checkpoint .
+The existence of a checkpoint in a pool prohibits the following
+.Nm zpool
+.Cm remove ,
+.Cm attach ,
+.Cm detach ,
+.Cm split ,
+.Cm reguid .
+In addition, it may break reservation boundaries if the pool lacks free
+.Nm zpool Cm status
+command indicates the existence of a checkpoint or the progress of discarding a
+checkpoint from a pool.
+.Nm zpool Cm list
+command reports how much space the checkpoint takes from the pool.
+.Bl -tag -width Ds
+.It Fl d, -discard
+Discards an existing checkpoint from
+.Ar pool .
+.It Xo
.Cm clear
.Ar pool
.Op Ar device
@@ -1152,6 +1234,7 @@ property to
.Cm import
.Op Fl Dfm
.Op Fl F Op Fl n
+.Op Fl -rewind-to-checkpoint
.Op Fl c Ar cachefile Ns | Ns Fl d Ar dir
.Op Fl o Ar mntopts
.Oo Fl o Ar property Ns = Ns Ar value Oc Ns ...
@@ -1240,6 +1323,16 @@ and the
.Sy altroot
property to
.Ar root .
+.It Fl -rewind-to-checkpoint
+Rewinds pool to the checkpointed state.
+Once the pool is imported with this flag there is no way to undo the rewind.
+All changes and data that were written after the checkpoint are lost!
+The only exception is when the
+.Sy readonly
+mounting option is enabled.
+In this case, the checkpointed state of the pool is opened and an
+administrator can see how the pool would look like if they were
+to fully rewind.
.It Xo
diff --git a/man/man5/zpool-features.5 b/man/man5/zpool-features.5
index 90414607fb7b..b471de9cea40 100644
--- a/man/man5/zpool-features.5
+++ b/man/man5/zpool-features.5
@@ -1,5 +1,5 @@
'\" te
-.\" Copyright (c) 2013, 2016 by Delphix. All rights reserved.
+.\" Copyright (c) 2013, 2017 by Delphix. All rights reserved.
.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
.\" Copyright (c) 2014 Integros [integros.com]
@@ -470,6 +470,24 @@ used on a top-level vdev, and will never return to being \fBenabled\fR.
.ne 2
+.RS 4n
+l l .
+GUID com.delphix:zpool_checkpoint
+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.
.RS 4n