ZTEST(1)

ZTEST(1) | General Commands Manual | ZTEST(1)

# NAME

`ztest` — ZFS stress test utility

# SYNOPSIS

`ztest` | [`-EhV`] [`-a` shift] [`-B` path] [`-d` datasets] [`-F` loops] [`-f` path] [`-g` threshold] [`-i` count] [`-k` percent] [`-m` copies] [`-P` passtime] [`-p` name] [`-R` parity] [`-r` disks] [`-s` size] [`-T` time] [`-t` threads] [`-v` vdevs]

# DESCRIPTION

The `ztest` utility stress tests the DMU, ZAP, SPA components of ZFS from user space.

`ztest` provides a simple routine to test the functionality of a component task. These simple routines can then be used to stress test through parallel execution. Tests are run as child processes of the main process.

The checksum and compression functions are changed each time a dataset is opened to introduce varying combinations of checksum and compression from block to block among objects.

While tests are running, faults are injected into the pool to verify self-healing ability.

To verify that the on-disk consistency is never lost after a crash, child processes are killed at random with a SIGKILL signal, after which the parent process invokes a new child to run the test again on the same storage pool.

Many of the tests record the transaction group number as part of their data. When reading old data, tests verify that the transaction group number is less than the current, open state, transaction group to ensure the consistency of tests and detect unaccounted changes. It is advised that any new tests added to `ztest` should also perform the same check with transaction group numbers, if applicable.

The main `ztest` process uses an mmap(2) temporary file to pass information to child processes which allows shared memory to survive exec(3) syscall. A copy of the ztest_shared_hdr_t struct containing information on the size and number of shared structures in the file is always stored at offset 0 of the file.

For backwards compatibility testing `ztest` can invoke an alternative version of `ztest` after a `SIGKILL` signal using the `-B` flag.

The following options are available:

`-a` shift
  alignment shift (default: 9) use 0 for random
`-B` path
  alt ztest (default: <none>) alternate ztest path
`-d` datasets
  datasets (default: 7)
`-E`
  use existing pool instead of creating new one
`-F` loops
  freezeloops (default: 50) max loops in `spa_freeze`()
`-f` path
  dir (default: /tmp) file directory for vdev files
`-g` threshold
  gang block threshold (default: 32K)
`-h`
  print help
`-i` count
  init count (default: 1) initialize pool count times
`-k` percent
  kill percentage (default: 70%)
`-m` copies
  mirror copies (default: 2)
`-P` passtime
  passtime (default: 60 sec) time per pass
`-p` name
  pool name (default: ztest)
`-R` parity
  raidz parity (default: 1)
`-r` disks
  raidz disks (default: 4)
`-s` size
  size of each vdev (default: 256M)
`-T` time
  time (default: 300 sec) total run time
`-t` threads
  threads (default: 23)
`-V`
  verbose (use multiple times to increase verbosity)
`-v` vdevs
  number of vdevs (default: 5)

# AUTHORS

This man page was written by Sevan Janiyan <sevan@NetBSD.org>.

# CAVEATS

To allow for backward compatibility testing using older versions of `ztest` the information stored in the mmap(2) temporary file passed from parent process to child must remain compatible with older versions of `ztest`.

December 10, 2018 | NetBSD 11.0