Add generic errata infrastructure

From time to time it may be necessary to inform the pool administrator
about an errata which impacts their pool.  These errata will by shown
to the administrator through the 'zpool status' and 'zpool import'
output as appropriate.  The errata must clearly describe the issue
detected, how the pool is impacted, and what action should be taken
to resolve the situation.  Additional information for each errata will
be provided at http://zfsonlinux.org/msg/ZFS-8000-ER.

To accomplish the above this patch adds the required infrastructure to
allow the kernel modules to notify the utilities that an errata has
been detected.  This is done through the ZPOOL_CONFIG_ERRATA uint64_t
which has been added to the pool configuration nvlist.

To add a new errata the following changes must be made:

* A new errata identifier must be assigned by adding a new enum value
  to the zpool_errata_t type.  New enums must be added to the end to
  preserve the existing ordering.

* Code must be added to detect the issue.  This does not strictly
  need to be done at pool import time but doing so will make the
  errata visible in 'zpool import' as well as 'zpool status'.  Once
  detected the spa->spa_errata member should be set to the new enum.

* If possible code should be added to clear the spa->spa_errata member
  once the errata has been resolved.

* The show_import() and status_callback() functions must be updated
  to include an informational message describing the errata.  This
  should include an action message describing what an administrator
  should do to address the errata.

* The documentation at http://zfsonlinux.org/msg/ZFS-8000-ER must be
  updated to describe the errata.  This space can be used to provide
  as much additional information as needed to fully describe the errata.
  A link to this documentation will be automatically generated in the
  output of 'zpool import' and 'zpool status'.

Original-idea-by: Tim Chase <tim@chase2k.com>
Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Tim Chase <tim@chase2k.com>
Signed-off-by: Richard Yao <ryao@gentoo.or
Issue #2094

diff --git a/cmd/zpool/zpool_main.c b/cmd/zpool/zpool_main.c
index f98bca14e15a05b021c62ee5eac41c61bbc4dce8..d496d0c72e26647633a01fcac876a2ce9451da9d 100644 (file)
--- a/cmd/zpool/zpool_main.c
+++ b/cmd/zpool/zpool_main.c
@@ -1609,6 +1609,7 @@ show_import(nvlist_t *config)
        char *msgid;
        nvlist_t *nvroot;
        zpool_status_t reason;
+       zpool_errata_t errata;
        const char *health;
        uint_t vsc;
        int namewidth;
@@ -1627,7 +1628,7 @@ show_import(nvlist_t *config)
            (uint64_t **)&vs, &vsc) == 0);
        health = zpool_state_to_name(vs->vs_state, vs->vs_aux);
 
-       reason = zpool_import_status(config, &msgid);
+       reason = zpool_import_status(config, &msgid, &errata);
 
        (void) printf(gettext("   pool: %s\n"), name);
        (void) printf(gettext("     id: %llu\n"), (u_longlong_t)guid);
@@ -1715,6 +1716,11 @@ show_import(nvlist_t *config)
                    "resilvered.\n"));
                break;
 
