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