cddl/usr.sbin/zfsd/zfsd.8

   1 .\"-
   2 .\" Copyright (c) 2016 Allan Jude
   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 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd May 26, 2016
  29 .Dt ZFSD 8
  30 .Os
  31 .Sh NAME
  32 .Nm zfsd
  33 .Nd ZFS fault management daemon
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl d
  37 .Sh DESCRIPTION
  38 .Nm
  39 attempts to resolve ZFS faults that the kernel can't resolve by itself.
  40 It listens to
  41 .Xr devctl 4
  42 events, which are how the kernel notifies userland of events such as I/O
  43 errors and disk removals.
  44 .Nm
  45 attempts to resolve these faults by activating or deactivating hot spares
  46 and onlining offline vdevs.
  47 .Pp
  48 The following options are available:
  49 .Bl -tag -width indent
  50 .It Fl d
  51 Run in the foreground instead of daemonizing.
  52 .El
  53 .Pp
  54 System administrators never interact with
  55 .Nm
  56 directly.
  57 Instead, they control its behavior indirectly through zpool configuration.
  58 There are two ways to influence
  59 .Nm :
  60 assigning hotspares and setting pool properties.
  61 Currently, only the
  62 .Em autoreplace
  63 property has any effect.
  64 See
  65 .Xr zpool 8
  66 for details.
  67 .Pp
  68 .Nm
  69 will attempt to resolve the following types of fault:
  70 .Bl -tag -width a
  71 .It device removal
  72 When a leaf vdev disappears,
  73 .Nm
  74 will activate any available hotspare.
  75 .It device arrival
  76 When a new GEOM device appears,
  77 .Nm
  78 will attempt to read its ZFS label, if any.
  79 If it matches a previously removed vdev on an active pool,
  80 .Nm
  81 will online it.
  82 Once resilvering completes, any active hotspare will detach automatically.
  83 .Pp
  84 If the new device has no ZFS label but its physical path matches the
  85 physical path of a previously removed vdev on an active pool, and that
  86 pool has the autoreplace property set, then
  87 .Nm
  88 will replace the missing vdev with the newly arrived device.
  89 Once resilvering completes, any active hotspare will detach automatically.
  90 .It vdev degrade or fault events
  91 If a vdev becomes degraded or faulted,
  92 .Nm
  93 will activate any available hotspare.
  94 .It I/O errors
  95 If a leaf vdev generates more than 50 I/O errors in a 60 second period, then
  96 .Nm
  97 will mark that vdev as
  98 .Em FAULTED .
  99 .Xr zfs 4
 100 will no longer issue any I/Os to it.
 101 .Nm
 102 will activate a hotspare if one is available.
 103 .It Checksum errors
 104 If a leaf vdev generates more than 50 checksum errors in a 60 second
 105 period, then
 106 .Nm
 107 will mark that vdev as
 108 .Em DEGRADED .
 109 .Xr zfs 4
 110 will still use it, but zfsd will activate a spare anyway.
 111 .It Spare addition
 112 If the system administrator adds a hotspare to a pool that is already degraded,
 113 .Nm
 114 will activate the spare.
 115 .It Resilver complete
 116 .Nm
 117 will detach any hotspare once a permanent replacement finishes resilvering.
 118 .It Physical path change
 119 If the physical path of an existing disk changes,
 120 .Nm
 121 will attempt to replace any missing disk with the same physical path,
 122 if its pool's autoreplace property is set.
 123 .El
 124 .Pp
 125 .Nm
 126 will log interesting events and its actions to syslog with facility
 127 .Em daemon
 128 and identity
 129 .Op zfsd .
 130 .El
 131 .Sh FILES
 132 .Bl -tag -width a -compact
 133 .It Pa /var/db/zfsd/cases
 134 When
 135 .Nm
 136 exits, it serializes any unresolved casefiles here,
 137 then reads them back in when next it starts up.
 138 .El
 139 .Sh SEE ALSO
 140 .Xr devctl 4 ,
 141 .Xr zfs 4 ,
 142 .Xr zpool 8
 143 .Sh HISTORY
 144 .Nm
 145 first appeared in
 146 .Fx 11.0 .
 147 .Sh AUTHORS
 148 .Nm
 149 was originally written by
 150 .An Justin Gibbs Aq Mt gibbs@FreeBSD.org
 151 and
 152 .An Alan Somers Aq Mt asomers@FreeBSD.org
 153 .Sh TODO
 154 In the future,
 155 .Nm
 156 should be able to resume a pool that became suspended due to device
 157 removals, if enough missing devices have returned.