From 3d00fbf9a0e54022375fa2c161898b3c3d15efec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=BD=D0=B0=D0=B1?= Date: Wed, 26 May 2021 15:48:24 +0200 Subject: [PATCH] zinject.8: modernise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-by: Brian Behlendorf Signed-off-by: Ahelenia Ziemiańska Closes #12125 --- man/man8/zinject.8 | 378 ++++++++++++++++++++++++++++----------------- 1 file 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 . 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 \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 -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