| blob | 64514b3172751e3fc7a0085b5a0e9d3a78945e6f |
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