man/man8/zinject.8

   1 '\" t
   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .\"
  23 .\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
  24 .\"
  25 .TH zinject 8 "2013 FEB 28" "ZFS on Linux" "System Administration Commands"
  26
  27 .SH NAME
  28 zinject \- ZFS Fault Injector
  29 .SH DESCRIPTION
  30 .BR zinject
  31 creates artificial problems in a ZFS pool by simulating data corruption or device failures. This program is dangerous.
  32 .SH SYNOPSIS
  33 .TP
  34 .B "zinject"
  35 List injection records.
  36 .TP
  37 .B "zinject \-b \fIobjset:object:level:blkd\fB [\-f \fIfrequency\fB] [\-amu] \fIpool\fB"
  38 Force an error into the pool at a bookmark.
  39 .TP
  40 .B "zinject \-c <\fIid\fB | all>
  41 Cancel injection records.
  42 .TP
  43 .B "zinject \-d \fIvdev\fB \-A <degrade|fault> \fIpool\fB
  44 Force a vdev into the DEGRADED or FAULTED state.
  45 .TP
  46 .B "zinject -d \fIvdev\fB -D latency:lanes \fIpool\fB
  47
  48 Add an artificial delay to IO requests on a particular
  49 device, such that the requests take a minimum of 'latency'
  50 milliseconds to complete. Each delay has an associated
  51 number of 'lanes' which defines the number of concurrent
  52 IO requests that can be processed.
  53
  54 For example, with a single lane delay of 10 ms (-D 10:1),
  55 the device will only be able to service a single IO request
  56 at a time with each request taking 10 ms to complete. So,
  57 if only a single request is submitted every 10 ms, the
  58 average latency will be 10 ms; but if more than one request
  59 is submitted every 10 ms, the average latency will be more
  60 than 10 ms.
  61
  62 Similarly, if a delay of 10 ms is specified to have two
  63 lanes (-D 10:2), then the device will be able to service
  64 two requests at a time, each with a minimum latency of
  65 10 ms. So, if two requests are submitted every 10 ms, then
  66 the average latency will be 10 ms; but if more than two
  67 requests are submitted every 10 ms, the average latency
  68 will be more than 10 ms.
  69
  70 Also note, these delays are additive. So two invocations
  71 of '-D 10:1', is roughly equivalent to a single invocation
  72 of '-D 10:2'. This also means, one can specify multiple
  73 lanes with differing target latencies. For example, an
  74 invocation of '-D 10:1' followed by '-D 25:2' will
  75 create 3 lanes on the device; one lane with a latency
  76 of 10 ms and two lanes with a 25 ms latency.
  77
  78 .TP
  79 .B "zinject \-d \fIvdev\fB [\-e \fIdevice_error\fB] [\-L \fIlabel_error\fB] [\-T \fIfailure\fB] [\-f \fIfrequency\fB] [\-F] \fIpool\fB"
  80 Force a vdev error.
  81 .TP
  82 .B "zinject \-I [\-s \fIseconds\fB | \-g \fItxgs\fB] \fIpool\fB"
  83 Simulate a hardware failure that fails to honor a cache flush.
  84 .TP
  85 .B "zinject \-p \fIfunction\fB \fIpool\fB
  86 Panic inside the specified function.
  87 .TP
  88 .B "zinject \-t data [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amq] \fIpath\fB"
  89 Force an error into the contents of a file.
  90 .TP
  91 .B "zinject \-t dnode [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-amq] \fIpath\fB"
  92 Force an error into the metadnode for a file or directory.
  93 .TP
  94 .B "zinject \-t \fImos_type\fB [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amqu] \fIpool\fB"
  95 Force an error into the MOS of a pool.
  96 .SH OPTIONS
  97 .TP
  98 .BI "\-a"
  99 Flush the ARC before injection.
 100 .TP
 101 .BI "\-b" " objset:object:level:start:end"
 102 Force an error into the pool at this bookmark tuple. Each number is
 103 in hexadecimal, and only one block can be specified.
 104 .TP
 105 .BI "\-C" " dvas"
 106 Inject the given error only into specific DVAs. The mask should be
 107 specified as a list of 0-indexed DVAs separated by commas (ex. '0,2'). This
 108 option is not applicable to logical data errors such as
 109 .BR "decompress"
 110 and
 111 .BR "decrypt" .
 112 .TP
 113 .BI "\-d" " vdev"
 114 A vdev specified by path or GUID.
 115 .TP
 116 .BI "\-e" " device_error"
 117 Specify
 118 .BR "checksum" " for an ECKSUM error,"
 119 .BR "decompress" " for a data decompression error,"
 120 .BR "decrypt" " for a data decryption error,"
 121 .BR "corrupt" " to flip a bit in the data after a read,"
 122 .BR "dtl" " for an ECHILD error,"
 123 .BR "io" " for an EIO error where reopening the device will succeed, or"
 124 .BR "nxio" " for an ENXIO error where reopening the device will fail."
 125 For EIO and ENXIO, the "failed" reads or writes still occur.  The probe simply
 126 sets the error value reported by the I/O pipeline so it appears the read or
 127 write failed.  Decryption errors only currently work with file data.
 128 .TP
 129 .BI "\-f" " frequency"
 130 Only inject errors a fraction of the time. Expressed as a real number
 131 percentage between 0.0001 and 100.
 132 .TP
 133 .BI "\-F"
 134 Fail faster. Do fewer checks.
 135 .TP
 136 .BI "\-g" " txgs"
 137 Run for this many transaction groups before reporting failure.
 138 .TP
 139 .BI "\-h"
 140 Print the usage message.
 141 .TP
 142 .BI "\-l" " level"
 143 Inject an error at a particular block level. The default is 0.
 144 .TP
 145 .BI "\-L" " label_error"
 146 Set the label error region to one of
 147 .BR " nvlist" ","
 148 .BR " pad1" ","
 149 .BR " pad2" ", or"
 150 .BR " uber" "."
 151 .TP
 152 .BI "\-m"
 153 Automatically remount the underlying filesystem.
 154 .TP
 155 .BI "\-q"
 156 Quiet mode. Only print the handler number added.
 157 .TP
 158 .BI "\-r" " range"
 159 Inject an error over a particular logical range of an object, which
 160 will be translated to the appropriate blkid range according to the
 161 object's properties.
 162 .TP
 163 .BI "\-s" " seconds"
 164 Run for this many seconds before reporting failure.
 165 .TP
 166 .BI "\-T" " failure"
 167 Set the failure type to one of
 168 .BR " all" ","
 169 .BR " claim" ","
 170 .BR " free" ","
 171 .BR " read" ", or"
 172 .BR " write" "."
 173 .TP
 174 .BI "\-t" " mos_type"
 175 Set this to
 176 .BR "mos " "for any data in the MOS,"
 177 .BR "mosdir " "for an object directory,"
 178 .BR "config " "for the pool configuration,"
 179 .BR "bpobj " "for the block pointer list,"
 180 .BR "spacemap " "for the space map,"
 181 .BR "metaslab " "for the metaslab, or"
 182 .BR "errlog " "for the persistent error log."
 183 .TP
 184 .BI "\-u"
 185 Unload the pool after injection.
 186
 187 .SH "ENVIRONMENT VARIABLES"
 188 .TP
 189 .B "ZINJECT_DEBUG"
 190 Run \fBzinject\fR in debug mode.
 191
 192 .SH "AUTHORS"
 193 This man page was written by Darik Horn <dajhorn@vanadac.com>
 194 excerpting the \fBzinject\fR usage message and source code.
 195
 196 .SH "SEE ALSO"
 197 .BR zpool (8),
 198 .BR zfs (8)