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