zinject.8: modernise

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Closes #12125

1 files changed, 238 insertions, 140 deletions

diff --git a/man/man8/zinject.8 b/man/man8/zinject.8
index ee6776fe7..a29346929 100644
--- a/man/man8/zinject.8
+++ b/man/man8/zinject.8
@@ -1,4 +1,3 @@
-'\" t
 .\"
 .\" CDDL HEADER START
 .\"
@@ -19,180 +18,279 @@
 .\"
 .\" CDDL HEADER END
 .\"
-.\"
 .\" Copyright 2013 Darik Horn <[email protected]>. 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 <[email protected]>
-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