man/man1/ztest.1

   1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or https://opensource.org/licenses/CDDL-1.0.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Copyright (c) 2009 Oracle and/or its affiliates. All rights reserved.
  22 .\" Copyright (c) 2009 Michael Gebetsroither <michael.geb@gmx.at>. All rights
  23 .\" reserved.
  24 .\" Copyright (c) 2017, Intel Corporation.
  25 .\"
  26 .Dd May 26, 2021
  27 .Dt ZTEST 1
  28 .Os
  29 .
  30 .Sh NAME
  31 .Nm ztest
  32 .Nd was written by the ZFS Developers as a ZFS unit test
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl VEG
  36 .Op Fl v Ar vdevs
  37 .Op Fl s Ar size_of_each_vdev
  38 .Op Fl a Ar alignment_shift
  39 .Op Fl m Ar mirror_copies
  40 .Op Fl r Ar raidz_disks/draid_disks
  41 .Op Fl R Ar raid_parity
  42 .Op Fl K Ar raid_kind
  43 .Op Fl D Ar draid_data
  44 .Op Fl S Ar draid_spares
  45 .Op Fl C Ar vdev_class_state
  46 .Op Fl d Ar datasets
  47 .Op Fl t Ar threads
  48 .Op Fl g Ar gang_block_threshold
  49 .Op Fl i Ar initialize_pool_i_times
  50 .Op Fl k Ar kill_percentage
  51 .Op Fl p Ar pool_name
  52 .Op Fl T Ar time
  53 .Op Fl z Ar zil_failure_rate
  54 .
  55 .Sh DESCRIPTION
  56 .Nm
  57 was written by the ZFS Developers as a ZFS unit test.
  58 The tool was developed in tandem with the ZFS functionality and was
  59 executed nightly as one of the many regression test against the daily build.
  60 As features were added to ZFS, unit tests were also added to
  61 .Nm .
  62 In addition, a separate test development team wrote and
  63 executed more functional and stress tests.
  64 .
  65 .Pp
  66 By default
  67 .Nm
  68 runs for ten minutes and uses block files
  69 (stored in
  70 .Pa /tmp )
  71 to create pools rather than using physical disks.
  72 Block files afford
  73 .Nm
  74 its flexibility to play around with
  75 zpool components without requiring large hardware configurations.
  76 However, storing the block files in
  77 .Pa /tmp
  78 may not work for you if you
  79 have a small tmp directory.
  80 .
  81 .Pp
  82 By default is non-verbose.
  83 This is why entering the command above will result in
  84 .Nm
  85 quietly executing for 5 minutes.
  86 The
  87 .Fl V
  88 option can be used to increase the verbosity of the tool.
  89 Adding multiple
  90 .Fl V
  91 options is allowed and the more you add the more chatty
  92 .Nm
  93 becomes.
  94 .
  95 .Pp
  96 After the
  97 .Nm
  98 run completes, you should notice many
  99 .Pa ztest.*
 100 files lying around.
 101 Once the run completes you can safely remove these files.
 102 Note that you shouldn't remove these files during a run.
 103 You can re-use these files in your next
 104 .Nm
 105 run by using the
 106 .Fl E
 107 option.
 108 .
 109 .Sh OPTIONS
 110 .Bl -tag -width "-v v"
 111 .It Fl h , \&? , -help
 112 Print a help summary.
 113 .It Fl v , -vdevs Ns = (default: Sy 5 )
 114 Number of vdevs.
 115 .It Fl s , -vdev-size Ns = (default: Sy 64M )
 116 Size of each vdev.
 117 .It Fl a , -alignment-shift Ns = (default: Sy 9 ) No (use Sy 0 No for random )
 118 Alignment shift used in test.
 119 .It Fl m , -mirror-copies Ns = (default: Sy 2 )
 120 Number of mirror copies.
 121 .It Fl r , -raid-disks Ns = (default: Sy 4 No for raidz/ Ns Sy 16 No for draid )
 122 Number of raidz/draid disks.
 123 .It Fl R , -raid-parity Ns = (default: Sy 1 )
 124 Raid parity (raidz & draid).
 125 .It Fl K , -raid-kind Ns = Ns Sy raidz Ns | Ns Sy draid Ns | Ns Sy random No (default : Sy random )
 126 The kind of RAID config to use.
 127 With
 128 .Sy random
 129 the kind alternates between raidz and draid.
 130 .It Fl D , -draid-data Ns = (default: Sy 4 )
 131 Number of data disks in a dRAID redundancy group.
 132 .It Fl S , -draid-spares Ns = (default: Sy 1 )
 133 Number of dRAID distributed spare disks.
 134 .It Fl d , -datasets Ns = (default: Sy 7 )
 135 Number of datasets.
 136 .It Fl t , -threads Ns = (default: Sy 23 )
 137 Number of threads.
 138 .It Fl g , -gang-block-threshold Ns = (default: Sy 32K )
 139 Gang block threshold.
 140 .It Fl i , -init-count Ns = (default: Sy 1 )
 141 Number of pool initializations.
 142 .It Fl k , -kill-percentage Ns = (default: Sy 70% )
 143 Kill percentage.
 144 .It Fl p , -pool-name Ns = (default: Sy ztest )
 145 Pool name.
 146 .It Fl f , -vdev-file-directory Ns = (default: Pa /tmp )
 147 File directory for vdev files.
 148 .It Fl M , -multi-host
 149 Multi-host; simulate pool imported on remote host.
 150 .It Fl E , -use-existing-pool
 151 Use existing pool (use existing pool instead of creating new one).
 152 .It Fl T , -run-time Ns = (default: Sy 300 Ns s)
 153 Total test run time.
 154 .It Fl P , -pass-time Ns = (default: Sy 60 Ns s)
 155 Time per pass.
 156 .It Fl F , -freeze-loops Ns = (default: Sy 50 )
 157 Max loops in
 158 .Fn spa_freeze .
 159 .It Fl B , -alt-ztest Ns =
 160 Path to alternate ("older")
 161 .Nm ztest
 162 to drive, which will be used to initialise the pool, and, a stochastic half the
 163 time, to run the tests.
 164 The parallel
 165 .Pa lib
 166 directory is prepended to
 167 .Ev LD_LIBRARY_PATH ;
 168 i.e. given
 169 .Fl B Pa ./chroots/lenny/usr/bin/ Ns Nm ,
 170 .Pa ./chroots/lenny/usr/lib
 171 will be loaded.
 172 .It Fl C , -vdev-class-state Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy random No (default : Sy random  )
 173 The vdev allocation class state.
 174 .It Fl o , -option Ns = Ns Ar variable Ns = Ns Ar value
 175 Set global
 176 .Ar variable
 177 to an unsigned 32-bit integer
 178 .Ar value
 179 (little-endian only).
 180 .It Fl G , -dump-debug
 181 Dump zfs_dbgmsg buffer before exiting due to an error.
 182 .It Fl V , -verbose
 183 Verbose (use multiple times for ever more verbosity).
 184 .El
 185 .
 186 .Sh EXAMPLES
 187 To override
 188 .Pa /tmp
 189 as your location for block files, you can use the
 190 .Fl f
 191 option:
 192 .Dl # ztest -f /
 193 .Pp
 194 To get an idea of what
 195 .Nm
 196 is actually testing try this:
 197 .Dl # ztest -f / -VVV
 198 .Pp
 199 Maybe you'd like to run
 200 .Nm ztest
 201 for longer? To do so simply use the
 202 .Fl T
 203 option and specify the runlength in seconds like so:
 204 .Dl # ztest -f / -V -T 120
 205 .
 206 .Sh ENVIRONMENT VARIABLES
 207 .Bl -tag -width "ZF"
 208 .It Ev ZFS_HOSTID Ns = Ns Em id
 209 Use
 210 .Em id
 211 instead of the SPL hostid to identify this host.
 212 Intended for use with
 213 .Nm , but this environment variable will affect any utility which uses
 214 libzpool, including
 215 .Xr zpool 8 .
 216 Since the kernel is unaware of this setting,
 217 results with utilities other than ztest are undefined.
 218 .It Ev ZFS_STACK_SIZE Ns = Ns Em stacksize
 219 Limit the default stack size to
 220 .Em stacksize
 221 bytes for the purpose of
 222 detecting and debugging kernel stack overflows.
 223 This value defaults to
 224 .Em 32K
 225 which is double the default
 226 .Em 16K
 227 Linux kernel stack size.
 228 .Pp
 229 In practice, setting the stack size slightly higher is needed because
 230 differences in stack usage between kernel and user space can lead to spurious
 231 stack overflows (especially when debugging is enabled).
 232 The specified value
 233 will be rounded up to a floor of PTHREAD_STACK_MIN which is the minimum stack
 234 required for a NULL procedure in user space.
 235 .Pp
 236 By default the stack size is limited to
 237 .Em 256K .
 238 .El
 239 .
 240 .Sh SEE ALSO
 241 .Xr zdb 1 ,
 242 .Xr zfs 1 ,
 243 .Xr zpool 1 ,
 244 .Xr spl 4