+       case ZPOOL_STATUS_ERRATA:
+               (void) printf(gettext(" status: Errata #%d detected.\n"),
+                   errata);
+               break;
+
        default:
                /*
                 * No other status can be seen when importing pools.
@@ -1736,6 +1742,17 @@ show_import(nvlist_t *config)
                        (void) printf(gettext(" action: The pool can be "
                            "imported using its name or numeric "
                            "identifier and\n\tthe '-f' flag.\n"));
+               } else if (reason == ZPOOL_STATUS_ERRATA) {
+                       switch (errata) {
+                       case ZPOOL_ERRATA_NONE:
+                               break;
+
+                       default:
+                               /*
+                                * All errata must contain an action message.
+                                */
+                               assert(0);
+                       }
                } else {
                        (void) printf(gettext(" action: The pool can be "
                            "imported using its name or numeric "
@@ -4126,12 +4143,13 @@ status_callback(zpool_handle_t *zhp, void *data)
        nvlist_t *config, *nvroot;
        char *msgid;
        zpool_status_t reason;
+       zpool_errata_t errata;
        const char *health;
        uint_t c;
        vdev_stat_t *vs;
 
        config = zpool_get_config(zhp, NULL);
-       reason = zpool_get_status(zhp, &msgid);
+       reason = zpool_get_status(zhp, &msgid, &errata);
 
        cbp->cb_count++;
 
@@ -4349,6 +4367,23 @@ status_callback(zpool_handle_t *zhp, void *data)
                    "'zpool clear'.\n"));
                break;
 
+       case ZPOOL_STATUS_ERRATA:
+               (void) printf(gettext("status: Errata #%d detected.\n"),
+                   errata);
+
+               switch (errata) {
+               case ZPOOL_ERRATA_NONE:
+                       break;
+
+               default:
+                       /*
+                        * All errata which allow the pool to be imported
+                        * must contain an action message.
+                        */
+                       assert(0);
+               }
+               break;
+
        default:
                /*
                 * The remaining errors can't actually be generated, yet.

diff --git a/include/libzfs.h b/include/libzfs.h
index 742f39f944e9f6d29e27fe84636532eb573f3af5..55dd34c99de18c96192c953c56a43f9000b7029b 100644 (file)
--- a/include/libzfs.h
+++ b/include/libzfs.h
@@ -312,6 +312,7 @@ typedef enum {
        ZPOOL_STATUS_IO_FAILURE_WAIT,   /* failed I/O, failmode 'wait' */
        ZPOOL_STATUS_IO_FAILURE_CONTINUE, /* failed I/O, failmode 'continue' */
        ZPOOL_STATUS_BAD_LOG,           /* cannot read log chain(s) */
+       ZPOOL_STATUS_ERRATA,            /* informational errata available */
 
        /*
         * If the pool has unsupported features but can still be opened in
@@ -347,8 +348,10 @@ typedef enum {
        ZPOOL_STATUS_OK
 } zpool_status_t;
 
-extern zpool_status_t zpool_get_status(zpool_handle_t *, char **);
-extern zpool_status_t zpool_import_status(nvlist_t *, char **);
+extern zpool_status_t zpool_get_status(zpool_handle_t *, char **,
+    zpool_errata_t *);
+extern zpool_status_t zpool_import_status(nvlist_t *, char **,
+    zpool_errata_t *);
 extern void zpool_dump_ddt(const ddt_stat_t *dds, const ddt_histogram_t *ddh);
 
 /*

diff --git a/include/sys/fs/zfs.h b/include/sys/fs/zfs.h
index c54721155a851ad93b76e323534e4e4a525e3570..50d099fc990cea984189a3d50acd137089735052 100644 (file)
--- a/include/sys/fs/zfs.h
+++ b/include/sys/fs/zfs.h
@@ -548,6 +548,7 @@ typedef struct zpool_rewind_policy {
 #define        ZPOOL_CONFIG_CAN_RDONLY         "can_rdonly"    /* not stored on disk */
 #define        ZPOOL_CONFIG_FEATURES_FOR_READ  "features_for_read"
 #define        ZPOOL_CONFIG_FEATURE_STATS      "feature_stats" /* not stored on disk */
+#define        ZPOOL_CONFIG_ERRATA             "errata"        /* not stored on disk */
 /*
  * The persistent vdev state is stored as separate values rather than a single
  * 'vdev_state' entry.  This is because a device can be in multiple states, such
@@ -704,6 +705,15 @@ typedef enum dsl_scan_state {
        DSS_NUM_STATES
 } dsl_scan_state_t;
 
+/*
+ * Errata described by http://zfsonlinux.org/msg/ZFS-8000-ER.  The ordering
+ * of this enum must be maintained to ensure the errata identifiers map to
+ * the correct documentation.  New errata may only be appended to the list
+ * and must contain corresponding documentation at the above link.
+ */
+typedef enum zpool_errata {
+       ZPOOL_ERRATA_NONE,
+} zpool_errata_t;
 
 /*
  * Vdev statistics.  Note: all fields should be 64-bit because this

diff --git a/include/sys/spa_impl.h b/include/sys/spa_impl.h
index 55515c1fc36953aa85ccb027c8245cee944df87b..90a32d3f0694b95e62e719dde9ebb946e00be6e3 100644 (file)
--- a/include/sys/spa_impl.h
+++ b/include/sys/spa_impl.h
@@ -236,6 +236,7 @@ struct spa {
        uint64_t        spa_deadman_calls;      /* number of deadman calls */
        hrtime_t        spa_sync_starttime;     /* starting time of spa_sync */
        uint64_t        spa_deadman_synctime;   /* deadman expiration timer */
+       uint64_t        spa_errata;             /* errata issues detected */
        spa_stats_t     spa_stats;              /* assorted spa statistics */
 
        /*

diff --git a/lib/libzfs/libzfs_status.c b/lib/libzfs/libzfs_status.c
index 0ef5f36d69f3a9f98cbe2956b890ff9061bae98a..534ff853a5bcdd484b47692e6156a4e28995a517 100644 (file)
--- a/lib/libzfs/libzfs_status.c
+++ b/lib/libzfs/libzfs_status.c
@@ -67,6 +67,7 @@ static char *zfs_msgid_table[] = {
        "ZFS-8000-HC",
        "ZFS-8000-JQ",
        "ZFS-8000-K4",
+       "ZFS-8000-ER",
 };
 
 #define        NMSGID  (sizeof (zfs_msgid_table) / sizeof (zfs_msgid_table[0]))
@@ -182,7 +183,7 @@ find_vdev_problem(nvlist_t *vdev, int (*func)(uint64_t, uint64_t, uint64_t))
  * only picks the most damaging of all the current errors to report.
  */
 static zpool_status_t
-check_status(nvlist_t *config, boolean_t isimport)
+check_status(nvlist_t *config, boolean_t isimport, zpool_errata_t *erratap)
 {
        nvlist_t *nvroot;
        vdev_stat_t *vs;
@@ -193,6 +194,7 @@ check_status(nvlist_t *config, boolean_t isimport)
        uint64_t stateval;
        uint64_t suspended;
        uint64_t hostid = 0;
+       uint64_t errata = 0;
        unsigned long system_hostid = gethostid() & 0xffffffff;
 
        verify(nvlist_lookup_uint64(config, ZPOOL_CONFIG_VERSION,
@@ -356,13 +358,22 @@ check_status(nvlist_t *config, boolean_t isimport)
                }
        }
 
+       /*
+        * Informational errata available.
+        */
+       (void) nvlist_lookup_uint64(config, ZPOOL_CONFIG_ERRATA, &errata);
+       if (errata) {
+               *erratap = errata;
+               return (ZPOOL_STATUS_ERRATA);
+       }
+
        return (ZPOOL_STATUS_OK);
 }
 
 zpool_status_t
-zpool_get_status(zpool_handle_t *zhp, char **msgid)
+zpool_get_status(zpool_handle_t *zhp, char **msgid, zpool_errata_t *errata)
 {
-       zpool_status_t ret = check_status(zhp->zpool_config, B_FALSE);
+       zpool_status_t ret = check_status(zhp->zpool_config, B_FALSE, errata);
 
        if (ret >= NMSGID)
                *msgid = NULL;
@@ -373,9 +384,9 @@ zpool_get_status(zpool_handle_t *zhp, char **msgid)
 }
 
 zpool_status_t
-zpool_import_status(nvlist_t *config, char **msgid)
+zpool_import_status(nvlist_t *config, char **msgid, zpool_errata_t *errata)
 {
-       zpool_status_t ret = check_status(config, B_TRUE);
+       zpool_status_t ret = check_status(config, B_TRUE, errata);
 
        if (ret >= NMSGID)
                *msgid = NULL;

diff --git a/module/zfs/spa.c b/module/zfs/spa.c
index 7052eec4ababd8bd5cc69dbe3a905bcc52b226f3..9e7a7b785a3261a655fcb7faa60b7a2fa26e504a 100644 (file)
--- a/module/zfs/spa.c
+++ b/module/zfs/spa.c
@@ -4083,6 +4083,8 @@ spa_tryimport(nvlist_t *tryconfig)
                    spa->spa_uberblock.ub_timestamp) == 0);
                VERIFY(nvlist_add_nvlist(config, ZPOOL_CONFIG_LOAD_INFO,
                    spa->spa_load_info) == 0);
+               VERIFY(nvlist_add_uint64(config, ZPOOL_CONFIG_ERRATA,
+                   spa->spa_errata) == 0);
 
                /*
                 * If the bootfs property exists on this pool then we

diff --git a/module/zfs/spa_config.c b/module/zfs/spa_config.c
index 9efa053616bc3b25bafaa6317c7b093adbe43f73..5b95a8e811e5dc6c3c5334c583894b3bd825e3cc 100644 (file)
--- a/module/zfs/spa_config.c
+++ b/module/zfs/spa_config.c
@@ -365,6 +365,8 @@ spa_config_generate(spa_t *spa, vdev_t *vd, uint64_t txg, int getstats)
            txg) == 0);
        VERIFY(nvlist_add_uint64(config, ZPOOL_CONFIG_POOL_GUID,
            spa_guid(spa)) == 0);
+       VERIFY(nvlist_add_uint64(config, ZPOOL_CONFIG_ERRATA,
+           spa->spa_errata) == 0);
        VERIFY(spa->spa_comment == NULL || nvlist_add_string(config,
            ZPOOL_CONFIG_COMMENT, spa->spa_comment) == 0);