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
133 .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs
136 Simulate a hardware failure that fails to honor a cache flush.
143 Panic inside the specified function.
149 .Op Fl e Ar device_error
150 .Op Fl f Ar frequency
156 Force an error into the contents of a file.
162 .Op Fl e Ar device_error
163 .Op Fl f Ar frequency
168 Force an error into the metadnode for a file or directory.
174 .Op Fl e Ar device_error
175 .Op Fl f Ar frequency
181 Force an error into the MOS of a pool.
184 .Bl -tag -width "-C dvas"
186 Flush the ARC before injection.
187 .It Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
188 Force an error into the pool at this bookmark tuple.
189 Each number is in hexadecimal, and only one block can be specified.
191 Inject the given error only into specific DVAs.
192 The mask should be specified as a list of 0-indexed DVAs separated by commas
193 .No (e.g . Ar 0,2 Ns No ).
194 This option is not applicable to logical data errors such as
199 A vdev specified by path or GUID.
200 .It Fl e Ar device_error
202 .Bl -tag -compact -width "decompress"
206 for a data decompression error,
208 for a data decryption error,
210 to flip a bit in the data after a read,
214 for an EIO error where reopening the device will succeed, or
216 for an ENXIO error where reopening the device will fail.
219 For EIO and ENXIO, the "failed" reads or writes still occur.
220 The probe simply sets the error value reported by the I/O pipeline
221 so it appears the read or write failed.
222 Decryption errors only currently work with file data.
223 .It Fl f Ar frequency
224 Only inject errors a fraction of the time.
225 Expressed as a real number percentage between
233 Run for this many transaction groups before reporting failure.
235 Print the usage message.
237 Inject an error at a particular block level.
240 .It Fl L Ar label_error
241 Set the label error region to one of
248 Automatically remount the underlying filesystem.
251 Only print the handler number added.
253 Inject an error over a particular logical range of an object, which
254 will be translated to the appropriate blkid range according to the
257 Run for this many seconds before reporting failure.
259 Set the failure type to one of
269 .Bl -tag -compact -width "spacemap"
271 for any data in the MOS,
273 for an object directory,
275 for the pool configuration,
277 for the block pointer list,
283 for the persistent error log.
286 Unload the pool after injection.
289 .Sh ENVIRONMENT VARIABLES
projects / mirror_zfs.git / blob