NAME¶

zinject - ZFS Fault Injector

DESCRIPTION¶

zinject creates artificial problems in a ZFS pool by simulating data corruption or device failures. This program is dangerous.

SYNOPSIS¶

zinject

List injection records.

zinject -b objset:object:level:blkd [-f frequency] [-amu] pool

Force an error into the pool at a bookmark.

zinject -c <id | all>

Cancel injection records.

zinject -d vdev -A <degrade|fault> pool

Force a vdev into the DEGRADED or FAULTED state.

zinject -d vdev -D latency:lanes pool

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.

zinject -d vdev [-e device_error] [-L label_error] [-T failure] [-f frequency] [-F] pool

Force a vdev error.

zinject -I [-s seconds | -g txgs] pool

Simulate a hardware failure that fails to honor a cache flush.

zinject -p function pool

Panic inside the specified function.

zinject -t data [-e device_error] [-f frequency] [-l level] [-r range] [-amq] path

Force an error into the contents of a file.

zinject -t dnode [-e device_error] [-f frequency] [-l level] [-amq] path

Force an error into the metadnode for a file or directory.

zinject -t mos_type [-e device_error] [-f frequency] [-l level] [-r range] [-amqu] pool

Force an error into the MOS of a pool.

OPTIONS¶

-a

Flush the ARC before injection.

-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.

-d vdev

A vdev specified by path or GUID.

-e device_error

Specify checksum for an ECKSUM error, dtl for an ECHILD error, io for an EIO error where reopening the device will succeed, or nxio for an ENXIO error where reopening the device will fail.

-f frequency

Only inject errors a fraction of the time. Expressed as a real number percentage between 0.0001 and 100.

-F

Fail faster. Do fewer checks.

-g txgs

Run for this many transaction groups before reporting failure.

-h

Print the usage message.

-l level

Inject an error at a particular block level. The default is 0.

-L label_error

Set the label error region to one of nvlist, pad1, pad2, or uber.

-m

Automatically remount the underlying filesystem.

-q

Quiet mode. Only print the handler number added.

-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.

-s seconds

Run for this many seconds before reporting failure.

-T failure

Set the failure type to one of all, claim, free, read, or write.

-t mos_type

Set this to mos for any data in the MOS, mosdir for an object directory, config for the pool configuration, bpobj for the block pointer list, spacemap for the space map, metaslab for the metaslab, or errlog for the persistent error log.

-u

Unload the pool after injection.

ENVIRONMENT VARIABLES¶

ZINJECT_DEBUG

Run zinject in debug mode.

AUTHORS¶

This man page was written by Darik Horn <dajhorn@vanadac.com> excerpting the zinject usage message and source code.

SEE ALSO¶

zpool(8), zfs(8)