1.\" $NetBSD: ztest.1,v 1.4 2018/12/10 03:58:30 sevan Exp $ 2.\" 3.\" Copyright (c) 2018 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Sevan Janiyan <sevan@NetBSD.org> 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\"/ 30.Dd March 30, 2022 31.Dt ZTEST 8 32.Os 33.Sh NAME 34.Nm ztest 35.Nd ZFS stress test utility 36.Sh SYNOPSIS 37.Nm 38.Op Fl EhV 39.Op Fl a Ar shift 40.Op Fl B Ar path 41.Op Fl d Ar datasets 42.Op Fl F Ar loops 43.Op Fl f Ar path 44.Op Fl g Ar threshold 45.Op Fl i Ar count 46.Op Fl k Ar percent 47.Op Fl m Ar copies 48.Op Fl P Ar passtime 49.Op Fl p Ar name 50.Op Fl R Ar parity 51.Op Fl r Ar disks 52.Op Fl s Ar size 53.Op Fl T Ar time 54.Op Fl t Ar threads 55.Op Fl v Ar vdevs 56.Sh DESCRIPTION 57The 58.Nm 59utility stress tests the DMU, ZAP, SPA components of ZFS from user space. 60.Pp 61.Nm 62provides a simple routine to test the functionality of a component task. 63These simple routines can then be used to stress test through parallel 64execution. 65Tests are run as child processes of the main process. 66.Pp 67The checksum and compression functions are changed each time a dataset is 68opened to introduce varying combinations of checksum and compression from block 69to block among objects. 70.Pp 71While tests are running, faults are injected into the pool to verify 72self-healing ability. 73.Pp 74To verify that the on-disk consistency is never lost after a crash, child 75processes are killed at random with a SIGKILL signal, after which the parent 76process invokes a new child to run the test again on the same storage pool. 77.Pp 78Many of the tests record the transaction group number as part of their data. 79When reading old data, tests verify that the transaction group number is less 80than the current, open state, transaction group to ensure the consistency of 81tests and detect unaccounted changes. 82It is advised that any new tests added to 83.Nm 84should also perform the same check with transaction group numbers, if 85applicable. 86.Pp 87The main 88.Nm 89process uses an 90.Xr mmap 2 91temporary file to pass information to child processes which allows shared 92memory to survive 93.Xr exec 2 94syscall. 95A copy of the 96.Vt ztest_shared_hdr_t 97struct containing information on the size and number of shared 98structures in the file is always stored at offset 0 of the file. 99.Pp 100For backwards compatibility testing 101.Nm 102can invoke an alternative version of 103.Nm 104after a 105.Dv SIGKILL 106signal using the 107.Fl B 108flag. 109.Pp 110The following options are available: 111.Bl -tag -width 5n 112.It Fl a Ar shift 113alignment shift (default: 9) use 0 for random 114.It Fl B Ar path 115alt ztest (default: <none>) alternate ztest path 116.It Fl d Ar datasets 117datasets (default: 7) 118.It Fl E 119use existing pool instead of creating new one 120.It Fl F Ar loops 121freezeloops (default: 50) max loops in 122.Fn spa_freeze 123.It Fl f Ar path 124dir (default: 125.Pa /tmp ) 126file directory for vdev files 127.It Fl g Ar threshold 128gang block threshold (default: 32K) 129.It Fl h 130print help 131.It Fl i Ar count 132init count (default: 1) initialize pool 133.Ar count 134times 135.It Fl k Ar percent 136kill percentage (default: 70%) 137.It Fl m Ar copies 138mirror copies (default: 2) 139.It Fl P Ar passtime 140passtime (default: 60 sec) time per pass 141.It Fl p Ar name 142pool name (default: ztest) 143.It Fl R Ar parity 144raidz parity (default: 1) 145.It Fl r Ar disks 146raidz disks (default: 4) 147.It Fl s Ar size 148size of each vdev (default: 256M) 149.It Fl T Ar time 150time (default: 300 sec) total run time 151.It Fl t Ar threads 152threads (default: 23) 153.It Fl V 154verbose (use multiple times to increase verbosity) 155.It Fl v Ar vdevs 156number of vdevs (default: 5) 157.El 158.Sh AUTHORS 159This man page was written by 160.An Sevan Janiyan 161.Aq Mt sevan@NetBSD.org . 162.Sh CAVEATS 163To allow for backward compatibility testing using older versions of 164.Nm 165the information stored in the 166.Xr mmap 2 167temporary file passed from parent process to child must 168remain compatible with older versions of 169.Nm . 170