Archive-Team
/
zfs
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 103 Wiki Activity

zinject.8: modernise 

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125
This commit is contained in:
наб 2021-05-26 15:48:24 +02:00 committed by Brian Behlendorf
parent 3365d2cf71
commit 3d00fbf9a0
1 changed files with 238 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

378
man/man8/zinject.8
View File

@ -1,4 +1,3 @@
'\" t
.\" .\"
.\" CDDL HEADER START .\" CDDL HEADER START
.\" .\"
@ -19,180 +18,279 @@
.\" .\"
.\" CDDL HEADER END .\" CDDL HEADER END
.\" .\"
.\"
.\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved. .\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
.\" .\"
.TH ZINJECT 8 "Aug 24, 2020" OpenZFS .\" lint-ok: WARNING: sections out of conventional order: Sh SYNOPSIS
.\"
.SH NAME .Dd May 26, 2021
zinject \- ZFS Fault Injector .Dt ZINJECT 8
.SH DESCRIPTION .Os
.BR zinject .
creates artificial problems in a ZFS pool by simulating data corruption or device failures. This program is dangerous. .Sh NAME
.SH SYNOPSIS .Nm zinject
.TP .Nd ZFS Fault Injector
.B "zinject" .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. List injection records.
.TP .
.B "zinject \-b \fIobjset:object:level:blkd\fB [\-f \fIfrequency\fB] [\-amu] \fIpool\fB" .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. Force an error into the pool at a bookmark.
.TP .
.B "zinject \-c <\fIid\fB | all> .It Xo
.Nm zinject
.Fl c Ar id Ns | Ns Sy all
.Xc
Cancel injection records. Cancel injection records.
.TP .
.B "zinject \-d \fIvdev\fB \-A <degrade|fault> \fIpool\fB .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. Force a vdev into the DEGRADED or FAULTED state.
.TP .
.B "zinject -d \fIvdev\fB -D latency:lanes \fIpool\fB .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 Add an artificial delay to IO requests on a particular
device, such that the requests take a minimum of 'latency' device, such that the requests take a minimum of
milliseconds to complete. Each delay has an associated .Ar latency
number of 'lanes' which defines the number of concurrent milliseconds to complete.
Each delay has an associated number of
.Ar lanes
which defines the number of concurrent
IO requests that can be processed. IO requests that can be processed.
.Pp
For example, with a single lane delay of 10 ms (-D 10:1), 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 the device will only be able to service a single IO request
at a time with each request taking 10 ms to complete. So, at a time with each request taking 10 ms to complete.
if only a single request is submitted every 10 ms, the So, if only a single request is submitted every 10 ms, the
average latency will be 10 ms; but if more than one request average latency will be 10 ms; but if more than one request
is submitted every 10 ms, the average latency will be more is submitted every 10 ms, the average latency will be more
than 10 ms. than 10 ms.
.Pp
Similarly, if a delay of 10 ms is specified to have two Similarly, if a delay of 10 ms is specified to have two
lanes (-D 10:2), then the device will be able to service lanes
two requests at a time, each with a minimum latency of .No (\& Ns Fl D Ar 10 : Ns Ar 2 ) ,
10 ms. So, if two requests are submitted every 10 ms, then 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 the average latency will be 10 ms; but if more than two
requests are submitted every 10 ms, the average latency requests are submitted every 10 ms, the average latency
will be more than 10 ms. will be more than 10 ms.
.Pp
Also note, these delays are additive. So two invocations Also note, these delays are additive.
of '-D 10:1', is roughly equivalent to a single invocation So two invocations of
of '-D 10:2'. This also means, one can specify multiple .Fl D Ar 10 : Ns Ar 1
lanes with differing target latencies. For example, an are roughly equivalent to a single invocation of
invocation of '-D 10:1' followed by '-D 25:2' will .Fl D Ar 10 : Ns Ar 2 .
create 3 lanes on the device; one lane with a latency 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. of 10 ms and two lanes with a 25 ms latency.
.
.TP .It Xo
.B "zinject \-d \fIvdev\fB [\-e \fIdevice_error\fB] [\-L \fIlabel_error\fB] [\-T \fIfailure\fB] [\-f \fIfrequency\fB] [\-F] \fIpool\fB" .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. Force a vdev error.
.TP .
.B "zinject \-I [\-s \fIseconds\fB | \-g \fItxgs\fB] \fIpool\fB" .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. Simulate a hardware failure that fails to honor a cache flush.
.TP .
.B "zinject \-p \fIfunction\fB \fIpool\fB .It Xo
.Nm zinject
.Fl p Ar function
.Ar pool
.Xc
Panic inside the specified function. Panic inside the specified function.
.TP .
.B "zinject \-t data [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amq] \fIpath\fB" .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. Force an error into the contents of a file.
.TP .
.B "zinject \-t dnode [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-amq] \fIpath\fB" .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. Force an error into the metadnode for a file or directory.
.TP .
.B "zinject \-t \fImos_type\fB [\-C \fIdvas\fB] [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amqu] \fIpool\fB" .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. Force an error into the MOS of a pool.
.SH OPTIONS .El
.TP .Sh OPTIONS
.BI "\-a" .Bl -tag -width "-C dvas"
.It Fl a
Flush the ARC before injection. Flush the ARC before injection.
.TP .It Fl b Ar objset : Ns Ar object : Ns Ar level : Ns Ar start : Ns Ar end
.BI "\-b" " objset:object:level:start:end" Force an error into the pool at this bookmark tuple.
Force an error into the pool at this bookmark tuple. Each number is Each number is in hexadecimal, and only one block can be specified.
in hexadecimal, and only one block can be specified. .It Fl C Ar dvas
.TP Inject the given error only into specific DVAs.
.BI "\-C" " dvas" The mask should be specified as a list of 0-indexed DVAs separated by commas
Inject the given error only into specific DVAs. The mask should be .No (ex. Ar 0,2 Ns No ).
specified as a list of 0-indexed DVAs separated by commas (ex. '0,2'). This This option is not applicable to logical data errors such as
option is not applicable to logical data errors such as .Sy decompress
.BR "decompress"
and and
.BR "decrypt" . .Sy decrypt .
.TP .It Fl d Ar vdev
.BI "\-d" " vdev"
A vdev specified by path or GUID. A vdev specified by path or GUID.
.TP .It Fl e Ar device_error
.BI "\-e" " device_error"
Specify Specify
.BR "checksum" " for an ECKSUM error," .Bl -tag -compact -width "decompress"
.BR "decompress" " for a data decompression error," .It Sy checksum
.BR "decrypt" " for a data decryption error," for an ECKSUM error,
.BR "corrupt" " to flip a bit in the data after a read," .It Sy decompress
.BR "dtl" " for an ECHILD error," for a data decompression error,
.BR "io" " for an EIO error where reopening the device will succeed, or" .It Sy decrypt
.BR "nxio" " for an ENXIO error where reopening the device will fail." for a data decryption error,
For EIO and ENXIO, the "failed" reads or writes still occur. The probe simply .It Sy corrupt
sets the error value reported by the I/O pipeline so it appears the read or to flip a bit in the data after a read,
write failed. Decryption errors only currently work with file data. .It Sy dtl
.TP for an ECHILD error,
.BI "\-f" " frequency" .It Sy io
Only inject errors a fraction of the time. Expressed as a real number for an EIO error where reopening the device will succeed, or
percentage between 0.0001 and 100. .It Sy nxio
.TP for an ENXIO error where reopening the device will fail.
.BI "\-F" .El
Fail faster. Do fewer checks. .Pp
.TP For EIO and ENXIO, the "failed" reads or writes still occur.
.BI "\-g" " txgs" 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. Run for this many transaction groups before reporting failure.
.TP .It Fl h
.BI "\-h"
Print the usage message. Print the usage message.
.TP .It Fl l Ar level
.BI "\-l" " level" Inject an error at a particular block level.
Inject an error at a particular block level. The default is 0. The default is
.TP .Sy 0 .
.BI "\-L" " label_error" .It Fl L Ar label_error
Set the label error region to one of Set the label error region to one of
.BR " nvlist" "," .Sy nvlist ,
.BR " pad1" "," .Sy pad1 ,
.BR " pad2" ", or" .Sy pad2 ,
.BR " uber" "." or
.TP .Sy uber .
.BI "\-m" .It Fl m
Automatically remount the underlying filesystem. Automatically remount the underlying filesystem.
.TP .It Fl q
.BI "\-q" Quiet mode.
Quiet mode. Only print the handler number added. Only print the handler number added.
.TP .It Fl r Ar range
.BI "\-r" " range"
Inject an error over a particular logical range of an object, which Inject an error over a particular logical range of an object, which
will be translated to the appropriate blkid range according to the will be translated to the appropriate blkid range according to the
object's properties. object's properties.
.TP .It Fl s Ar seconds
.BI "\-s" " seconds"
Run for this many seconds before reporting failure. Run for this many seconds before reporting failure.
.TP .It Fl T Ar failure
.BI "\-T" " failure"
Set the failure type to one of Set the failure type to one of
.BR " all" "," .Sy all ,
.BR " claim" "," .Sy claim ,
.BR " free" "," .Sy free ,
.BR " read" ", or" .Sy read ,
.BR " write" "." or
.TP .Sy write .
.BI "\-t" " mos_type" .It Fl t Ar mos_type
Set this to Set this to
.BR "mos " "for any data in the MOS," .Bl -tag -compact -width "spacemap"
.BR "mosdir " "for an object directory," .It Sy mos
.BR "config " "for the pool configuration," for any data in the MOS,
.BR "bpobj " "for the block pointer list," .It Sy mosdir
.BR "spacemap " "for the space map," for an object directory,
.BR "metaslab " "for the metaslab, or" .It Sy config
.BR "errlog " "for the persistent error log." for the pool configuration,
.TP .It Sy bpobj
.BI "\-u" 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. Unload the pool after injection.
.El
.SH "ENVIRONMENT VARIABLES" .
.TP .Sh ENVIRONMENT VARIABLES
.B "ZINJECT_DEBUG" .Bl -tag -width "ZF"
Run \fBzinject\fR in debug mode. .It Ev ZFS_HOSTID
Run
.SH "AUTHORS" .Nm
This man page was written by Darik Horn <dajhorn@vanadac.com> in debug mode.
excerpting the \fBzinject\fR usage message and source code. .El
.
.SH "SEE ALSO" .Sh SEE ALSO
.BR zpool (8), .Xr zfs 8 ,
.BR zfs (8) .Xr zpool 8