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