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.Nm 56.Fl X 57.Op Fl VG 58.Op Fl s Ar size_of_each_vdev 59.Op Fl a Ar alignment_shift 60.Op Fl r Ar raidz_disks 61.Op Fl R Ar raid_parity 62.Op Fl d Ar datasets 63.Op Fl t Ar threads 64. 65.Sh DESCRIPTION 66.Nm 67was written by the ZFS Developers as a ZFS unit test. 68The tool was developed in tandem with the ZFS functionality and was 69executed nightly as one of the many regression test against the daily build. 70As features were added to ZFS, unit tests were also added to 71.Nm . 72In addition, a separate test development team wrote and 73executed more functional and stress tests. 74. 75.Pp 76By default 77.Nm 78runs for ten minutes and uses block files 79(stored in 80.Pa /tmp ) 81to create pools rather than using physical disks. 82Block files afford 83.Nm 84its flexibility to play around with 85zpool components without requiring large hardware configurations. 86However, storing the block files in 87.Pa /tmp 88may not work for you if you 89have a small tmp directory. 90. 91.Pp 92By default is non-verbose. 93This is why entering the command above will result in 94.Nm 95quietly executing for 5 minutes. 96The 97.Fl V 98option can be used to increase the verbosity of the tool. 99Adding multiple 100.Fl V 101options is allowed and the more you add the more chatty 102.Nm 103becomes. 104. 105.Pp 106After the 107.Nm 108run completes, you should notice many 109.Pa ztest.* 110files lying around. 111Once the run completes you can safely remove these files. 112Note that you shouldn't remove these files during a run. 113You can re-use these files in your next 114.Nm 115run by using the 116.Fl E 117option. 118. 119.Sh OPTIONS 120.Bl -tag -width "-v v" 121.It Fl h , \&? , -help 122Print a help summary. 123.It Fl v , -vdevs Ns = (default: Sy 5 ) 124Number of vdevs. 125.It Fl s , -vdev-size Ns = (default: Sy 64M ) 126Size of each vdev. 127.It Fl a , -alignment-shift Ns = (default: Sy 9 ) No (use Sy 0 No for random ) 128Alignment shift used in test. 129.It Fl m , -mirror-copies Ns = (default: Sy 2 ) 130Number of mirror copies. 131.It Fl r , -raid-disks Ns = (default: Sy 4 No for raidz/ Ns Sy 16 No for draid ) 132Number of raidz/draid disks. 133.It Fl R , -raid-parity Ns = (default: Sy 1 ) 134Raid parity (raidz & draid). 135.It Xo 136.Fl K , -raid-kind Ns = Ns 137.Sy raidz Ns | Ns Sy eraidz Ns | Ns Sy draid Ns | Ns Sy random 138(default: 139.Sy random Ns 140) 141.Xc 142The kind of RAID config to use. 143With 144.Sy random 145the kind alternates between raidz, eraidz (expandable raidz) and draid. 146.It Fl D , -draid-data Ns = (default: Sy 4 ) 147Number of data disks in a dRAID redundancy group. 148.It Fl S , -draid-spares Ns = (default: Sy 1 ) 149Number of dRAID distributed spare disks. 150.It Fl d , -datasets Ns = (default: Sy 7 ) 151Number of datasets. 152.It Fl t , -threads Ns = (default: Sy 23 ) 153Number of threads. 154.It Fl g , -gang-block-threshold Ns = (default: Sy 32K ) 155Gang block threshold. 156.It Fl i , -init-count Ns = (default: Sy 1 ) 157Number of pool initializations. 158.It Fl k , -kill-percentage Ns = (default: Sy 70% ) 159Kill percentage. 160.It Fl p , -pool-name Ns = (default: Sy ztest ) 161Pool name. 162.It Fl f , -vdev-file-directory Ns = (default: Pa /tmp ) 163File directory for vdev files. 164.It Fl M , -multi-host 165Multi-host; simulate pool imported on remote host. 166.It Fl E , -use-existing-pool 167Use existing pool (use existing pool instead of creating new one). 168.It Fl T , -run-time Ns = (default: Sy 300 Ns s) 169Total test run time. 170.It Fl P , -pass-time Ns = (default: Sy 60 Ns s) 171Time per pass. 172.It Fl F , -freeze-loops Ns = (default: Sy 50 ) 173Max loops in 174.Fn spa_freeze . 175.It Fl B , -alt-ztest Ns = 176Path to alternate ("older") 177.Nm ztest 178to drive, which will be used to initialise the pool, and, a stochastic half the 179time, to run the tests. 180The parallel 181.Pa lib 182directory is prepended to 183.Ev LD_LIBRARY_PATH ; 184i.e. given 185.Fl B Pa ./chroots/lenny/usr/bin/ Ns Nm , 186.Pa ./chroots/lenny/usr/lib 187will be loaded. 188.It Fl C , -vdev-class-state Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy random No (default : Sy random ) 189The vdev allocation class state. 190.It Fl o , -option Ns = Ns Ar variable Ns = Ns Ar value 191Set global 192.Ar variable 193to an unsigned 32-bit integer 194.Ar value 195(little-endian only). 196.It Fl G , -dump-debug 197Dump zfs_dbgmsg buffer before exiting due to an error. 198.It Fl V , -verbose 199Verbose (use multiple times for ever more verbosity). 200.It Fl X , -raidz-expansion 201Perform a dedicated raidz expansion test. 202.El 203. 204.Sh EXAMPLES 205To override 206.Pa /tmp 207as your location for block files, you can use the 208.Fl f 209option: 210.Dl # ztest -f / 211.Pp 212To get an idea of what 213.Nm 214is actually testing try this: 215.Dl # ztest -f / -VVV 216.Pp 217Maybe you'd like to run 218.Nm ztest 219for longer? To do so simply use the 220.Fl T 221option and specify the runlength in seconds like so: 222.Dl # ztest -f / -V -T 120 223. 224.Sh ENVIRONMENT VARIABLES 225.Bl -tag -width "ZF" 226.It Ev ZFS_HOSTID Ns = Ns Em id 227Use 228.Em id 229instead of the SPL hostid to identify this host. 230Intended for use with 231.Nm , but this environment variable will affect any utility which uses 232libzpool, including 233.Xr zpool 8 . 234Since the kernel is unaware of this setting, 235results with utilities other than ztest are undefined. 236.It Ev ZFS_STACK_SIZE Ns = Ns Em stacksize 237Limit the default stack size to 238.Em stacksize 239bytes for the purpose of 240detecting and debugging kernel stack overflows. 241This value defaults to 242.Em 32K 243which is double the default 244.Em 16K 245Linux kernel stack size. 246.Pp 247In practice, setting the stack size slightly higher is needed because 248differences in stack usage between kernel and user space can lead to spurious 249stack overflows (especially when debugging is enabled). 250The specified value 251will be rounded up to a floor of PTHREAD_STACK_MIN which is the minimum stack 252required for a NULL procedure in user space. 253.Pp 254By default the stack size is limited to 255.Em 256K . 256.El 257. 258.Sh SEE ALSO 259.Xr zdb 1 , 260.Xr zfs 1 , 261.Xr zpool 1 , 262.Xr spl 4 263