[mirror_zfs-debian.git] / man / man8 / zinject.8

'\" t
.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\"
.\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
.\"
.TH zinject 8 "2013 FEB 28" "ZFS on Linux" "System Administration Commands"

.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"
List injection records.
.TP
.B "zinject \-b \fIobjset:object:level:blkd\fB [\-f \fIfrequency\fB] [\-amu] \fIpool\fB"
Force an error into the pool at a bookmark.
.TP
.B "zinject \-c <\fIid\fB | all>
Cancel injection records.
.TP
.B "zinject \-d \fIvdev\fB \-A <degrade|fault> \fIpool\fB
Force a vdev into the DEGRADED or FAULTED state.
.TP
.B "zinject -d \fIvdev\fB -D latency:lanes \fIpool\fB

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
IO requests that can be processed.

For example, with a single lane delay of 10 ms (-D 10: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
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.

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
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
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"
Force a vdev error.
.TP
.B "zinject \-I [\-s \fIseconds\fB | \-g \fItxgs\fB] \fIpool\fB"
Simulate a hardware failure that fails to honor a cache flush.
.TP
.B "zinject \-p \fIfunction\fB \fIpool\fB
Panic inside the specified function.
.TP
.B "zinject \-t data [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amq] \fIpath\fB"
Force an error into the contents of a file.
.TP
.B "zinject \-t dnode [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-amq] \fIpath\fB"
Force an error into the metadnode for a file or directory.
.TP
.B "zinject \-t \fImos_type\fB [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amqu] \fIpool\fB"
Force an error into the MOS of a pool.
.SH OPTIONS
.TP
.BI "\-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 "\-d" " vdev"
A vdev specified by path or GUID.
.TP
.BI "\-e" " device_error"
Specify
.BR "checksum" " for an ECKSUM error,"
.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.
.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"
Run for this many transaction groups before reporting failure.
.TP
.BI "\-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"
Set the label error region to one of
.BR " nvlist" ","
.BR " pad1" ","
.BR " pad2" ", or"
.BR " uber" "."
.TP
.BI "\-m"
Automatically remount the underlying filesystem.
.TP
.BI "\-q"
Quiet mode. Only print the handler number added.
.TP
.BI "\-r" " 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"
Run for this many seconds before reporting failure.
.TP
.BI "\-T" " failure"
Set the failure type to one of
.BR " all" ","
.BR " claim" ","
.BR " free" ","
.BR " read" ", or"
.BR " write" "."
.TP
.BI "\-t" " 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"
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)
Commit	Line	Data
cf2129e6 DH	1	'\" t
	2	.\"
	3	.\" CDDL HEADER START
	4	.\"
	5	.\" The contents of this file are subject to the terms of the
	6	.\" Common Development and Distribution License (the "License").
	7	.\" You may not use this file except in compliance with the License.
	8	.\"
	9	.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
	10	.\" or http://www.opensolaris.org/os/licensing.
	11	.\" See the License for the specific language governing permissions
	12	.\" and limitations under the License.
	13	.\"
	14	.\" When distributing Covered Code, include this CDDL HEADER in each
	15	.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
	16	.\" If applicable, add the following below this CDDL HEADER, with the
	17	.\" fields enclosed by brackets "[]" replaced with your own identifying
	18	.\" information: Portions Copyright [yyyy] [name of copyright owner]
	19	.\"
	20	.\" CDDL HEADER END
	21	.\"
	22	.\"
	23	.\" Copyright 2013 Darik Horn <dajhorn@vanadac.com>. All rights reserved.
	24	.\"
	25	.TH zinject 8 "2013 FEB 28" "ZFS on Linux" "System Administration Commands"
	26
	27	.SH NAME
	28	zinject \- ZFS Fault Injector
	29	.SH DESCRIPTION
	30	.BR zinject
	31	creates artificial problems in a ZFS pool by simulating data corruption or device failures. This program is dangerous.
	32	.SH SYNOPSIS
	33	.TP
	34	.B "zinject"
	35	List injection records.
	36	.TP
	37	.B "zinject \-b \fIobjset:object:level:blkd\fB [\-f \fIfrequency\fB] [\-amu] \fIpool\fB"
	38	Force an error into the pool at a bookmark.
	39	.TP
	40	.B "zinject \-c <\fIid\fB \| all>
	41	Cancel injection records.
	42	.TP
	43	.B "zinject \-d \fIvdev\fB \-A <degrade\|fault> \fIpool\fB
	44	Force a vdev into the DEGRADED or FAULTED state.
	45	.TP
