[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 [\-e \fIdevice_error\fB] [\-L \fIlabel_error\fB] [\-T \fIfailure\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 hexidecimal, 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."
.TP
.BI "\-f" " frequency"
Only inject errors a fraction of the time. Expressed as an integer
percentage between 1 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
	46	.B "zinject \-d \fIvdev\fB [\-e \fIdevice_error\fB] [\-L \fIlabel_error\fB] [\-T \fIfailure\fB] [\-F] \fIpool\fB"
	47	Force a vdev error.
	48	.TP
	49	.B "zinject \-I [\-s \fIseconds\fB \| \-g \fItxgs\fB] \fIpool\fB"
	50	Simulate a hardware failure that fails to honor a cache flush.
	51	.TP
	52	.B "zinject \-p \fIfunction\fB \fIpool\fB
	53	Panic inside the specified function.
	54	.TP
	55	.B "zinject \-t data [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amq] \fIpath\fB"
	56	Force an error into the contents of a file.
	57	.TP
	58	.B "zinject \-t dnode [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-amq] \fIpath\fB"
	59	Force an error into the metadnode for a file or directory.
	60	.TP
	61	.B "zinject \-t \fImos_type\fB [\-e \fIdevice_error\fB] [\-f \fIfrequency\fB] [\-l \fIlevel\fB] [\-r \fIrange\fB] [\-amqu] \fIpool\fB"
	62	Force an error into the MOS of a pool.
	63	.SH OPTIONS
	64	.TP
65	.BI "\-a"
66	Flush the ARC before injection.
67	.TP
68	.BI "\-b" " objset:object:level:start:end"
69	Force an error into the pool at this bookmark tuple. Each number is
70	in hexidecimal, and only one block can be specified.
71	.TP
72	.BI "\-d" " vdev"
73	A vdev specified by path or GUID.
74	.TP
75	.BI "\-e" " device_error"
76	Specify
77	.BR "checksum" " for an ECKSUM error,"
78	.BR "dtl" " for an ECHILD error,"
79	.BR "io" " for an EIO error where reopening the device will succeed, or"
80	.BR "nxio" " for an ENXIO error where reopening the device will fail."
81	.TP
82	.BI "\-f" " frequency"
83	Only inject errors a fraction of the time. Expressed as an integer
84	percentage between 1 and 100.
85	.TP
86	.BI "\-F"
87	Fail faster. Do fewer checks.
88	.TP
89	.BI "\-g" " txgs"
90	Run for this many transaction groups before reporting failure.
91	.TP
92	.BI "\-h"
93	Print the usage message.
94	.TP
95	.BI "\-l" " level"
96	Inject an error at a particular block level. The default is 0.
97	.TP
98	.BI "\-L" " label_error"
99	Set the label error region to one of
100	.BR " nvlist" ","
101	.BR " pad1" ","
102	.BR " pad2" ", or"
103	.BR " uber" "."
104	.TP
105	.BI "\-m"
106	Automatically remount the underlying filesystem.
107	.TP
108	.BI "\-q"
109	Quiet mode. Only print the handler number added.
110	.TP
111	.BI "\-r" " range"
112	Inject an error over a particular logical range of an object, which
113	will be translated to the appropriate blkid range according to the
114	object's properties.
115	.TP
116	.BI "\-s" " seconds"
117	Run for this many seconds before reporting failure.
118	.TP
119	.BI "\-T" " failure"
120	Set the failure type to one of
121	.BR " all" ","
122	.BR " claim" ","
123	.BR " free" ","
124	.BR " read" ", or"
125	.BR " write" "."
126	.TP
127	.BI "\-t" " mos_type"
128	Set this to
129	.BR "mos " "for any data in the MOS,"
130	.BR "mosdir " "for an object directory,"
131	.BR "config " "for the pool configuration,"
132	.BR "bpobj " "for the block pointer list,"
133	.BR "spacemap " "for the space map,"
134	.BR "metaslab " "for the metaslab, or"
135	.BR "errlog " "for the persistent error log."
136	.TP
137	.BI "\-u"
138	Unload the pool after injection.
139
ea04106b AX	140	.SH "ENVIRONMENT VARIABLES"
	141	.TP
	142	.B "ZINJECT_DEBUG"
	143	Run \fBzinject\fR in debug mode.
	144
cf2129e6 DH	145	.SH "AUTHORS"
	146	This man page was written by Darik Horn <dajhorn@vanadac.com>
	147	excerpting the \fBzinject\fR usage message and source code.
	148
	149	.SH "SEE ALSO"
	150	.BR zpool (8),
	151	.BR zfs (8)