ZINJECT(8) System Manager's Manual ZINJECT(8)

# [NAME](#NAME)

`zinject` — ZFS Fault Injector

# [DESCRIPTION](#DESCRIPTION)

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

# [SYNOPSIS](#SYNOPSIS)

`zinject`

List injection records.

`zinject` `-b` `objset`:`object`:`level`:`start`:`end` \[`-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**](#degrade)|[**fault**](#fault) `pool`

Force a vdev into the DEGRADED or FAULTED state.

`zinject` `-d` `vdev` `-D` `latency`:`lanes` \[`-T` `read|write`] `pool`

Add an artificial delay to I/O 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 I/O 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 I/O 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` are roughly equivalent to a single invocation of `-D` `10`:`2`. This also means, that 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` `seconds` `pool`

Add an artificial delay during the future import of a pool. This injector is automatically cleared after the import is finished.

`zinject` `-E` `delay` \[`-a`] \[`-m`] \[`-f` `freq`] \[`-l` `level`] \[`-r` `range`] \[`-T` `iotype`] \[`-t` `type`|`-b` `bookmark`]

Inject pipeline ready stage delays for the given object or bookmark. The delay is specified in milliseconds.

`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**](#data) `-C` `dvas` \[`-e` `device_error`] \[`-f` `frequency`] \[`-l` `level`] \[`-r` `range`] \[`-amq`] `path`

Force an error into the contents of a file.

`zinject` `-t` [**dnode**](#dnode) `-C` `dvas` \[`-e` `device_error`] \[`-f` `frequency`] \[`-l` `level`] \[`-amq`] `path`

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

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

Force an error into the MOS of a pool.

# [OPTIONS](#OPTIONS)

[`-a`](#a)

Flush the ARC before injection.

[`-b`](#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.

[`-C`](#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 (e.g. `0,2`). This option is not applicable to logical data errors such as **decompress** and **decrypt**.

[`-d`](#d) `vdev`

A vdev specified by path or GUID.

[`-e`](#e) `device_error`

Specify

[**checksum**](#checksum)

for an ECKSUM error,

[**decompress**](#decompress)

for a data decompression error,

[**decrypt**](#decrypt)

for a data decryption error,

[**corrupt**](#corrupt)

to flip a bit in the data after a read,

[**dtl**](#dtl)

for an ECHILD error,

[**io**](#io)

for an EIO error where reopening the device will succeed,

[**nxio**](#nxio)

for an ENXIO error where reopening the device will fail, or

[**noop**](#noop)

to drop the IO without executing it, and return success.

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.

[`-f`](#f) `frequency`

Only inject errors a fraction of the time. Expressed as a real number percentage between [**0.0001**](#0.0001) and [**100**](#100).

[`-F`](#F)

Fail faster. Do fewer checks.

[`-f`](#f~2) `txgs`

Run for this many transaction groups before reporting failure.

[`-h`](#h)

Print the usage message.

[`-l`](#l) `level`

Inject an error at a particular block level. The default is [**0**](#0).

[`-L`](#L) `label_error`

Set the label error region to one of [**nvlist**](#nvlist), [**pad1**](#pad1), [**pad2**](#pad2), or [**uber**](#uber).

[`-m`](#m)

Automatically remount the underlying filesystem.

[`-q`](#q)

Quiet mode. Only print the handler number added.

[`-r`](#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`](#s) `seconds`

Run for this many seconds before reporting failure.

[`-T`](#T) `type`

Inject the error into I/O of this type.

[**read**](#read), [**write**](#write), [**flush**](#flush), [**claim**](#claim), [**free**](#free)

Fundamental I/O types

[**all**](#all)

All fundamental I/O types

[**probe**](#probe)

Device probe I/O

[`-t`](#t) `mos_type`

Set this to

[**mos**](#mos)

for any data in the MOS,

[**mosdir**](#mosdir)

for an object directory,

[**config**](#config)

for the pool configuration,

[**bpobj**](#bpobj)

for the block pointer list,

[**spacemap**](#spacemap)

for the space map,

[**metaslab**](#metaslab)

for the metaslab, or

[**errlog**](#errlog)

for the persistent error log.

[`-u`](#u)

Unload the pool after injection.

# [ENVIRONMENT VARIABLES](#ENVIRONMENT_VARIABLES)

[`ZFS_HOSTID`](#ZFS_HOSTID)

Run `zinject` in debug mode.

# [SEE ALSO](#SEE_ALSO)

[zfs(8)](/man/os/zfs/zfs.8), [zpool(8)](/man/os/zfs/zpool.8)

January 14, 2025 OpenZFS

---

Document: zinject(8) from zfs 2.4.4-r3 (Chainguard OS)
Source: https://github.com/openzfs/zfs