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.
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.
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]
21 .\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
22 .\" Copyright (c) 2024, Klara Inc.
24 .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS
32 .Nd ZFS Fault Injector
35 creates artificial problems in a ZFS pool by simulating data corruption
37 This program is dangerous.
44 List injection records.
48 .Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
53 Force an error into the pool at a bookmark.
57 .Fl c Ar id Ns | Ns Sy all
59 Cancel injection records.
64 .Fl A Sy degrade Ns | Ns Sy fault
67 Force a vdev into the DEGRADED or FAULTED state.
72 .Fl D Ar latency : Ns Ar lanes
73 .Op Fl T Ar read|write
76 Add an artificial delay to I/O requests on a particular
77 device, such that the requests take a minimum of
79 milliseconds to complete.
80 Each delay has an associated number of
82 which defines the number of concurrent
83 I/O requests that can be processed.
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
94 Similarly, if a delay of 10 ms is specified to have two
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.
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
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.
121 .Op Fl e Ar device_error
122 .Op Fl L Ar label_error
124 .Op Fl f Ar frequency
135 Add an artificial delay during the future import of a pool.
136 This injector is automatically cleared after the import is finished.
141 .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs
144 Simulate a hardware failure that fails to honor a cache flush.
151 Panic inside the specified function.
157 .Op Fl e Ar device_error
158 .Op Fl f Ar frequency
164 Force an error into the contents of a file.
170 .Op Fl e Ar device_error
171 .Op Fl f Ar frequency
176 Force an error into the metadnode for a file or directory.
182 .Op Fl e Ar device_error
183 .Op Fl f Ar frequency
189 Force an error into the MOS of a pool.
192 .Bl -tag -width "-C dvas"
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.
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
207 A vdev specified by path or GUID.
208 .It Fl e Ar device_error
210 .Bl -tag -compact -width "decompress"
214 for a data decompression error,
216 for a data decryption error,
218 to flip a bit in the data after a read,
222 for an EIO error where reopening the device will succeed,
224 for an ENXIO error where reopening the device will fail, or
226 to drop the IO without executing it, and return success.
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
243 Run for this many transaction groups before reporting failure.
245 Print the usage message.
247 Inject an error at a particular block level.
250 .It Fl L Ar label_error
251 Set the label error region to one of
258 Automatically remount the underlying filesystem.
261 Only print the handler number added.
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
267 Run for this many seconds before reporting failure.
269 Set the failure type to one of
279 .Bl -tag -compact -width "spacemap"
281 for any data in the MOS,
283 for an object directory,
285 for the pool configuration,
287 for the block pointer list,
293 for the persistent error log.
296 Unload the pool after injection.
299 .Sh ENVIRONMENT VARIABLES
projects / FreeBSD / FreeBSD.git / blob