244 lines
6.9 KiB
Groff
244 lines
6.9 KiB
Groff
.\"
|
|
.\" CDDL HEADER START
|
|
.\"
|
|
.\" The contents of this file are subject to the terms of the
|
|
.\" Common Development and Distribution License (the "License").
|
|
.\" You may not use this file except in compliance with the License.
|
|
.\"
|
|
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
|
|
.\" or https://opensource.org/licenses/CDDL-1.0.
|
|
.\" See the License for the specific language governing permissions
|
|
.\" and limitations under the License.
|
|
.\"
|
|
.\" When distributing Covered Code, include this CDDL HEADER in each
|
|
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
|
|
.\" If applicable, add the following below this CDDL HEADER, with the
|
|
.\" fields enclosed by brackets "[]" replaced with your own identifying
|
|
.\" information: Portions Copyright [yyyy] [name of copyright owner]
|
|
.\"
|
|
.\" CDDL HEADER END
|
|
.\"
|
|
.\" Copyright (c) 2009 Oracle and/or its affiliates. All rights reserved.
|
|
.\" Copyright (c) 2009 Michael Gebetsroither <michael.geb@gmx.at>. All rights
|
|
.\" reserved.
|
|
.\" Copyright (c) 2017, Intel Corporation.
|
|
.\"
|
|
.Dd May 26, 2021
|
|
.Dt ZTEST 1
|
|
.Os
|
|
.
|
|
.Sh NAME
|
|
.Nm ztest
|
|
.Nd was written by the ZFS Developers as a ZFS unit test
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl VEG
|
|
.Op Fl v Ar vdevs
|
|
.Op Fl s Ar size_of_each_vdev
|
|
.Op Fl a Ar alignment_shift
|
|
.Op Fl m Ar mirror_copies
|
|
.Op Fl r Ar raidz_disks/draid_disks
|
|
.Op Fl R Ar raid_parity
|
|
.Op Fl K Ar raid_kind
|
|
.Op Fl D Ar draid_data
|
|
.Op Fl S Ar draid_spares
|
|
.Op Fl C Ar vdev_class_state
|
|
.Op Fl d Ar datasets
|
|
.Op Fl t Ar threads
|
|
.Op Fl g Ar gang_block_threshold
|
|
.Op Fl i Ar initialize_pool_i_times
|
|
.Op Fl k Ar kill_percentage
|
|
.Op Fl p Ar pool_name
|
|
.Op Fl T Ar time
|
|
.Op Fl z Ar zil_failure_rate
|
|
.
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
was written by the ZFS Developers as a ZFS unit test.
|
|
The tool was developed in tandem with the ZFS functionality and was
|
|
executed nightly as one of the many regression test against the daily build.
|
|
As features were added to ZFS, unit tests were also added to
|
|
.Nm .
|
|
In addition, a separate test development team wrote and
|
|
executed more functional and stress tests.
|
|
.
|
|
.Pp
|
|
By default
|
|
.Nm
|
|
runs for ten minutes and uses block files
|
|
(stored in
|
|
.Pa /tmp )
|
|
to create pools rather than using physical disks.
|
|
Block files afford
|
|
.Nm
|
|
its flexibility to play around with
|
|
zpool components without requiring large hardware configurations.
|
|
However, storing the block files in
|
|
.Pa /tmp
|
|
may not work for you if you
|
|
have a small tmp directory.
|
|
.
|
|
.Pp
|
|
By default is non-verbose.
|
|
This is why entering the command above will result in
|
|
.Nm
|
|
quietly executing for 5 minutes.
|
|
The
|
|
.Fl V
|
|
option can be used to increase the verbosity of the tool.
|
|
Adding multiple
|
|
.Fl V
|
|
options is allowed and the more you add the more chatty
|
|
.Nm
|
|
becomes.
|
|
.
|
|
.Pp
|
|
After the
|
|
.Nm
|
|
run completes, you should notice many
|
|
.Pa ztest.*
|
|
files lying around.
|
|
Once the run completes you can safely remove these files.
|
|
Note that you shouldn't remove these files during a run.
|
|
You can re-use these files in your next
|
|
.Nm
|
|
run by using the
|
|
.Fl E
|
|
option.
|
|
.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width "-v v"
|
|
.It Fl h , \&? , -help
|
|
Print a help summary.
|
|
.It Fl v , -vdevs Ns = (default: Sy 5 )
|
|
Number of vdevs.
|
|
.It Fl s , -vdev-size Ns = (default: Sy 64M )
|
|
Size of each vdev.
|
|
.It Fl a , -alignment-shift Ns = (default: Sy 9 ) No (use Sy 0 No for random)
|
|
Alignment shift used in test.
|
|
.It Fl m , -mirror-copies Ns = (default: Sy 2 )
|
|
Number of mirror copies.
|
|
.It Fl r , -raid-disks Ns = (default: Sy 4 No for raidz/ Ns Sy 16 No for draid)
|
|
Number of raidz/draid disks.
|
|
.It Fl R , -raid-parity Ns = (default: Sy 1 )
|
|
Raid parity (raidz & draid).
|
|
.It Fl K , -raid-kind Ns = Ns Sy raidz Ns | Ns Sy draid Ns | Ns Sy random No (default: Sy random )
|
|
The kind of RAID config to use.
|
|
With
|
|
.Sy random
|
|
the kind alternates between raidz and draid.
|
|
.It Fl D , -draid-data Ns = (default: Sy 4 )
|
|
Number of data disks in a dRAID redundancy group.
|
|
.It Fl S , -draid-spares Ns = (default: Sy 1 )
|
|
Number of dRAID distributed spare disks.
|
|
.It Fl d , -datasets Ns = (default: Sy 7 )
|
|
Number of datasets.
|
|
.It Fl t , -threads Ns = (default: Sy 23 )
|
|
Number of threads.
|
|
.It Fl g , -gang-block-threshold Ns = (default: Sy 32K )
|
|
Gang block threshold.
|
|
.It Fl i , -init-count Ns = (default: Sy 1 )
|
|
Number of pool initializations.
|
|
.It Fl k , -kill-percentage Ns = (default: Sy 70% )
|
|
Kill percentage.
|
|
.It Fl p , -pool-name Ns = (default: Sy ztest )
|
|
Pool name.
|
|
.It Fl f , -vdev-file-directory Ns = (default: Pa /tmp )
|
|
File directory for vdev files.
|
|
.It Fl M , -multi-host
|
|
Multi-host; simulate pool imported on remote host.
|
|
.It Fl E , -use-existing-pool
|
|
Use existing pool (use existing pool instead of creating new one).
|
|
.It Fl T , -run-time Ns = (default: Sy 300 Ns s)
|
|
Total test run time.
|
|
.It Fl P , -pass-time Ns = (default: Sy 60 Ns s)
|
|
Time per pass.
|
|
.It Fl F , -freeze-loops Ns = (default: Sy 50 )
|
|
Max loops in
|
|
.Fn spa_freeze .
|
|
.It Fl B , -alt-ztest Ns =
|
|
Path to alternate ("older")
|
|
.Nm ztest
|
|
to drive, which will be used to initialise the pool, and, a stochastic half the time, to run the tests.
|
|
The parallel
|
|
.Pa lib
|
|
directory is prepended to
|
|
.Ev LD_LIBRARY_PATH ;
|
|
i.e. given
|
|
.Fl B Pa ./chroots/lenny/usr/bin/ Ns Nm ,
|
|
.Pa ./chroots/lenny/usr/lib
|
|
will be loaded.
|
|
.It Fl C , -vdev-class-state Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy random No (default: Sy random )
|
|
The vdev allocation class state.
|
|
.It Fl o , -option Ns = Ns Ar variable Ns = Ns Ar value
|
|
Set global
|
|
.Ar variable
|
|
to an unsigned 32-bit integer
|
|
.Ar value
|
|
(little-endian only).
|
|
.It Fl G , -dump-debug
|
|
Dump zfs_dbgmsg buffer before exiting due to an error.
|
|
.It Fl V , -verbose
|
|
Verbose (use multiple times for ever more verbosity).
|
|
.El
|
|
.
|
|
.Sh EXAMPLES
|
|
To override
|
|
.Pa /tmp
|
|
as your location for block files, you can use the
|
|
.Fl f
|
|
option:
|
|
.Dl # ztest -f /
|
|
.Pp
|
|
To get an idea of what
|
|
.Nm
|
|
is actually testing try this:
|
|
.Dl # ztest -f / -VVV
|
|
.Pp
|
|
Maybe you'd like to run
|
|
.Nm ztest
|
|
for longer? To do so simply use the
|
|
.Fl T
|
|
option and specify the runlength in seconds like so:
|
|
.Dl # ztest -f / -V -T 120
|
|
.
|
|
.Sh ENVIRONMENT VARIABLES
|
|
.Bl -tag -width "ZF"
|
|
.It Ev ZFS_HOSTID Ns = Ns Em id
|
|
Use
|
|
.Em id
|
|
instead of the SPL hostid to identify this host.
|
|
Intended for use with
|
|
.Nm , but this environment variable will affect any utility which uses
|
|
libzpool, including
|
|
.Xr zpool 8 .
|
|
Since the kernel is unaware of this setting,
|
|
results with utilities other than ztest are undefined.
|
|
.It Ev ZFS_STACK_SIZE Ns = Ns Em stacksize
|
|
Limit the default stack size to
|
|
.Em stacksize
|
|
bytes for the purpose of
|
|
detecting and debugging kernel stack overflows.
|
|
This value defaults to
|
|
.Em 32K
|
|
which is double the default
|
|
.Em 16K
|
|
Linux kernel stack size.
|
|
.Pp
|
|
In practice, setting the stack size slightly higher is needed because
|
|
differences in stack usage between kernel and user space can lead to spurious
|
|
stack overflows (especially when debugging is enabled).
|
|
The specified value
|
|
will be rounded up to a floor of PTHREAD_STACK_MIN which is the minimum stack
|
|
required for a NULL procedure in user space.
|
|
.Pp
|
|
By default the stack size is limited to
|
|
.Em 256K .
|
|
.El
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr zdb 1 ,
|
|
.Xr zfs 1 ,
|
|
.Xr zpool 1 ,
|
|
.Xr spl 4
|