sys/contrib/openzfs/man/man8/zinject.8

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
  22 .\"
  23 .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS
  24 .\"
  25 .Dd May 26, 2021
  26 .Dt ZINJECT 8
  27 .Os
  28 .
  29 .Sh NAME
  30 .Nm zinject
  31 .Nd ZFS Fault Injector
  32 .Sh DESCRIPTION
  33 .Nm
  34 creates artificial problems in a ZFS pool by simulating data corruption
  35 or device failures.
  36 This program is dangerous.
  37 .
  38 .Sh SYNOPSIS
  39 .Bl -tag -width Ds
  40 .It Xo
  41 .Nm zinject
  42 .Xc
  43 List injection records.
  44 .
  45 .It Xo
  46 .Nm zinject
  47 .Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
  48 .Op Fl f Ar frequency
  49 .Fl amu
  50 .Op pool
  51 .Xc
  52 Force an error into the pool at a bookmark.
  53 .
  54 .It Xo
  55 .Nm zinject
  56 .Fl c Ar id Ns | Ns Sy all
  57 .Xc
  58 Cancel injection records.
  59 .
  60 .It Xo
  61 .Nm zinject
  62 .Fl d Ar vdev
  63 .Fl A Sy degrade Ns | Ns Sy fault
  64 .Ar pool
  65 .Xc
  66 Force a vdev into the DEGRADED or FAULTED state.
  67 .
  68 .It Xo
  69 .Nm zinject
  70 .Fl d Ar vdev
  71 .Fl D Ar latency : Ns Ar lanes
  72 .Ar pool
  73 .Xc
  74 Add an artificial delay to I/O requests on a particular
  75 device, such that the requests take a minimum of
  76 .Ar latency
  77 milliseconds to complete.
  78 Each delay has an associated number of
  79 .Ar lanes
  80 which defines the number of concurrent
  81 I/O requests that can be processed.
  82 .Pp
  83 For example, with a single lane delay of 10 ms
  84 .No (\& Ns Fl D Ar 10 : Ns Ar 1 ) ,
  85 the device will only be able to service a single I/O request
  86 at a time with each request taking 10 ms to complete.
  87 So, if only a single request is submitted every 10 ms, the
  88 average latency will be 10 ms; but if more than one request
  89 is submitted every 10 ms, the average latency will be more
  90 than 10 ms.
  91 .Pp
  92 Similarly, if a delay of 10 ms is specified to have two
  93 lanes
  94 .No (\& Ns Fl D Ar 10 : Ns Ar 2 ) ,
  95 then the device will be able to service
  96 two requests at a time, each with a minimum latency of 10 ms.
  97 So, if two requests are submitted every 10 ms, then
  98 the average latency will be 10 ms; but if more than two
  99 requests are submitted every 10 ms, the average latency
 100 will be more than 10 ms.
 101 .Pp
 102 Also note, these delays are additive.
 103 So two invocations of
 104 .Fl D Ar 10 : Ns Ar 1
 105 are roughly equivalent to a single invocation of
 106 .Fl D Ar 10 : Ns Ar 2 .
 107 This also means, that one can specify multiple
 108 lanes with differing target latencies.
 109 For example, an invocation of
 110 .Fl D Ar 10 : Ns Ar 1
 111 followed by
 112 .Fl D Ar 25 : Ns Ar 2
 113 will create 3 lanes on the device: one lane with a latency
 114 of 10 ms and two lanes with a 25 ms latency.
 115 .
 116 .It Xo
 117 .Nm zinject
 118 .Fl d Ar vdev
 119 .Op Fl e Ar device_error
 120 .Op Fl L Ar label_error
 121 .Op Fl T Ar failure
 122 .Op Fl f Ar frequency
 123 .Op Fl F
 124 .Ar pool
 125 .Xc
 126 Force a vdev error.
 127 .
 128 .It Xo
 129 .Nm zinject
 130 .Fl I
 131 .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs
 132 .Ar pool
 133 .Xc
 134 Simulate a hardware failure that fails to honor a cache flush.
 135 .
 136 .It Xo
 137 .Nm zinject
 138 .Fl p Ar function
 139 .Ar pool
 140 .Xc
 141 Panic inside the specified function.
 142 .
 143 .It Xo
 144 .Nm zinject
 145 .Fl t Sy data
 146 .Fl C Ar dvas
 147 .Op Fl e Ar device_error
 148 .Op Fl f Ar frequency
 149 .Op Fl l Ar level
 150 .Op Fl r Ar range
 151 .Op Fl amq
 152 .Ar path
 153 .Xc
 154 Force an error into the contents of a file.
 155 .
 156 .It Xo
 157 .Nm zinject
 158 .Fl t Sy dnode
 159 .Fl C Ar dvas
 160 .Op Fl e Ar device_error
 161 .Op Fl f Ar frequency
 162 .Op Fl l Ar level
 163 .Op Fl amq
 164 .Ar path
 165 .Xc
 166 Force an error into the metadnode for a file or directory.
 167 .
 168 .It Xo
 169 .Nm zinject
 170 .Fl t Ar mos_type
 171 .Fl C Ar dvas
 172 .Op Fl e Ar device_error
 173 .Op Fl f Ar frequency
 174 .Op Fl l Ar level
 175 .Op Fl r Ar range
 176 .Op Fl amqu
 177 .Ar pool
 178 .Xc
 179 Force an error into the MOS of a pool.
 180 .El
 181 .Sh OPTIONS
 182 .Bl -tag -width "-C dvas"
 183 .It Fl a
 184 Flush the ARC before injection.
 185 .It Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
 186 Force an error into the pool at this bookmark tuple.
 187 Each number is in hexadecimal, and only one block can be specified.
 188 .It Fl C Ar dvas
 189 Inject the given error only into specific DVAs.
 190 The mask should be specified as a list of 0-indexed DVAs separated by commas
 191 .No (e.g. Ar 0,2 Ns No ).
 192 This option is not applicable to logical data errors such as
 193 .Sy decompress
 194 and
 195 .Sy decrypt .
 196 .It Fl d Ar vdev
 197 A vdev specified by path or GUID.
 198 .It Fl e Ar device_error
 199 Specify
 200 .Bl -tag -compact -width "decompress"
 201 .It Sy checksum
 202 for an ECKSUM error,
 203 .It Sy decompress
 204 for a data decompression error,
 205 .It Sy decrypt
 206 for a data decryption error,
 207 .It Sy corrupt
 208 to flip a bit in the data after a read,
 209 .It Sy dtl
 210 for an ECHILD error,
 211 .It Sy io
 212 for an EIO error where reopening the device will succeed, or
 213 .It Sy nxio
 214 for an ENXIO error where reopening the device will fail.
 215 .El
 216 .Pp
 217 For EIO and ENXIO, the "failed" reads or writes still occur.
 218 The probe simply sets the error value reported by the I/O pipeline
 219 so it appears the read or write failed.
 220 Decryption errors only currently work with file data.
 221 .It Fl f Ar frequency
 222 Only inject errors a fraction of the time.
 223 Expressed as a real number percentage between
 224 .Sy 0.0001
 225 and
 226 .Sy 100 .
 227 .It Fl F
 228 Fail faster.
 229 Do fewer checks.
 230 .It Fl f Ar txgs
 231 Run for this many transaction groups before reporting failure.
 232 .It Fl h
 233 Print the usage message.
 234 .It Fl l Ar level
 235 Inject an error at a particular block level.
 236 The default is
 237 .Sy 0 .
 238 .It Fl L Ar label_error
 239 Set the label error region to one of
 240 .Sy nvlist ,
 241 .Sy pad1 ,
 242 .Sy pad2 ,
 243 or
 244 .Sy uber .
 245 .It Fl m
 246 Automatically remount the underlying filesystem.
 247 .It Fl q
 248 Quiet mode.
 249 Only print the handler number added.
 250 .It Fl r Ar range
 251 Inject an error over a particular logical range of an object, which
 252 will be translated to the appropriate blkid range according to the
 253 object's properties.
 254 .It Fl s Ar seconds
 255 Run for this many seconds before reporting failure.
 256 .It Fl T Ar failure
 257 Set the failure type to one of
 258 .Sy all ,
 259 .Sy claim ,
 260 .Sy free ,
 261 .Sy read ,
 262 or
 263 .Sy write .
 264 .It Fl t Ar mos_type
 265 Set this to
 266 .Bl -tag -compact -width "spacemap"
 267 .It Sy mos
 268 for any data in the MOS,
 269 .It Sy mosdir
 270 for an object directory,
 271 .It Sy config
 272 for the pool configuration,
 273 .It Sy bpobj
 274 for the block pointer list,
 275 .It Sy spacemap
 276 for the space map,
 277 .It Sy metaslab
 278 for the metaslab, or
 279 .It Sy errlog
 280 for the persistent error log.
 281 .El
 282 .It Fl u
 283 Unload the pool after injection.
 284 .El
 285 .
 286 .Sh ENVIRONMENT VARIABLES
 287 .Bl -tag -width "ZF"
 288 .It Ev ZFS_HOSTID
 289 Run
 290 .Nm
 291 in debug mode.
 292 .El
 293 .
 294 .Sh SEE ALSO
 295 .Xr zfs 8 ,
 296 .Xr zpool 8