cae5b340 AX	46	.B "zinject -d \fIvdev\fB -D latency:lanes \fIpool\fB
	47
	48	Add an artificial delay to IO requests on a particular
	49	device, such that the requests take a minimum of 'latency'
	50	milliseconds to complete. Each delay has an associated
	51	number of 'lanes' which defines the number of concurrent
	52	IO requests that can be processed.
	53
	54	For example, with a single lane delay of 10 ms (-D 10:1),
	55	the device will only be able to service a single IO request
	56	at a time with each request taking 10 ms to complete. So,
	57	if only a single request is submitted every 10 ms, the
	58	average latency will be 10 ms; but if more than one request
	59	is submitted every 10 ms, the average latency will be more
	60	than 10 ms.
	61
	62	Similarly, if a delay of 10 ms is specified to have two
	63	lanes (-D 10:2), then the device will be able to service
	64	two requests at a time, each with a minimum latency of
	65	10 ms. So, if two requests are submitted every 10 ms, then
	66	the average latency will be 10 ms; but if more than two
	67	requests are submitted every 10 ms, the average latency
	68	will be more than 10 ms.
	69
	70	Also note, these delays are additive. So two invocations
	71	of '-D 10:1', is roughly equivalent to a single invocation
	72	of '-D 10:2'. This also means, one can specify multiple
	73	lanes with differing target latencies. For example, an
	74	invocation of '-D 10:1' followed by '-D 25:2' will
	75	create 3 lanes on the device; one lane with a latency
	76	of 10 ms and two lanes with a 25 ms latency.
	77
	78	.TP
	79	.B "zinject \-d \fIvdev\fB [\-e \fIdevice_error\fB] [\-L \fIlabel_error\fB] [\-T \fIfailure\fB] [\-f \fIfrequency\fB] [\-F] \fIpool\fB"
cf2129e6 DH	80	Force a vdev error.
	81	.TP
	82	.B "zinject \-I [\-s \fIseconds\fB \| \-g \fItxgs\fB] \fIpool\fB"
	83	Simulate a hardware failure that fails to honor a cache flush.
	84	.TP
	85	.B "zinject \-p \fIfunction\fB \fIpool\fB
	86	Panic inside the specified function.
	87	.TP
	88	.B "zinject \-t data [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amq] \fIpath\fB"
	89	Force an error into the contents of a file.
	90	.TP
	91	.B "zinject \-t dnode [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-amq] \fIpath\fB"
	92	Force an error into the metadnode for a file or directory.
	93	.TP
	94	.B "zinject \-t \fImos_type\fB [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amqu] \fIpool\fB"
	95	Force an error into the MOS of a pool.
	96	.SH OPTIONS
	97	.TP
	98	.BI "\-a"
	99	Flush the ARC before injection.
	100	.TP
	101	.BI "\-b" " objset:object:level:start:end"
	102	Force an error into the pool at this bookmark tuple. Each number is
cae5b340	103	in hexadecimal, and only one block can be specified.
cf2129e6 DH	104	.TP
	105	.BI "\-d" " vdev"
	106	A vdev specified by path or GUID.
	107	.TP
	108	.BI "\-e" " device_error"
	109	Specify
	110	.BR "checksum" " for an ECKSUM error,"
	111	.BR "dtl" " for an ECHILD error,"
	112	.BR "io" " for an EIO error where reopening the device will succeed, or"
	113	.BR "nxio" " for an ENXIO error where reopening the device will fail."
42f7b73b AX	114	For EIO and ENXIO, the "failed" reads or writes still occur. The probe simply
	115	sets the error value reported by the I/O pipeline so it appears the read or
	116	write failed.
cf2129e6 DH	117	.TP
cf2129e6 DH	118	.BI "\-f" " frequency"
cae5b340 AX	119	Only inject errors a fraction of the time. Expressed as a real number
cae5b340 AX	120	percentage between 0.0001 and 100.
cf2129e6 DH	121	.TP
	122	.BI "\-F"
	123	Fail faster. Do fewer checks.
	124	.TP
	125	.BI "\-g" " txgs"
	126	Run for this many transaction groups before reporting failure.
	127	.TP
	128	.BI "\-h"
	129	Print the usage message.
	130	.TP
	131	.BI "\-l" " level"
	132	Inject an error at a particular block level. The default is 0.
	133	.TP
	134	.BI "\-L" " label_error"
	135	Set the label error region to one of
	136	.BR " nvlist" ","
	137	.BR " pad1" ","
	138	.BR " pad2" ", or"
	139	.BR " uber" "."
	140	.TP
	141	.BI "\-m"
	142	Automatically remount the underlying filesystem.
	143	.TP
	144	.BI "\-q"
	145	Quiet mode. Only print the handler number added.
	146	.TP
	147	.BI "\-r" " range"
	148	Inject an error over a particular logical range of an object, which
	149	will be translated to the appropriate blkid range according to the
	150	object's properties.
	151	.TP
	152	.BI "\-s" " seconds"
	153	Run for this many seconds before reporting failure.
	154	.TP
	155	.BI "\-T" " failure"
	156	Set the failure type to one of
	157	.BR " all" ","
	158	.BR " claim" ","
	159	.BR " free" ","
	160	.BR " read" ", or"
	161	.BR " write" "."
	162	.TP
	163	.BI "\-t" " mos_type"
	164	Set this to
	165	.BR "mos " "for any data in the MOS,"
	166	.BR "mosdir " "for an object directory,"
	167	.BR "config " "for the pool configuration,"
	168	.BR "bpobj " "for the block pointer list,"
	169	.BR "spacemap " "for the space map,"
	170	.BR "metaslab " "for the metaslab, or"
	171	.BR "errlog " "for the persistent error log."
	172	.TP
	173	.BI "\-u"
	174	Unload the pool after injection.
	175
ea04106b AX	176	.SH "ENVIRONMENT VARIABLES"
	177	.TP
	178	.B "ZINJECT_DEBUG"
	179	Run \fBzinject\fR in debug mode.
	180
cf2129e6 DH	181	.SH "AUTHORS"
	182	This man page was written by Darik Horn <dajhorn@vanadac.com>
	183	excerpting the \fBzinject\fR usage message and source code.
	184
	185	.SH "SEE ALSO"
	186	.BR zpool (8),
	187	.BR zfs (8)