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