cddl/usr.sbin/zfsd/case_file.h

   1 /*-
   2  * Copyright (c) 2011, 2012, 2013 Spectra Logic Corporation
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions, and the following disclaimer,
  10  *    without modification.
  11  * 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12  *    substantially similar to the "NO WARRANTY" disclaimer below
  13  *    ("Disclaimer") and any redistribution must be conditioned upon
  14  *    including a substantially similar Disclaimer requirement for further
  15  *    binary redistribution.
  16  *
  17  * NO WARRANTY
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22  * HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGES.
  29  *
  30  * Authors: Justin T. Gibbs     (Spectra Logic Corporation)
  31  *
  32  * $FreeBSD$
  33  */
  34
  35 /**
  36  * \file case_file.h
  37  *
  38  * CaseFile objects aggregate vdev faults that may require ZFSD action
  39  * in order to maintain the health of a ZFS pool.
  40  *
  41  * Header requirements:
  42  *
  43  *    #include <list>
  44  *
  45  *    #include "callout.h"
  46  *    #include "zfsd_event.h"
  47  */
  48 #ifndef _CASE_FILE_H_
  49 #define _CASE_FILE_H_
  50
  51 /*=========================== Forward Declarations ===========================*/
  52 class CaseFile;
  53 class Vdev;
  54
  55 /*============================= Class Definitions ============================*/
  56 /*------------------------------- CaseFileList -------------------------------*/
  57 /**
  58  * CaseFileList is a specialization of the standard list STL container.
  59  */
  60 typedef std::list< CaseFile *> CaseFileList;
  61
  62 /*--------------------------------- CaseFile ---------------------------------*/
  63 /**
  64  * A CaseFile object is instantiated anytime a vdev for an active pool
  65  * experiences an I/O error, is faulted by ZFS, or is determined to be
  66  * missing/removed.
  67  *
  68  * A vdev may have at most one CaseFile.
  69  *
  70  * CaseFiles are retired when a vdev leaves an active pool configuration
  71  * or an action is taken to resolve the issues recorded in the CaseFile.
  72  *
  73  * Logging a case against a vdev does not imply that an immediate action
  74  * to resolve a fault is required or even desired.  For example, a CaseFile
  75  * must accumulate a number of I/O errors in order to flag a device as
  76  * degraded.
  77  *
  78  * Vdev I/O errors are not recorded in ZFS label inforamation.  For this
  79  * reasons, CaseFile%%s with accumulated I/O error events are serialized
  80  * to the file system so that they survive across boots.  Currently all
  81  * other fault types can be reconstructed from ZFS label information, so
  82  * CaseFile%%s for missing, faulted, or degradded members are just recreated
  83  * at ZFSD startup instead of being deserialized from the file system.
  84  */
  85 class CaseFile
  86 {
  87 public:
  88         /**
  89          * \brief Find a CaseFile object by a vdev's pool/vdev GUID tuple.
  90          *
  91          * \param poolGUID  Pool GUID for the vdev of the CaseFile to find.
  92          *                  If InvalidGuid, then only match the vdev GUID
  93          *                  instead of both pool and vdev GUIDs.
  94          * \param vdevGUID  Vdev GUID for the vdev of the CaseFile to find.
  95          *
  96          * \return  If found, a pointer to a valid CaseFile object.
  97          *          Otherwise NULL.
  98          */
  99         static CaseFile *Find(DevdCtl::Guid poolGUID, DevdCtl::Guid vdevGUID);
 100
 101         /**
 102          * \brief Find a CaseFile object by a vdev's current/last known
 103          *        physical path.
 104          *
 105          * \param physPath  Physical path of the vdev of the CaseFile to find.
 106          *
 107          * \return  If found, a pointer to a valid CaseFile object.
 108          *          Otherwise NULL.
 109          */
 110         static CaseFile *Find(const string &physPath);
 111
 112         /**
 113          * \brief ReEvaluate all open cases whose pool guid matches the argument
 114          *
 115          * \param poolGUID      Only reevaluate cases for this pool
 116          * \param event         Try to consume this event with the casefile
 117          */
 118         static void ReEvaluateByGuid(DevdCtl::Guid poolGUID,
 119                                      const ZfsEvent &event);
 120
 121         /**
 122          * \brief Create or return an existing active CaseFile for the
 123          *        specified vdev.
 124          *
 125          * \param vdev  The vdev object for which to find/create a CaseFile.
 126          *
 127          * \return  A reference to a valid CaseFile object.
 128          */
 129         static CaseFile &Create(Vdev &vdev);
 130
 131         /**
 132          * \brief Deserialize all serialized CaseFile objects found in
 133          *        the file system.
 134          */
 135         static void      DeSerialize();
 136
 137         /**
 138          * \brief Emit syslog data on all active CaseFile%%s in the system.
 139          */
 140         static void      LogAll();
 141
 142         /**
 143          * \brief Destroy the in-core cache of CaseFile data.
 144          *
 145          * This routine does not disturb the on disk, serialized, CaseFile
 146          * data.
 147          */
 148         static void      PurgeAll();
 149
 150         DevdCtl::Guid PoolGUID()       const;
 151         DevdCtl::Guid VdevGUID()       const;
 152         vdev_state    VdevState()      const;
 153         const string &PoolGUIDString() const;
 154         const string &VdevGUIDString() const;
 155         const string &PhysicalPath()   const;
 156
 157         /**
 158          * \brief Attempt to resolve this CaseFile using the disk
 159          *        resource at the given device/physical path/vdev object
 160          *        tuple.
 161          *
 162          * \param devPath   The devfs path for the disk resource.
 163          * \param physPath  The physical path information reported by
 164          *                  the disk resource.
 165          * \param vdev      If the disk contains ZFS label information,
 166          *                  a pointer to the disk label's vdev object
 167          *                  data.  Otherwise NULL.
 168          *
 169          * \return  True if this event was consumed by this CaseFile.
 170          */
 171         bool ReEvaluate(const string &devPath, const string &physPath,
 172                         Vdev *vdev);
 173
 174         /**
 175          * \brief Update this CaseFile in light of the provided ZfsEvent.
 176          *
 177          * Must be virtual so it can be overridden in the unit tests
 178          *
 179          * \param event  The ZfsEvent to evaluate.
 180          *
 181          * \return  True if this event was consumed by this CaseFile.
 182          */
 183         virtual bool ReEvaluate(const ZfsEvent &event);
 184
 185         /**
 186          * \brief Register an itimer callout for the given event, if necessary
 187          */
 188         virtual void RegisterCallout(const DevdCtl::Event &event);
 189
 190         /**
 191          * \brief Close a case if it is no longer relevant.
 192          *
 193          * This method deals with cases tracking soft errors.  Soft errors
 194          * will be discarded should a remove event occur within a short period
 195          * of the soft errors being reported.  We also discard the events
 196          * if the vdev is marked degraded or failed.
 197          *
 198          * \return  True if the case is closed.  False otherwise.
 199          */
 200         bool CloseIfSolved();
 201
 202         /**
 203          * \brief Emit data about this CaseFile via syslog(3).
 204          */
 205         void Log();
 206
 207         /**
 208          * \brief Whether we should degrade this vdev
 209          */
 210         bool ShouldDegrade() const;
 211
 212         /**
 213          * \brief Whether we should fault this vdev
 214          */
 215         bool ShouldFault() const;
 216
 217 protected:
 218         enum {
 219                 /**
 220                  * The number of soft errors on a vdev required
 221                  * to transition a vdev from healthy to degraded
 222                  * status.
 223                  */
 224                 ZFS_DEGRADE_IO_COUNT = 50
 225         };
 226
 227         static CalloutFunc_t OnGracePeriodEnded;
 228
 229         /**
 230          * \brief scandir(3) filter function used to find files containing
 231          *        serialized CaseFile data.
 232          *
 233          * \param dirEntry  Directory entry for the file to filter.
 234          *
 235          * \return  Non-zero for a file to include in the selection,
 236          *          otherwise 0.
 237          */
 238         static int  DeSerializeSelector(const struct dirent *dirEntry);
 239
 240         /**
 241          * \brief Given the name of a file containing serialized events from a
 242          *        CaseFile object, create/update an in-core CaseFile object
 243          *        representing the serialized data.
 244          *
 245          * \param fileName  The name of a file containing serialized events
 246          *                  from a CaseFile object.
 247          */
 248         static void DeSerializeFile(const char *fileName);
 249
 250         /** Constructor. */
 251         CaseFile(const Vdev &vdev);
 252
 253         /**
 254          * Destructor.
 255          * Must be virtual so it can be subclassed in the unit tests
 256          */
 257         virtual ~CaseFile();
 258
 259         /**
 260          * \brief Reload state for the vdev associated with this CaseFile.
 261          *
 262          * \return  True if the refresh was successful.  False if the system
 263          *          has no record of the pool or vdev for this CaseFile.
 264          */
 265         virtual bool RefreshVdevState();
 266
 267         /**
 268          * \brief Free all events in the m_events list.
 269          */
 270         void PurgeEvents();
 271
 272         /**
 273          * \brief Free all events in the m_tentativeEvents list.
 274          */
 275         void PurgeTentativeEvents();
 276
 277         /**
 278          * \brief Commit to file system storage.
 279          */
 280         void Serialize();
 281
 282         /**
 283          * \brief Retrieve event data from a serialization stream.
 284          *
 285          * \param caseStream  The serializtion stream to parse.
 286          */
 287         void DeSerialize(std::ifstream &caseStream);
 288
 289         /**
 290          * \brief Serializes the supplied event list and writes it to fd
 291          *
 292          * \param prefix  If not NULL, this prefix will be prepended to
 293          *                every event in the file.
 294          */
 295         void SerializeEvList(const DevdCtl::EventList events, int fd,
 296                              const char* prefix=NULL) const;
 297
 298         /**
 299          * \brief Unconditionally close a CaseFile.
 300          */
 301         virtual void Close();
 302
 303         /**
 304          * \brief Callout callback invoked when the remove timer grace
 305          *        period expires.
 306          *
 307          * If no remove events are received prior to the grace period
 308          * firing, then any tentative events are promoted and counted
 309          * against the health of the vdev.
 310          */
 311         void OnGracePeriodEnded();
 312
 313         /**
 314          * \brief Attempt to activate a spare on this case's pool.
 315          *
 316          * Call this whenever a pool becomes degraded.  It will look for any
 317          * spare devices and activate one to replace the casefile's vdev.  It
 318          * will _not_ close the casefile; that should only happen when the
 319          * missing drive is replaced or the user promotes the spare.
 320          *
 321          * \return True if a spare was activated
 322          */
 323         bool ActivateSpare();
 324
 325         /**
 326          * \brief replace a pool's vdev with another
 327          *
 328          * \param vdev_type   The type of the new vdev.  Usually either
 329          *                    VDEV_TYPE_DISK or VDEV_TYPE_FILE
 330          * \param path        The file system path to the new vdev
 331          * \param isspare     Whether the new vdev is a spare
 332          *
 333          * \return            true iff the replacement was successful
 334          */
 335         bool Replace(const char* vdev_type, const char* path, bool isspare);
 336
 337         /**
 338          * \brief Which vdev, if any, is replacing ours.
 339          *
 340          * \param zhp           Pool handle state from the caller context
 341          *
 342          * \return              the vdev that is currently replacing ours,
 343          *                      or NonexistentVdev if there isn't one.
 344          */
 345         Vdev BeingReplacedBy(zpool_handle_t *zhp);
 346
 347         /**
 348          * \brief All CaseFiles being tracked by ZFSD.
 349          */
 350         static CaseFileList  s_activeCases;
 351
 352         /**
 353          * \brief The file system path to serialized CaseFile data.
 354          */
 355         static const string  s_caseFilePath;
 356
 357         /**
 358          * \brief The time ZFSD waits before promoting a tentative event
 359          *        into a permanent event.
 360          */
 361         static const timeval s_removeGracePeriod;
 362
 363         /**
 364          * \brief A list of soft error events counted against the health of
 365          *        a vdev.
 366          */
 367         DevdCtl::EventList m_events;
 368
 369         /**
 370          * \brief A list of soft error events waiting for a grace period
 371          *        expiration before being counted against the health of
 372          *        a vdev.
 373          */
 374         DevdCtl::EventList m_tentativeEvents;
 375
 376         DevdCtl::Guid      m_poolGUID;
 377         DevdCtl::Guid      m_vdevGUID;
 378         vdev_state         m_vdevState;
 379         string             m_poolGUIDString;
 380         string             m_vdevGUIDString;
 381         string             m_vdevPhysPath;
 382
 383         /**
 384          * \brief Callout activated when a grace period
 385          */
 386         Callout           m_tentativeTimer;
 387
 388 private:
 389         nvlist_t        *CaseVdev(zpool_handle_t *zhp)  const;
 390 };
 391
 392 inline DevdCtl::Guid
 393 CaseFile::PoolGUID() const
 394 {
 395         return (m_poolGUID);
 396 }
 397
 398 inline DevdCtl::Guid
 399 CaseFile::VdevGUID() const
 400 {
 401         return (m_vdevGUID);
 402 }
 403
 404 inline vdev_state
 405 CaseFile::VdevState() const
 406 {
 407         return (m_vdevState);
 408 }
 409
 410 inline const string &
 411 CaseFile::PoolGUIDString() const
 412 {
 413         return (m_poolGUIDString);
 414 }
 415
 416 inline const string &
 417 CaseFile::VdevGUIDString() const
 418 {
 419         return (m_vdevGUIDString);
 420 }
 421
 422 inline const string &
 423 CaseFile::PhysicalPath() const
 424 {
 425         return (m_vdevPhysPath);
 426 }
 427
 428 #endif /* _CASE_FILE_H_ */