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.
23 .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS
31 .Nd ZFS Fault Injector
34 creates artificial problems in a ZFS pool by simulating data corruption
36 This program is dangerous.
43 List injection records.
47 .Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
52 Force an error into the pool at a bookmark.
56 .Fl c Ar id Ns | Ns Sy all
58 Cancel injection records.
63 .Fl A Sy degrade Ns | Ns Sy fault
66 Force a vdev into the DEGRADED or FAULTED state.
71 .Fl D Ar latency : Ns Ar lanes
72 .Op Fl T Ar read|write
75 Add an artificial delay to I/O requests on a particular
76 device, such that the requests take a minimum of
78 milliseconds to complete.
79 Each delay has an associated number of
81 which defines the number of concurrent
82 I/O requests that can be processed.
84 For example, with a single lane delay of 10 ms
85 .No (\& Ns Fl D Ar 10 : Ns Ar 1 ) ,
86 the device will only be able to service a single I/O request
87 at a time with each request taking 10 ms to complete.
88 So, if only a single request is submitted every 10 ms, the
89 average latency will be 10 ms; but if more than one request
90 is submitted every 10 ms, the average latency will be more
93 Similarly, if a delay of 10 ms is specified to have two
95 .No (\& Ns Fl D Ar 10 : Ns Ar 2 ) ,
96 then the device will be able to service
97 two requests at a time, each with a minimum latency of 10 ms.
98 So, if two requests are submitted every 10 ms, then
99 the average latency will be 10 ms; but if more than two
100 requests are submitted every 10 ms, the average latency
101 will be more than 10 ms.
103 Also note, these delays are additive.
104 So two invocations of
105 .Fl D Ar 10 : Ns Ar 1
106 are roughly equivalent to a single invocation of
107 .Fl D Ar 10 : Ns Ar 2 .
108 This also means, that one can specify multiple
109 lanes with differing target latencies.
110 For example, an invocation of
111 .Fl D Ar 10 : Ns Ar 1
113 .Fl D Ar 25 : Ns Ar 2
114 will create 3 lanes on the device: one lane with a latency
115 of 10 ms and two lanes with a 25 ms latency.
120 .Op Fl e Ar device_error
121 .Op Fl L Ar label_error
123 .Op Fl f Ar frequency
132 .Op Fl s Ar seconds Ns | Ns Fl g Ar txgs
135 Simulate a hardware failure that fails to honor a cache flush.
142 Panic inside the specified function.
148 .Op Fl e Ar device_error
149 .Op Fl f Ar frequency
155 Force an error into the contents of a file.
161 .Op Fl e Ar device_error
162 .Op Fl f Ar frequency
167 Force an error into the metadnode for a file or directory.
173 .Op Fl e Ar device_error
174 .Op Fl f Ar frequency
180 Force an error into the MOS of a pool.
183 .Bl -tag -width "-C dvas"
185 Flush the ARC before injection.
186 .It Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
187 Force an error into the pool at this bookmark tuple.
188 Each number is in hexadecimal, and only one block can be specified.
190 Inject the given error only into specific DVAs.
191 The mask should be specified as a list of 0-indexed DVAs separated by commas
192 .No (e.g . Ar 0,2 Ns No ).
193 This option is not applicable to logical data errors such as
198 A vdev specified by path or GUID.
199 .It Fl e Ar device_error
201 .Bl -tag -compact -width "decompress"
205 for a data decompression error,
207 for a data decryption error,
209 to flip a bit in the data after a read,
213 for an EIO error where reopening the device will succeed, or
215 for an ENXIO error where reopening the device will fail.
218 For EIO and ENXIO, the "failed" reads or writes still occur.
219 The probe simply sets the error value reported by the I/O pipeline
220 so it appears the read or write failed.
221 Decryption errors only currently work with file data.
222 .It Fl f Ar frequency
223 Only inject errors a fraction of the time.
224 Expressed as a real number percentage between
232 Run for this many transaction groups before reporting failure.
234 Print the usage message.
236 Inject an error at a particular block level.
239 .It Fl L Ar label_error
240 Set the label error region to one of
247 Automatically remount the underlying filesystem.
250 Only print the handler number added.
252 Inject an error over a particular logical range of an object, which
253 will be translated to the appropriate blkid range according to the
256 Run for this many seconds before reporting failure.
258 Set the failure type to one of
267 .Bl -tag -compact -width "spacemap"
269 for any data in the MOS,
271 for an object directory,
273 for the pool configuration,
275 for the block pointer list,
281 for the persistent error log.
284 Unload the pool after injection.
287 .Sh ENVIRONMENT VARIABLES
projects / mirror_zfs.git / blob