| .\" |
| .\" 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 http://www.opensolaris.org/os/licensing. |
| .\" 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 = |
| Alternate ztest path. |
| .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 |