From c2fdbb197d24d3bb4eabf3e6bbbe82fd4dcf883e Mon Sep 17 00:00:00 2001 From: Ryan Moeller Date: Wed, 26 Aug 2020 13:39:04 -0400 Subject: [PATCH] Migrate ZFS-* message descriptions (#49) Prerequisite for changing the URLs in the command outputs from zfsonlinux.org to openzfs.github.io/openzfs-docs/ Signed-off-by: Ryan Moeller --- docs/_TableOfContents.rst | 1 + docs/msg/ZFS-8000-14/index.rst | 82 +++++++++ docs/msg/ZFS-8000-2Q/index.rst | 134 ++++++++++++++ docs/msg/ZFS-8000-3C/index.rst | 110 ++++++++++++ docs/msg/ZFS-8000-4J/index.rst | 133 ++++++++++++++ docs/msg/ZFS-8000-5E/index.rst | 88 +++++++++ docs/msg/ZFS-8000-6X/index.rst | 80 +++++++++ docs/msg/ZFS-8000-72/index.rst | 112 ++++++++++++ docs/msg/ZFS-8000-8A/index.rst | 111 ++++++++++++ docs/msg/ZFS-8000-9P/index.rst | 157 ++++++++++++++++ docs/msg/ZFS-8000-A5/index.rst | 83 +++++++++ docs/msg/ZFS-8000-ER/index.rst | 320 +++++++++++++++++++++++++++++++++ docs/msg/ZFS-8000-EY/index.rst | 79 ++++++++ docs/msg/ZFS-8000-HC/index.rst | 85 +++++++++ docs/msg/ZFS-8000-JQ/index.rst | 86 +++++++++ docs/msg/ZFS-8000-K4/index.rst | 132 ++++++++++++++ docs/msg/index.rst | 9 + 17 files changed, 1802 insertions(+) create mode 100644 docs/msg/ZFS-8000-14/index.rst create mode 100644 docs/msg/ZFS-8000-2Q/index.rst create mode 100644 docs/msg/ZFS-8000-3C/index.rst create mode 100644 docs/msg/ZFS-8000-4J/index.rst create mode 100644 docs/msg/ZFS-8000-5E/index.rst create mode 100644 docs/msg/ZFS-8000-6X/index.rst create mode 100644 docs/msg/ZFS-8000-72/index.rst create mode 100644 docs/msg/ZFS-8000-8A/index.rst create mode 100644 docs/msg/ZFS-8000-9P/index.rst create mode 100644 docs/msg/ZFS-8000-A5/index.rst create mode 100644 docs/msg/ZFS-8000-ER/index.rst create mode 100644 docs/msg/ZFS-8000-EY/index.rst create mode 100644 docs/msg/ZFS-8000-HC/index.rst create mode 100644 docs/msg/ZFS-8000-JQ/index.rst create mode 100644 docs/msg/ZFS-8000-K4/index.rst create mode 100644 docs/msg/index.rst diff --git a/docs/_TableOfContents.rst b/docs/_TableOfContents.rst index 802ec77..3502e12 100644 --- a/docs/_TableOfContents.rst +++ b/docs/_TableOfContents.rst @@ -8,4 +8,5 @@ Performance and Tuning/index Basic Concepts/index man/index + msg/index License diff --git a/docs/msg/ZFS-8000-14/index.rst b/docs/msg/ZFS-8000-14/index.rst new file mode 100644 index 0000000..5084bfc --- /dev/null +++ b/docs/msg/ZFS-8000-14/index.rst @@ -0,0 +1,82 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-14 +======================= + +Corrupt ZFS cache +----------------- + ++-------------------------+--------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------+ +| **Severity:** | Critical | ++-------------------------+--------------------------------------+ +| **Description:** | The ZFS cache file is corrupted. | ++-------------------------+--------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------+ +| **Impact:** | ZFS filesystems are not available. | ++-------------------------+--------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +ZFS keeps a list of active pools on the filesystem to avoid having to +scan all devices when the system is booted. If this file is corrupted, +then normally active pools will not be automatically opened. The pools +can be recovered using the ``zpool import`` command: + +:: + + # zpool import + pool: test + id: 12743384782310107047 + state: ONLINE + action: The pool can be imported using its name or numeric identifier. + config: + + test ONLINE + sda9 ONLINE + +This will automatically scan ``/dev`` for any devices part of a pool. +If devices have been made available in an alternate location, use the +``-d`` option to ``zpool import`` to search for devices in a different +directory. + +Once you have determined which pools are available for import, you +can import the pool explicitly by specifying the name or numeric +identifier: + +:: + + # zpool import test + +Alternately, you can import all available pools by specifying the ``-a`` +option. Once a pool has been imported, the ZFS cache will be repaired +so that the pool will appear normally in the future. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-14`` indicates a corrupted ZFS cache file. +Take the documented action to resolve the problem. diff --git a/docs/msg/ZFS-8000-2Q/index.rst b/docs/msg/ZFS-8000-2Q/index.rst new file mode 100644 index 0000000..3eac49f --- /dev/null +++ b/docs/msg/ZFS-8000-2Q/index.rst @@ -0,0 +1,134 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-2Q +======================= + +Missing device in replicated configuration +------------------------------------------ + ++-------------------------+--------------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------------+ +| **Severity:** | Major | ++-------------------------+--------------------------------------------------+ +| **Description:** | A device in a replicated configuration could not | +| | be opened. | ++-------------------------+--------------------------------------------------+ +| **Automated Response:** | A hot spare will be activated if available. | ++-------------------------+--------------------------------------------------+ +| **Impact:** | The pool is no longer providing the configured | +| | level of replication. | ++-------------------------+--------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +.. rubric:: For an active pool: + +If this error was encountered while running ``zpool import``, please +see the section below. Otherwise, run ``zpool status -x`` to determine +which pool has experienced a failure: + +:: + + # zpool status -x + pool: test + state: DEGRADED + status: One or more devices could not be opened. Sufficient replicas exist for + the pool to continue functioning in a degraded state. + action: Attach the missing device and online it using 'zpool online'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-2Q + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test DEGRADED 0 0 0 + mirror DEGRADED 0 0 0 + c0t0d0 ONLINE 0 0 0 + c0t0d1 FAULTED 0 0 0 cannot open + + errors: No known data errors + +Determine which device failed to open by looking for a FAULTED device +with an additional 'cannot open' message. If this device has been +inadvertently removed from the system, attach the device and bring it +online with ``zpool online``: + +:: + + # zpool online test c0t0d1 + +If the device is no longer available, the device can be replaced +using the ``zpool replace`` command: + +:: + + # zpool replace test c0t0d1 c0t0d2 + +If the device has been replaced by another disk in the same physical +slot, then the device can be replaced using a single argument to the +``zpool replace`` command: + +:: + + # zpool replace test c0t0d1 + +Existing data will be resilvered to the new device. Once the +resilvering completes, the device will be removed from the pool. + +.. rubric:: For an exported pool: + +If this error is encountered during a ``zpool import``, it means that +one of the devices is not attached to the system: + +:: + + # zpool import + pool: test + id: 10121266328238932306 + state: DEGRADED + status: One or more devices are missing from the system. + action: The pool can be imported despite missing or damaged devices. The + fault tolerance of the pool may be compromised if imported. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-2Q + config: + + test DEGRADED + mirror DEGRADED + c0t0d0 ONLINE + c0t0d1 FAULTED cannot open + +Unlike when the pool is active on the system, the device cannot be +replaced while the pool is exported. If the device can be attached to +the system, attach the device and run ``zpool import`` again. + +Alternatively, the pool can be imported as-is, though it will be +placed in the DEGRADED state due to a missing device. The device will +be marked as UNAVAIL. Once the pool has been imported, the missing +device can be replaced as described above. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-2Q`` indicates a device which was unable +to be opened by the ZFS subsystem. diff --git a/docs/msg/ZFS-8000-3C/index.rst b/docs/msg/ZFS-8000-3C/index.rst new file mode 100644 index 0000000..fcdb0cc --- /dev/null +++ b/docs/msg/ZFS-8000-3C/index.rst @@ -0,0 +1,110 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-3C +======================= + +Missing device in non-replicated configuration +---------------------------------------------- + ++-------------------------+--------------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------------+ +| **Severity:** | Critical | ++-------------------------+--------------------------------------------------+ +| **Description:** | A device could not be opened and no replicas are | +| | available. | ++-------------------------+--------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------------------+ +| **Impact:** | The pool is no longer available. | ++-------------------------+--------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +.. rubric:: For an active pool: + +If this error was encountered while running ``zpool import``, please +see the section below. Otherwise, run ``zpool status -x`` to determine +which pool has experienced a failure: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: One or more devices could not be opened. There are insufficient + replicas for the pool to continue functioning. + action: Attach the missing device and online it using 'zpool online'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-3C + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 0 0 insufficient replicas + c0t0d0 ONLINE 0 0 0 + c0t0d1 FAULTED 0 0 0 cannot open + + errors: No known data errors + +If the device has been temporarily detached from the system, attach +the device to the system and run ``zpool status`` again. The pool +should automatically detect the newly attached device and resume +functioning. You may have to mount the filesystems in the pool +explicitly using ``zfs mount -a``. + +If the device is no longer available and cannot be reattached to the +system, then the pool must be destroyed and re-created from a backup +source. + +.. rubric:: For an exported pool: + +If this error is encountered during a ``zpool import``, it means that +one of the devices is not attached to the system: + +:: + + # zpool import + pool: test + id: 10121266328238932306 + state: FAULTED + status: One or more devices are missing from the system. + action: The pool cannot be imported. Attach the missing devices and try again. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-3C + config: + + test FAULTED insufficient replicas + c0t0d0 ONLINE + c0t0d1 FAULTED cannot open + +The pool cannot be imported until the missing device is attached to +the system. If the device has been made available in an alternate +location, use the ``-d`` option to ``zpool import`` to search for devices +in a different directory. If the missing device is unavailable, then +the pool cannot be imported. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-3C`` indicates a device which was unable +to be opened by the ZFS subsystem. diff --git a/docs/msg/ZFS-8000-4J/index.rst b/docs/msg/ZFS-8000-4J/index.rst new file mode 100644 index 0000000..cab39c2 --- /dev/null +++ b/docs/msg/ZFS-8000-4J/index.rst @@ -0,0 +1,133 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-4J +======================= + +Corrupted device label in a replicated configuration +---------------------------------------------------- + ++-------------------------+--------------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------------+ +| **Severity:** | Major | ++-------------------------+--------------------------------------------------+ +| **Description:** | A device could not be opened due to a missing or | +| | invalid device label. | ++-------------------------+--------------------------------------------------+ +| **Automated Response:** | A hot spare will be activated if available. | ++-------------------------+--------------------------------------------------+ +| **Impact:** | The pool is no longer providing the configured | +| | level of replication. | ++-------------------------+--------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +.. rubric:: For an active pool: + +If this error was encountered while running ``zpool import``, please +see the section below. Otherwise, run ``zpool status -x`` to determine +which pool has experienced a failure: + +:: + + # zpool status -x + pool: test + state: DEGRADED + status: One or more devices could not be used because the label is missing or + invalid. Sufficient replicas exist for the pool to continue + functioning in a degraded state. + action: Replace the device using 'zpool replace'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-4J + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test DEGRADED 0 0 0 + mirror DEGRADED 0 0 0 + c0t0d0 ONLINE 0 0 0 + c0t0d1 FAULTED 0 0 0 corrupted data + + errors: No known data errors + +If the device has been temporarily detached from the system, attach +the device to the system and run ``zpool status`` again. The pool +should automatically detect the newly attached device and resume +functioning. + +If the device is no longer available, it can be replaced using ``zpool +replace``: + +:: + + # zpool replace test c0t0d1 c0t0d2 + +If the device has been replaced by another disk in the same physical +slot, then the device can be replaced using a single argument to the +``zpool replace`` command: + +:: + + # zpool replace test c0t0d1 + +ZFS will begin migrating data to the new device as soon as the +replace is issued. Once the resilvering completes, the original +device (if different from the replacement) will be removed, and the +pool will be restored to the ONLINE state. + +.. rubric:: For an exported pool: + +If this error is encountered while running ``zpool import``, the pool +can be still be imported despite the failure: + +:: + + # zpool import + pool: test + id: 5187963178597328409 + state: DEGRADED + status: One or more devices contains corrupted data. The fault tolerance of + the pool may be compromised if imported. + action: The pool can be imported using its name or numeric identifier. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-4J + config: + + test DEGRADED + mirror DEGRADED + c0t0d0 ONLINE + c0t0d1 FAULTED corrupted data + +To import the pool, run ``zpool import``: + +:: + + # zpool import test + +Once the pool has been imported, the damaged device can be replaced +according to the above procedure. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-4J`` indicates a device which was unable +to be opened by the ZFS subsystem. diff --git a/docs/msg/ZFS-8000-5E/index.rst b/docs/msg/ZFS-8000-5E/index.rst new file mode 100644 index 0000000..0b89515 --- /dev/null +++ b/docs/msg/ZFS-8000-5E/index.rst @@ -0,0 +1,88 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-5E +======================= + +Corrupted device label in non-replicated configuration +------------------------------------------------------ + ++-------------------------+--------------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------------+ +| **Severity:** | Critical | ++-------------------------+--------------------------------------------------+ +| **Description:** | A device could not be opened due to a missing or | +| | invalid device label and no replicas are | +| | available. | ++-------------------------+--------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------------------+ +| **Impact:** | The pool is no longer available. | ++-------------------------+--------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +.. rubric:: For an active pool: + +If this error was encountered while running ``zpool import``, please see the +section below. Otherwise, run ``zpool status -x`` to determine which pool has +experienced a failure: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: One or more devices could not be used because the the label is missing + or invalid. There are insufficient replicas for the pool to continue + functioning. + action: Destroy and re-create the pool from a backup source. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-5E + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 0 0 insufficient replicas + c0t0d0 FAULTED 0 0 0 corrupted data + c0t0d1 ONLINE 0 0 0 + + errors: No known data errors + +The device listed as FAULTED with 'corrupted data' cannot be opened due to a +corrupt label. ZFS will be unable to use the pool, and all data within the +pool is irrevocably lost. The pool must be destroyed and recreated from an +appropriate backup source. Using replicated configurations will prevent this +from happening in the future. + +.. rubric:: For an exported pool: + +If this error is encountered during ``zpool import``, the action is the same. +The pool cannot be imported - all data is lost and must be restored from an +appropriate backup source. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-5E`` indicates a device which was unable to be +opened by the ZFS subsystem. diff --git a/docs/msg/ZFS-8000-6X/index.rst b/docs/msg/ZFS-8000-6X/index.rst new file mode 100644 index 0000000..b6702eb --- /dev/null +++ b/docs/msg/ZFS-8000-6X/index.rst @@ -0,0 +1,80 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-6X +======================= + +Missing top level device +------------------------ + ++-------------------------+--------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------+ +| **Severity:** | Critical | ++-------------------------+--------------------------------------------+ +| **Description:** | One or more top level devices are missing. | ++-------------------------+--------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------------+ +| **Impact:** | The pool cannot be imported. | ++-------------------------+--------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +Run ``zpool import`` to list which pool cannot be imported: + +:: + + # zpool import + pool: test + id: 13783646421373024673 + state: FAULTED + status: One or more devices are missing from the system. + action: The pool cannot be imported. Attach the missing devices and try again. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-6X + config: + + test FAULTED missing device + c0t0d0 ONLINE + + Additional devices are known to be part of this pool, though their + exact configuration cannot be determined. + +ZFS attempts to store enough configuration data on the devices such +that the configuration is recoverable from any subset of devices. In +some cases, particularly when an entire toplevel virtual device is +not attached to the system, ZFS will be unable to determine the +complete configuration. It will always detect that these devices are +missing, even if it cannot identify all of the devices. + +The pool cannot be imported until the unknown missing device is +attached to the system. If the device has been made available in an +alternate location, use the ``-d`` option to ``zpool import`` to search +for devices in a different directory. If the missing device is +unavailable, then the pool cannot be imported. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-6X`` indicates one or more top level +devices are missing from the configuration. diff --git a/docs/msg/ZFS-8000-72/index.rst b/docs/msg/ZFS-8000-72/index.rst new file mode 100644 index 0000000..e302ea2 --- /dev/null +++ b/docs/msg/ZFS-8000-72/index.rst @@ -0,0 +1,112 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-72 +======================= + +Corrupted pool metadata +----------------------- + ++-------------------------+-------------------------------------------+ +| **Type:** | Error | ++-------------------------+-------------------------------------------+ +| **Severity:** | Critical | ++-------------------------+-------------------------------------------+ +| **Description:** | The metadata required to open the pool is | +| | corrupt. | ++-------------------------+-------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+-------------------------------------------+ +| **Impact:** | The pool is no longer available. | ++-------------------------+-------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +Even though all the devices are available, the on-disk data has been +corrupted such that the pool cannot be opened. If a recovery action +is presented, the pool can be returned to a usable state. Otherwise, +all data within the pool is lost, and the pool must be destroyed and +restored from an appropriate backup source. ZFS includes built-in +metadata replication to prevent this from happening even for +unreplicated pools, but running in a replicated configuration will +decrease the chances of this happening in the future. + +If this error is encountered during ``zpool import``, see the section +below. Otherwise, run ``zpool status -x`` to determine which pool is +faulted and if a recovery option is available: + +:: + + # zpool status -x + pool: test + id: 13783646421373024673 + state: FAULTED + status: The pool metadata is corrupted and cannot be opened. + action: Recovery is possible, but will result in some data loss. + Returning the pool to its state as of Mon Sep 28 10:24:39 2009 + should correct the problem. Approximately 59 seconds of data + will have to be discarded, irreversibly. Recovery can be + attempted by executing 'zpool clear -F test'. A scrub of the pool + is strongly recommended following a successful recovery. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-72 + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 0 2 corrupted data + c0t0d0 ONLINE 0 0 2 + c0t0d1 ONLINE 0 0 2 + +If recovery is unavailable, the recommended action will be: + +:: + + action: Destroy the pool and restore from backup. + +If this error is encountered during ``zpool import``, and if no recovery option +is mentioned, the pool is unrecoverable and cannot be imported. The pool must +be restored from an appropriate backup source. If a recovery option is +available, the output from ``zpool import`` will look something like the +following: + +:: + + # zpool import share + cannot import 'share': I/O error + Recovery is possible, but will result in some data loss. + Returning the pool to its state as of Sun Sep 27 12:31:07 2009 + should correct the problem. Approximately 53 seconds of data + will have to be discarded, irreversibly. Recovery can be + attempted by executing 'zpool import -F share'. A scrub of the pool + is strongly recommended following a successful recovery. + +Recovery actions are requested with the -F option to either ``zpool +clear`` or ``zpool import``. Recovery will result in some data loss, +because it reverts the pool to an earlier state. A dry-run recovery +check can be performed by adding the ``-n`` option, affirming if recovery +is possible without actually reverting the pool to its earlier state. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-72`` indicates a pool was unable to be +opened due to a detected corruption in the pool metadata. diff --git a/docs/msg/ZFS-8000-8A/index.rst b/docs/msg/ZFS-8000-8A/index.rst new file mode 100644 index 0000000..a854e83 --- /dev/null +++ b/docs/msg/ZFS-8000-8A/index.rst @@ -0,0 +1,111 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-8A +======================= + +Corrupted data +-------------- + ++-------------------------+----------------------------------------------+ +| **Type:** | Error | ++-------------------------+----------------------------------------------+ +| **Severity:** | Critical | ++-------------------------+----------------------------------------------+ +| **Description:** | A file or directory could not be read due to | +| | corrupt data. | ++-------------------------+----------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+----------------------------------------------+ +| **Impact:** | The file or directory is unavailable. | ++-------------------------+----------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +Run ``zpool status -x`` to determine which pool is damaged: + +:: + + # zpool status -x + pool: test + state: ONLINE + status: One or more devices has experienced an error and no valid replicas + are available. Some filesystem data is corrupt, and applications + may have been affected. + action: Destroy the pool and restore from backup. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-8A + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 2 + c0t0d0 ONLINE 0 0 2 + c0t0d1 ONLINE 0 0 0 + + errors: 1 data errors, use '-v' for a list + +Unfortunately, the data cannot be repaired, and the only choice to +repair the data is to restore the pool from backup. Applications +attempting to access the corrupted data will get an error (EIO), and +data may be permanently lost. + +The list of affected files can be retrieved by using the ``-v`` option to +``zpool status``: + +:: + + # zpool status -xv + pool: test + state: ONLINE + status: One or more devices has experienced an error and no valid replicas + are available. Some filesystem data is corrupt, and applications + may have been affected. + action: Destroy the pool and restore from backup. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-8A + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 2 + c0t0d0 ONLINE 0 0 2 + c0t0d1 ONLINE 0 0 0 + + errors: Permanent errors have been detected in the following files: + + /export/example/foo + +Damaged files may or may not be able to be removed depending on the +type of corruption. If the corruption is within the plain data, the +file should be removable. If the corruption is in the file metadata, +then the file cannot be removed, though it can be moved to an +alternate location. In either case, the data should be restored from +a backup source. It is also possible for the corruption to be within +pool-wide metadata, resulting in entire datasets being unavailable. +If this is the case, the only option is to destroy the pool and +re-create the datasets from backup. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-8A`` indicates corrupted data exists in +the current pool. diff --git a/docs/msg/ZFS-8000-9P/index.rst b/docs/msg/ZFS-8000-9P/index.rst new file mode 100644 index 0000000..e49b099 --- /dev/null +++ b/docs/msg/ZFS-8000-9P/index.rst @@ -0,0 +1,157 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-9P +======================= + +Failing device in replicated configuration +------------------------------------------ + ++-------------------------+----------------------------------------------------+ +| **Type:** | Error | ++-------------------------+----------------------------------------------------+ +| **Severity:** | Minor | ++-------------------------+----------------------------------------------------+ +| **Description:** | A device has experienced uncorrectable errors in a | +| | replicated configuration. | ++-------------------------+----------------------------------------------------+ +| **Automated Response:** | ZFS has attempted to repair the affected data. | ++-------------------------+----------------------------------------------------+ +| **Impact:** | The system is unaffected, though errors may | +| | indicate future failure. Future errors may cause | +| | ZFS to automatically fault the device. | ++-------------------------+----------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +Run ``zpool status -x`` to determine which pool has experienced errors: + +:: + + # zpool status + pool: test + state: ONLINE + status: One or more devices has experienced an unrecoverable error. An + attempt was made to correct the error. Applications are unaffected. + action: Determine if the device needs to be replaced, and clear the errors + using 'zpool online' or replace the device with 'zpool replace'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-9P + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 0 + mirror ONLINE 0 0 0 + c0t0d0 ONLINE 0 0 2 + c0t0d1 ONLINE 0 0 0 + + errors: No known data errors + +Find the device with a non-zero error count for READ, WRITE, or +CKSUM. This indicates that the device has experienced a read I/O +error, write I/O error, or checksum validation error. Because the +device is part of a mirror or RAID-Z device, ZFS was able to recover +from the error and subsequently repair the damaged data. + +If these errors persist over a period of time, ZFS may determine the +device is faulty and mark it as such. However, these error counts may +or may not indicate that the device is unusable. It depends on how +the errors were caused, which the administrator can determine in +advance of any ZFS diagnosis. For example, the following cases will +all produce errors that do not indicate potential device failure: + +- A network attached device lost connectivity but has now + recovered +- A device suffered from a bit flip, an expected event over long + periods of time +- An administrator accidentally wrote over a portion of the disk + using another program + +In these cases, the presence of errors does not indicate that the +device is likely to fail in the future, and therefore does not need +to be replaced. If this is the case, then the device errors should be +cleared using ``zpool clear``: + +:: + + # zpool clear test c0t0d0 + +On the other hand, errors may very well indicate that the device has +failed or is about to fail. If there are continual I/O errors to a +device that is otherwise attached and functioning on the system, it +most likely needs to be replaced. The administrator should check the +system log for any driver messages that may indicate hardware +failure. If it is determined that the device needs to be replaced, +then the ``zpool replace`` command should be used: + +:: + + # zpool replace test c0t0d0 c0t0d2 + +This will attach the new device to the pool and begin resilvering +data to it. Once the resilvering process is complete, the old device +will automatically be removed from the pool, at which point it can +safely be removed from the system. If the device needs to be replaced +in-place (because there are no available spare devices), the original +device can be removed and replaced with a new device, at which point +a different form of ``zpool replace`` can be used: + +:: + + # zpool replace test c0t0d0 + +This assumes that the original device at 'c0t0d0' has been replaced +with a new device under the same path, and will be replaced +appropriately. + +You can monitor the progress of the resilvering operation by using +the ``zpool status -x`` command: + +:: + + # zpool status -x + pool: test + state: DEGRADED + status: One or more devices is currently being replaced. The pool may not be + providing the necessary level of replication. + action: Wait for the resilvering operation to complete + scrub: resilver in progress, 0.14% done, 0h0m to go + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 0 + mirror ONLINE 0 0 0 + replacing ONLINE 0 0 0 + c0t0d0 ONLINE 0 0 3 + c0t0d2 ONLINE 0 0 0 58.5K resilvered + c0t0d1 ONLINE 0 0 0 + + errors: No known data errors + +.. rubric:: Details + +The Message ID: ``ZFS-8000-9P`` indicates a device has exceeded the +acceptable limit of errors allowed by the system. See document +`203768 `__ +for additional information. diff --git a/docs/msg/ZFS-8000-A5/index.rst b/docs/msg/ZFS-8000-A5/index.rst new file mode 100644 index 0000000..b58c129 --- /dev/null +++ b/docs/msg/ZFS-8000-A5/index.rst @@ -0,0 +1,83 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-A5 +======================= + +Incompatible version +-------------------- + ++-------------------------+------------------------------------------------+ +| **Type:** | Error | ++-------------------------+------------------------------------------------+ +| **Severity:** | Major | ++-------------------------+------------------------------------------------+ +| **Description:** | The on-disk version is not compatible with the | +| | running system. | ++-------------------------+------------------------------------------------+ +| **Automated Response:** | No automated response will occur. | ++-------------------------+------------------------------------------------+ +| **Impact:** | The pool is unavailable. | ++-------------------------+------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +If this error is seen during ``zpool import``, see the section below. +Otherwise, run ``zpool status -x`` to determine which pool is faulted: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: The ZFS version for the pool is incompatible with the software running + on this system. + action: Destroy and re-create the pool. + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 0 0 incompatible version + mirror ONLINE 0 0 0 + sda9 ONLINE 0 0 0 + sdb9 ONLINE 0 0 0 + + errors: No known errors + +The pool cannot be used on this system. Either move the storage to +the system where the pool was originally created, upgrade the current +system software to a more recent version, or destroy the pool and +re-create it from backup. + +If this error is seen during import, the pool cannot be imported on +the current system. The disks must be attached to the system which +originally created the pool, and imported there. + +The list of currently supported versions can be displayed using +``zpool upgrade -v``. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-A5`` indicates a version mismatch exists +between the running system and the on-disk data. diff --git a/docs/msg/ZFS-8000-ER/index.rst b/docs/msg/ZFS-8000-ER/index.rst new file mode 100644 index 0000000..b890abc --- /dev/null +++ b/docs/msg/ZFS-8000-ER/index.rst @@ -0,0 +1,320 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-ER +======================= + +ZFS Errata #1 +------------- + ++-------------------------+--------------------------------------------------+ +| **Type:** | Compatibility | ++-------------------------+--------------------------------------------------+ +| **Severity:** | Moderate | ++-------------------------+--------------------------------------------------+ +| **Description:** | The ZFS pool contains an on-disk format | +| | incompatibility. | ++-------------------------+--------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------------------+ +| **Impact:** | Until the pool is scrubbed using OpenZFS version | +| | 0.6.3 or newer the pool may not be imported by | +| | older versions of OpenZFS or other ZFS | +| | implementations. | ++-------------------------+--------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +The pool contains an on-disk format incompatibility. Affected pools +must be imported and scrubbed using the current version of ZFS. This +will return the pool to a state in which it may be imported by other +implementations. This errata only impacts compatibility between ZFS +versions, no user data is at risk as result of this erratum. + +:: + + # zpool status -x + pool: test + state: ONLINE + status: Errata #1 detected. + action: To correct the issue run 'zpool scrub'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-ER + scan: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 0 + raidz1-0 ONLINE 0 0 0 + vdev0 ONLINE 0 0 0 + vdev1 ONLINE 0 0 0 + vdev2 ONLINE 0 0 0 + vdev3 ONLINE 0 0 0 + + errors: No known data errors + + # zpool scrub test + + # zpool status -x + all pools are healthy + + +ZFS Errata #2 +------------- + ++-------------------------+---------------------------------------------------+ +| **Type:** | Compatibility | ++-------------------------+---------------------------------------------------+ +| **Severity:** | Moderate | ++-------------------------+---------------------------------------------------+ +| **Description:** | The ZFS packages were updated while an | +| | asynchronous destroy was in progress and the pool | +| | contains an on-disk format incompatibility. | ++-------------------------+---------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+---------------------------------------------------+ +| **Impact:** | The pool cannot be imported until the issue is | +| | corrected. | ++-------------------------+---------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +Affected pools must be reverted to the previous ZFS version where +they can be correctly imported. Once imported, all asynchronous +destroy operations must be allowed to complete. The ZFS packages may +then be updated and the pool can be imported cleanly by the newer +software. + +:: + + # zpool import + pool: test + id: 1165955789558693437 + state: ONLINE + status: Errata #2 detected. + action: The pool cannot be imported with this version of ZFS due to + an active asynchronous destroy. Revert to an earlier version + and allow the destroy to complete before updating. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-ER + config: + + test ONLINE + raidz1-0 ONLINE + vdev0 ONLINE + vdev1 ONLINE + vdev2 ONLINE + vdev3 ONLINE + +Revert to previous ZFS version, import the pool, then wait for the +``freeing`` property to drop to zero. This indicates that all +outstanding asynchronous destroys have completed. + +:: + + # zpool get freeing + NAME PROPERTY VALUE SOURCE + test freeing 0 default + +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 `Errata #1 <#1>`__. + + +ZFS Errata #3 +------------- + ++-------------------------+----------------------------------------------------+ +| **Type:** | Compatibility | ++-------------------------+----------------------------------------------------+ +| **Severity:** | Moderate | ++-------------------------+----------------------------------------------------+ +| **Description:** | An encrypted dataset contains an on-disk format | +| | incompatibility. | ++-------------------------+----------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+----------------------------------------------------+ +| **Impact:** | 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. | ++-------------------------+----------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +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 ``zfs send`` and ``zfs receive``. +Note, however, that backups can NOT be done with a raw ``zfs send -w``, +since this would preserve the on-disk incompatibility. +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. + +:: + + # 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: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-ER + config: + + test ONLINE + raidz1-0 ONLINE + vdev0 ONLINE + vdev1 ONLINE + vdev2 ONLINE + vdev3 ONLINE + +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 or use ``zfs receive -o +encryption=on``, then destroy the source dataset. + +:: + + # zfs send test/crypt1@snap1 | zfs receive -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile test/newcrypt1 + # zfs send -I test/crypt1@snap1 test/crypt1@snap5 | zfs receive test/newcrypt1 + # zfs destroy -R test/crypt1 + +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 ``zpool status``. + +:: + + # zpool export test + # zpool import test + # zfs load-key -a + Enter passphrase for 'test/crypt1': + 1 / 1 key(s) successfully loaded + # zfs mount -a + # zpool status -x + all pools are healthy + + +ZFS Errata #4 +------------- + ++-------------------------+----------------------------------------------------+ +| **Type:** | Compatibility | ++-------------------------+----------------------------------------------------+ +| **Severity:** | Moderate | ++-------------------------+----------------------------------------------------+ +| **Description:** | An encrypted dataset contains an on-disk format | +| | incompatibility. | ++-------------------------+----------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+----------------------------------------------------+ +| **Impact:** | Encrypted datasets created before the ZFS packages | +| | were updated cannot be backed up via a raw send to | +| | an updated system. These datasets also cannot | +| | receive additional snapshots. New encrypted | +| | datasets cannot be created until the | +| | ``bookmark_v2`` feature has been enabled. | ++-------------------------+----------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +First, system administrators with affected pools will need to enable +the ``bookmark_v2`` feature on their pools. Enabling this feature +will prevent this pool from being imported by previous versions of +the ZFS software after any new bookmarks are created (including +read-only imports). If the pool contains no encrypted datasets, this +is the only step required. If there are existing encrypted datasets, +administrators will then need to back these datasets up. This can be +done in several ways. Non-raw ``zfs send`` and ``zfs receive`` can be +used as per usual, as can traditional backup tools. Raw receives of +existing encrypted datasets and raw receives into existing encrypted +datasets are currently disabled because ZFS is not able to guarantee +that the stream and the existing dataset came from a consistent +source. This check can be disabled which will allow ZFS to receive +these streams anyway. Note that this can result in datasets with data +that cannot be accessed due to authentication errors if raw and +non-raw receives are mixed over the course of several incremental +backups. To disable this restriction, set the +``zfs_disable_ivset_guid_check`` module parameter to 1. Streams +received this way (as well as any received before the upgrade) will +need to be manually checked by reading the data to ensure they are +not corrupted. Note that ``zpool scrub`` cannot be used for this +purpose because the scrub does not check the cryptographic +authentication codes. For more information on this issue, please +refer to the zfs man page section on ``zfs receive`` which describes +the restrictions on raw sends. + +:: + + # zpool status + pool: test + state: ONLINE + status: Errata #4 detected. + Existing encrypted datasets contain an on-disk incompatibility + which needs to be corrected. + action: To correct the issue enable the bookmark_v2 feature and backup + any existing encrypted datasets to new encrypted datasets and + destroy the old ones. If this pool does not contain any + encrypted datasets, simply enable the bookmark_v2 feature. + see: http://openzfs.github.io/openzfs-docs/msg/ZFS-8000-ER + scan: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 0 + /root/vdev0 ONLINE 0 0 0 + + errors: No known data errors + +Import the pool and enable the ``bookmark_v2`` feature. Then backup +any existing encrypted datasets to new datasets. This can be done +with traditional tools or via ``zfs send``. Raw sends will require +that the ``zfs_disable_ivset_guid_check`` is set to 1 on the receive +side. Once this is done, the original datasets should be destroyed. + +:: + + # zpool set feature@bookmark_v2=enabled test + # echo 1 > /sys/module/zfs/parameters/zfs_disable_ivset_guid_check + # zfs send -Rw test/crypt1@snap1 | zfs receive test/newcrypt1 + # zfs send -I test/crypt1@snap1 test/crypt1@snap5 | zfs receive test/newcrypt1 + # zfs destroy -R test/crypt1 + # echo 0 > /sys/module/zfs/parameters/zfs_disable_ivset_guid_check + +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 check that all datasets are fixed, perform a ``zfs list -t all``, +and check ``zpool status`` once it is completed. + +:: + + # zpool export test + # zpool import test + # zpool scrub # wait for completion + # zpool status -x + all pools are healthy diff --git a/docs/msg/ZFS-8000-EY/index.rst b/docs/msg/ZFS-8000-EY/index.rst new file mode 100644 index 0000000..0bd466e --- /dev/null +++ b/docs/msg/ZFS-8000-EY/index.rst @@ -0,0 +1,79 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-EY +======================= + +ZFS label hostid mismatch +------------------------- + ++-------------------------+---------------------------------------------------+ +| **Type:** | Error | ++-------------------------+---------------------------------------------------+ +| **Severity:** | Major | ++-------------------------+---------------------------------------------------+ +| **Description:** | The ZFS pool was last accessed by another system. | ++-------------------------+---------------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+---------------------------------------------------+ +| **Impact:** | ZFS filesystems are not available. | ++-------------------------+---------------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +The pool has been written to from another host, and was not cleanly +exported from the other system. Actively importing a pool on multiple +systems will corrupt the pool and leave it in an unrecoverable state. +To determine which system last accessed the pool, run the ``zpool +import`` command: + +:: + + # zpool import + pool: test + id: 14702934086626715962 + state: ONLINE + status: The pool was last accessed by another system. + action: The pool can be imported using its name or numeric identifier and + the '-f' flag. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-EY + config: + + test ONLINE + c0t0d0 ONLINE + + # zpool import test + cannot import 'test': pool may be in use from other system, it was last + accessed by 'tank' (hostid: 0x1435718c) on Fri Mar 9 15:42:47 2007 + use '-f' to import anyway + +If you are certain that the pool is not being actively accessed by +another system, then you can use the ``-f`` option to ``zpool import`` to +forcibly import the pool. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-EY`` indicates that the pool cannot be +imported as it was last accessed by another system. Take the +documented action to resolve the problem. diff --git a/docs/msg/ZFS-8000-HC/index.rst b/docs/msg/ZFS-8000-HC/index.rst new file mode 100644 index 0000000..1a94d7e --- /dev/null +++ b/docs/msg/ZFS-8000-HC/index.rst @@ -0,0 +1,85 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-HC +======================= + +ZFS pool I/O failures +--------------------- + ++-------------------------+-----------------------------------------+ +| **Type:** | Error | ++-------------------------+-----------------------------------------+ +| **Severity:** | Major | ++-------------------------+-----------------------------------------+ +| **Description:** | The ZFS pool has experienced currently | +| | unrecoverable I/O failures. | ++-------------------------+-----------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+-----------------------------------------+ +| **Impact:** | Read and write I/Os cannot be serviced. | ++-------------------------+-----------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +The pool has experienced I/O failures. Since the ZFS pool property +``failmode`` is set to 'wait', all I/Os (reads and writes) are blocked. +See the zpoolprops(8) manpage for more information on the ``failmode`` +property. Manual intervention is required for I/Os to be serviced. + +You can see which devices are affected by running ``zpool status -x``: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: There are I/O failures. + action: Make sure the affected devices are connected, then run 'zpool clear'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-HC + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 13 0 insufficient replicas + c0t0d0 FAULTED 0 7 0 experienced I/O failures + c0t1d0 ONLINE 0 0 0 + + errors: 1 data errors, use '-v' for a list + +After you have made sure the affected devices are connected, run ``zpool +clear`` to allow I/O to the pool again: + +:: + + # zpool clear test + +If I/O failures continue to happen, then applications and commands for the pool +may hang. At this point, a reboot may be necessary to allow I/O to the pool +again. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-HC`` indicates that the pool has experienced I/O +failures. Take the documented action to resolve the problem. diff --git a/docs/msg/ZFS-8000-JQ/index.rst b/docs/msg/ZFS-8000-JQ/index.rst new file mode 100644 index 0000000..6ffcc2f --- /dev/null +++ b/docs/msg/ZFS-8000-JQ/index.rst @@ -0,0 +1,86 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-JQ +======================= + +ZFS pool I/O failures +--------------------- + ++-------------------------+----------------------------------------+ +| **Type:** | Error | ++-------------------------+----------------------------------------+ +| **Severity:** | Major | ++-------------------------+----------------------------------------+ +| **Description:** | The ZFS pool has experienced currently | +| | unrecoverable I/O failures. | ++-------------------------+----------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+----------------------------------------+ +| **Impact:** | Write I/Os cannot be serviced. | ++-------------------------+----------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +The pool has experienced I/O failures. Since the ZFS pool property +``failmode`` is set to 'continue', read I/Os will continue to be +serviced, but write I/Os are blocked. See the zpoolprops(8) manpage for +more information on the ``failmode`` property. Manual intervention is +required for write I/Os to be serviced. You can see which devices are +affected by running ``zpool status -x``: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: There are I/O failures. + action: Make sure the affected devices are connected, then run 'zpool clear'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-HC + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 13 0 insufficient replicas + sda9 FAULTED 0 7 0 experienced I/O failures + sdb9 ONLINE 0 0 0 + + errors: 1 data errors, use '-v' for a list + +After you have made sure the affected devices are connected, run +``zpool clear`` to allow write I/O to the pool again: + +:: + + # zpool clear test + +If I/O failures continue to happen, then applications and commands +for the pool may hang. At this point, a reboot may be necessary to +allow I/O to the pool again. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-JQ`` indicates that the pool has +experienced I/O failures. Take the documented action to resolve the +problem. diff --git a/docs/msg/ZFS-8000-K4/index.rst b/docs/msg/ZFS-8000-K4/index.rst new file mode 100644 index 0000000..c8963d8 --- /dev/null +++ b/docs/msg/ZFS-8000-K4/index.rst @@ -0,0 +1,132 @@ +.. + CDDL HEADER START + + 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] + + CDDL HEADER END + + Portions Copyright 2007 Sun Microsystems, Inc. + +.. highlight:: none + +Message ID: ZFS-8000-K4 +======================= + +ZFS intent log read failure +--------------------------- + ++-------------------------+--------------------------------------------+ +| **Type:** | Error | ++-------------------------+--------------------------------------------+ +| **Severity:** | Major | ++-------------------------+--------------------------------------------+ +| **Description:** | A ZFS intent log device could not be read. | ++-------------------------+--------------------------------------------+ +| **Automated Response:** | No automated response will be taken. | ++-------------------------+--------------------------------------------+ +| **Impact:** | The intent log(s) cannot be replayed. | ++-------------------------+--------------------------------------------+ + +.. rubric:: Suggested Action for System Administrator + +A ZFS intent log record could not be read due to an error. This may +be due to a missing or broken log device, or a device within the pool +may be experiencing I/O errors. The pool itself is not corrupt but is +missing some pool changes that happened shortly before a power loss +or system failure. These are pool changes that applications had +requested to be written synchronously but had not been committed in +the pool. This transaction group commit currently occurs every five +seconds, and so typically at most five seconds worth of synchronous +writes have been lost. ZFS itself cannot determine if the pool +changes lost are critical to those applications running at the time +of the system failure. This is a decision the administrator must +make. You may want to consider mirroring log devices. First determine +which pool is in error: + +:: + + # zpool status -x + pool: test + state: FAULTED + status: One or more of the intent logs could not be read. + Waiting for adminstrator intervention to fix the faulted pool. + action: Either restore the affected device(s) and run 'zpool online', + or ignore the intent log records by running 'zpool clear'. + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test FAULTED 0 0 0 bad intent log + c3t2d0 ONLINE 0 0 0 + logs FAULTED 0 0 0 bad intent log + c5t3d0 UNAVAIL 0 0 0 cannot open + +There are two courses of action to resolve this problem. +If the validity of the pool from an application perspective requires +the pool changes then the log devices must be recovered. Make sure +power and cables are connected and that the affected device is +online. Then run ``zpool online`` and then ``zpool clear``: + +:: + + # zpool online test c5t3d0 + # zpool clear test + # zpool status test + pool: test + state: ONLINE + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test ONLINE 0 0 0 + c3t2d0 ONLINE 0 0 0 + logs ONLINE 0 0 0 + c5t3d0 ONLINE 0 0 0 + + errors: No known data errors + +The second alternative action is to ignore the most recent pool +changes that could not be read. To do this run ``zpool clear``: + +:: + + # zpool clear test + # zpool status test + pool: test + state: DEGRADED + status: One or more devices could not be opened. Sufficient replicas exist for + the pool to continue functioning in a degraded state. + action: Attach the missing device and online it using 'zpool online'. + see: https://openzfs.github.io/openzfs-docs/msg/ZFS-8000-2Q + scrub: none requested + config: + + NAME STATE READ WRITE CKSUM + test DEGRADED 0 0 0 + c3t2d0 ONLINE 0 0 0 + logs DEGRADED 0 0 0 + c5t3d0 UNAVAIL 0 0 0 cannot open + + errors: No known data errors + +Future log records will not use a failed log device but will be +written to the main pool. You should fix or replace any failed log +devices. + +.. rubric:: Details + +The Message ID: ``ZFS-8000-K4`` indicates that a log device is +missing or cannot be read. diff --git a/docs/msg/index.rst b/docs/msg/index.rst new file mode 100644 index 0000000..cbcbcdd --- /dev/null +++ b/docs/msg/index.rst @@ -0,0 +1,9 @@ +ZFS Messages +============ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :glob: + + ZFS-*/index