]>
Commit | Line | Data |
---|---|---|
cf2129e6 DH |
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 | |
1d3ba0bf | 9 | .\" or https://opensource.org/licenses/CDDL-1.0. |
cf2129e6 DH |
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 | .\" | |
cf2129e6 | 21 | .\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved. |
76d1dde9 | 22 | .\" Copyright (c) 2024, Klara Inc. |
cf2129e6 | 23 | .\" |
3d00fbf9 AZ |
24 | .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS |
25 | .\" | |
76d1dde9 | 26 | .Dd April 4, 2024 |
3d00fbf9 AZ |
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 | |
cf2129e6 | 44 | List injection records. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 53 | Force an error into the pool at a bookmark. |
3d00fbf9 AZ |
54 | . |
55 | .It Xo | |
56 | .Nm zinject | |
57 | .Fl c Ar id Ns | Ns Sy all | |
58 | .Xc | |
cf2129e6 | 59 | Cancel injection records. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 67 | Force a vdev into the DEGRADED or FAULTED state. |
3d00fbf9 AZ |
68 | . |
69 | .It Xo | |
70 | .Nm zinject | |
71 | .Fl d Ar vdev | |
72 | .Fl D Ar latency : Ns Ar lanes | |
cbe88229 | 73 | .Op Fl T Ar read|write |
3d00fbf9 AZ |
74 | .Ar pool |
75 | .Xc | |
a737b415 | 76 | Add an artificial delay to I/O requests on a particular |
3d00fbf9 AZ |
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 | |
a737b415 | 83 | I/O requests that can be processed. |
3d00fbf9 AZ |
84 | .Pp |
85 | For example, with a single lane delay of 10 ms | |
86 | .No (\& Ns Fl D Ar 10 : Ns Ar 1 ) , | |
a737b415 | 87 | the device will only be able to service a single I/O request |
3d00fbf9 AZ |
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 | |
26ef0cc7 TH |
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. | |
3d00fbf9 | 93 | .Pp |
26ef0cc7 | 94 | Similarly, if a delay of 10 ms is specified to have two |
3d00fbf9 AZ |
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 | |
26ef0cc7 TH |
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. | |
3d00fbf9 AZ |
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 | |
26ef0cc7 | 116 | of 10 ms and two lanes with a 25 ms latency. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 128 | Force a vdev error. |
3d00fbf9 AZ |
129 | . |
130 | .It Xo | |
131 | .Nm zinject | |
c183d164 GW |
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 | |
3d00fbf9 AZ |
140 | .Fl I |
141 | .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs | |
142 | .Ar pool | |
143 | .Xc | |
cf2129e6 | 144 | Simulate a hardware failure that fails to honor a cache flush. |
3d00fbf9 AZ |
145 | . |
146 | .It Xo | |
147 | .Nm zinject | |
148 | .Fl p Ar function | |
149 | .Ar pool | |
150 | .Xc | |
cf2129e6 | 151 | Panic inside the specified function. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 164 | Force an error into the contents of a file. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 176 | Force an error into the metadnode for a file or directory. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 189 | Force an error into the MOS of a pool. |
3d00fbf9 AZ |
190 | .El |
191 | .Sh OPTIONS | |
192 | .Bl -tag -width "-C dvas" | |
193 | .It Fl a | |
cf2129e6 | 194 | Flush the ARC before injection. |
3d00fbf9 AZ |
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 | |
b46be903 | 201 | .No (e.g . Ar 0,2 Ns No ). |
3d00fbf9 AZ |
202 | This option is not applicable to logical data errors such as |
203 | .Sy decompress | |
ab7615d9 | 204 | and |
3d00fbf9 AZ |
205 | .Sy decrypt . |
206 | .It Fl d Ar vdev | |
cf2129e6 | 207 | A vdev specified by path or GUID. |
3d00fbf9 | 208 | .It Fl e Ar device_error |
cf2129e6 | 209 | Specify |
3d00fbf9 AZ |
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 | |
4725e543 | 222 | for an EIO error where reopening the device will succeed, |
3d00fbf9 | 223 | .It Sy nxio |
4725e543 RN |
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. | |
3d00fbf9 AZ |
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 | |
cf2129e6 | 243 | Run for this many transaction groups before reporting failure. |
3d00fbf9 | 244 | .It Fl h |
cf2129e6 | 245 | Print the usage message. |
3d00fbf9 AZ |
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 | |
cf2129e6 | 251 | Set the label error region to one of |
3d00fbf9 AZ |
252 | .Sy nvlist , |
253 | .Sy pad1 , | |
254 | .Sy pad2 , | |
255 | or | |
256 | .Sy uber . | |
257 | .It Fl m | |
cf2129e6 | 258 | Automatically remount the underlying filesystem. |
3d00fbf9 AZ |
259 | .It Fl q |
260 | Quiet mode. | |
261 | Only print the handler number added. | |
262 | .It Fl r Ar range | |
cf2129e6 DH |
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. | |
3d00fbf9 | 266 | .It Fl s Ar seconds |
cf2129e6 | 267 | Run for this many seconds before reporting failure. |
3d00fbf9 | 268 | .It Fl T Ar failure |
cf2129e6 | 269 | Set the failure type to one of |
3d00fbf9 | 270 | .Sy all , |
76d1dde9 | 271 | .Sy ioctl , |
3d00fbf9 AZ |
272 | .Sy claim , |
273 | .Sy free , | |
274 | .Sy read , | |
275 | or | |
276 | .Sy write . | |
277 | .It Fl t Ar mos_type | |
cf2129e6 | 278 | Set this to |
3d00fbf9 AZ |
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 | |
cf2129e6 | 296 | Unload the pool after injection. |
3d00fbf9 AZ |
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 |