Added Info for Errata #3

Reviewed-by: George Melikov <[email protected]> Reviewed-by: Olaf Faaland <[email protected]> Reviewed-by: Tony Hutter <[email protected]> Reviewed-by: Brian Behlendorf <[email protected]> Signed-off-by: Tom Caputi <[email protected]>
zfsonlinux · Feb 2, 2018 · 587f96a · 587f96a
1 parent e295bd1
commit 587f96a
Showing 1 changed file with 87 additions and 2 deletions.
diff --git a/msg/ZFS-8000-ER/index.html b/msg/ZFS-8000-ER/index.html
@@ -135,13 +135,98 @@
 
 <pre>
 # zpool get freeing
-NAME   PROPERTY  VALUE    SOURCE
-rpool  freeing   0        default
+NAME  PROPERTY  VALUE    SOURCE
+test  freeing   0        default
 </pre>
 
 The ZFS packages may be now be updated and the pool imported.  The on-disk
 format incompatibility can now be corrected online as described in
 <a href="#1">Errata #1</a>.
 </pre>
 </td></tr></table>
+<br><br>
+<hr>
+<br><br>
+<!-- end: templates/success -->
+<!-- start: article -->
+<!-- code: ZFS-8000-ER -->
+<!-- keys: errata -->
+<table width="80%"><tr><td>
+<a name="2"><b>ZFS Errata #3</b></a>
+<p>
+<dl>
+<dt><p><b>Type</b>
+<dd>Compatibility
+<dt><p><b>Severity</b>
+<dd>Moderate
+<dt><p><b>Description</b>
+<dd>An encrypted dataset contains an on-disk format incompatability.
+<dt><p><b>Automated Response</b>
+<dd>No automated response will be taken.
+<dt><p><b>Impact</b>
+<dd>
+Encrypted datasets created before the ZFS packages were updated cannot be
+mounted or opened for write. The errata impacts the ability of ZFS to correctly
+perform raw sends, so this functionality has been disabled for these datasets.
+</dd>
+<dt><p><b>Suggested Action for System Administrator</b>
+<dd>
+System administrators with affected pools will need to recreate any encrypted
+datasets created before the new version of ZFS was used. This can be
+accomplished by using <b>zfs send</b> and <b>zfs receive</b>. Note, however,
+that backups can NOT be done with a raw <b>zfs send -w</b>, since this would
+preserve the on-disk incompatibility. Since the <b>-p</b> and <b>-R</b> options
+imply <b>-w</b> for encrypted datasets, these flags can not be used either.
+Alternatively, system administrators can use conventional tools to back up data
+to new encrypted datasets. The new version of ZFS will prevent new data from
+being written to the impacted datasets, but they can still be mounted read-only.
+<pre>
+# zpool status
+  pool: test
+    id: 1165955789558693437
+ state: ONLINE
+status: Errata #3 detected.
+action: To correct the issue backup existing encrypted datasets to new
+	encrypted datasets and destroy the old ones.
+   see: http://zfsonlinux.org/msg/ZFS-8000-ER
+config:
+
+	test           ONLINE
+	  raidz1-0     ONLINE
+	    vdev0      ONLINE
+	    vdev1      ONLINE
+	    vdev2      ONLINE
+	    vdev3      ONLINE
+</pre>
+
+Import the pool and backup any existing encrypted datasets to new datasets.
+To ensure the new datasets are re-encrypted, be sure to receive them below an
+encryption root, then destroy the source dataset.
+<pre>
+# zfs create -o encryption=on -o keyformat=passphrase test/new_root
+Enter passphrase:
+Re-enter passphrase
+# zfs send test/crypt1 | zfs receive test/new_root/crypt1
+# zfs send test/crypt2 | zfs receive test/new_root/crypt2
+# zfs destroy test/crypt1
+# zfs destroy test/crypt2
+</pre>
+
+New datasets can be mounted read-write and used normally. The errata will be
+cleared upon reimporting the pool and the alert will only be shown again if
+another dataset is found with the errata. To ensure that all datasets are
+on the new version reimport the pool, load all keys, mount all encrypted
+datasets, and check <b>zpool status</b>.
+
+<pre>
+# zpool export test
+# zpool import test
+# zfs load-key -a
+Enter passphrase for 'test/new_root': 
+1 / 1 key(s) successfully loaded
+# zfs mount -a
+# zpool status -x
+all pools are healthy
+</pre>
+</td></tr></table>
 </body></html>