sys/contrib/openzfs/man/man1/ztest.1

   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 (c) 2009 Oracle and/or its affiliates. All rights reserved.
  24 .\" Copyright (c) 2009 Michael Gebetsroither <michael.geb@gmx.at>. All rights
  25 .\" reserved.
  26 .\"
  27 .TH ZTEST 1 "Aug 24, 2020" OpenZFS
  28
  29 .SH NAME
  30 \fBztest\fR \- was written by the ZFS Developers as a ZFS unit test.
  31 .SH SYNOPSIS
  32 .LP
  33 .BI "ztest <options>"
  34 .SH DESCRIPTION
  35 .LP
  36 This manual page documents briefly the \fBztest\fR command.
  37 .LP
  38 \fBztest\fR was written by the ZFS Developers as a ZFS unit test. The
  39 tool was developed in tandem with the ZFS functionality and was
  40 executed nightly as one of the many regression test against the daily
  41 build. As features were added to ZFS, unit tests were also added to
  42 \fBztest\fR.  In addition, a separate test development team wrote and
  43 executed more functional and stress tests.
  44 .LP
  45 By default \fBztest\fR runs for ten minutes and uses block files
  46 (stored in /tmp) to create pools rather than using physical disks.
  47 Block files afford \fBztest\fR its flexibility to play around with
  48 zpool components without requiring large hardware configurations.
  49 However, storing the block files in /tmp may not work for you if you
  50 have a small tmp directory.
  51 .LP
  52 By default is non-verbose. This is why entering the command above will
  53 result in \fBztest\fR quietly executing for 5 minutes. The -V option
  54 can be used to increase the verbosity of the tool. Adding multiple -V
  55 option is allowed and the more you add the more chatty \fBztest\fR
  56 becomes.
  57 .LP
  58 After the \fBztest\fR run completes, you should notice many ztest.*
  59 files lying around. Once the run completes you can safely remove these
  60 files. Note that you shouldn't remove these files during a run. You
  61 can re-use these files in your next \fBztest\fR run by using the -E
  62 option.
  63 .SH OPTIONS
  64 .HP
  65 .BI "\-?" ""
  66 .IP
  67 Print a help summary.
  68 .HP
  69 .BI "\-v" " vdevs" " (default: 5)
  70 .IP
  71 Number of vdevs.
  72 .HP
  73 .BI "\-s" " size_of_each_vdev" " (default: 64M)"
  74 .IP
  75 Size of each vdev.
  76 .HP
  77 .BI "\-a" " alignment_shift" " (default: 9) (use 0 for random)"
  78 .IP
  79 Used alignment in test.
  80 .HP
  81 .BI "\-m" " mirror_copies" " (default: 2)"
  82 .IP
  83 Number of mirror copies.
  84 .HP
  85 .BI "\-r" " raidz_disks" " (default: 4)"
  86 .IP
  87 Number of raidz disks.
  88 .HP
  89 .BI "\-R" " raidz_parity" " (default: 1)"
  90 .IP
  91 Raidz parity.
  92 .HP
  93 .BI "\-d" " datasets" " (default: 7)"
  94 .IP
  95 Number of datasets.
  96 .HP
  97 .BI "\-t" " threads" " (default: 23)"
  98 .IP
  99 Number of threads.
 100 .HP
 101 .BI "\-g" " gang_block_threshold" " (default: 32K)"
 102 .IP
 103 Gang block threshold.
 104 .HP
 105 .BI "\-i" " initialize_pool_i_times" " (default: 1)"
 106 .IP
 107 Number of pool initialisations.
 108 .HP
 109 .BI "\-k" " kill_percentage" " (default: 70%)"
 110 .IP
 111 Kill percentage.
 112 .HP
 113 .BI "\-p" " pool_name" " (default: ztest)"
 114 .IP
 115 Pool name.
 116 .HP
 117 .BI "\-V(erbose)"
 118 .IP
 119 Verbose (use multiple times for ever more blather).
 120 .HP
 121 .BI "\-E(xisting)"
 122 .IP
 123 Use existing pool (use existing pool instead of creating new one).
 124 .HP
 125 .BI "\-T" " time" " (default: 300 sec)"
 126 .IP
 127 Total test run time.
 128 .HP
 129 .BI "\-z" " zil_failure_rate" " (default: fail every 2^5 allocs)
 130 .IP
 131 Injected failure rate.
 132 .HP
 133 .BI "\-G"
 134 .IP
 135 Dump zfs_dbgmsg buffer before exiting.
 136 .SH "EXAMPLES"
 137 .LP
 138 To override /tmp as your location for block files, you can use the -f
 139 option:
 140 .IP
 141 ztest -f /
 142 .LP
 143 To get an idea of what ztest is actually testing try this:
 144 .IP
 145 ztest -f / -VVV
 146 .LP
 147 Maybe you'd like to run ztest for longer? To do so simply use the -T
 148 option and specify the runlength in seconds like so:
 149 .IP
 150 ztest -f / -V -T 120
 151
 152 .SH "ENVIRONMENT VARIABLES"
 153 .TP
 154 .B "ZFS_HOSTID=id"
 155 Use \fBid\fR instead of the SPL hostid to identify this host.  Intended for use
 156 with ztest, but this environment variable will affect any utility which uses
 157 libzpool, including \fBzpool(8)\fR.  Since the kernel is unaware of this setting
 158 results with utilities other than ztest are undefined.
 159 .TP
 160 .B "ZFS_STACK_SIZE=stacksize"
 161 Limit the default stack size to \fBstacksize\fR bytes for the purpose of
 162 detecting and debugging kernel stack overflows.  This value defaults to
 163 \fB32K\fR which is double the default \fB16K\fR Linux kernel stack size.
 164
 165 In practice, setting the stack size slightly higher is needed because
 166 differences in stack usage between kernel and user space can lead to spurious
 167 stack overflows (especially when debugging is enabled).  The specified value
 168 will be rounded up to a floor of PTHREAD_STACK_MIN which is the minimum stack
 169 required for a NULL procedure in user space.
 170
 171 By default the stack size is limited to 256K.
 172 .SH "SEE ALSO"
 173 .BR "spl-module-parameters (5)" ","
 174 .BR "zpool (1)" ","
 175 .BR "zfs (1)" ","
 176 .BR "zdb (1)" ","
 177 .SH "AUTHOR"
 178 This manual page was transferred to asciidoc by Michael Gebetsroither
 179 <gebi@grml.org> from http://opensolaris.org/os/community/zfs/ztest/