| blob | 4f0bbae81212462ba216a9cddd2b8a00b9070740 |
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 .\"
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