From 68a310dc45337b47339f504815caf2452985d8bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=BD=D0=B0=D0=B1?= Date: Wed, 26 May 2021 14:10:56 +0200 Subject: [PATCH] ztest.1: modernise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I fixed a few typos, but avoided changing anything beyond that; the sould of the document should be preserved Reviewed-by: Brian Behlendorf Signed-off-by: Ahelenia Ziemiańska Closes #12125 --- man/man1/ztest.1 | 327 +++++++++++++++++++++++++---------------------- 1 file changed, 172 insertions(+), 155 deletions(-) diff --git a/man/man1/ztest.1 b/man/man1/ztest.1 index 0b4d234401..459486c286 100644 --- a/man/man1/ztest.1 +++ b/man/man1/ztest.1 @@ -1,4 +1,3 @@ -'\" t .\" .\" CDDL HEADER START .\" @@ -19,198 +18,216 @@ .\" .\" CDDL HEADER END .\" -.\" .\" Copyright (c) 2009 Oracle and/or its affiliates. All rights reserved. .\" Copyright (c) 2009 Michael Gebetsroither . All rights .\" reserved. .\" Copyright (c) 2017, Intel Corporation. .\" -.TH ZTEST 1 "Aug 24, 2020" OpenZFS - -.SH NAME -\fBztest\fR \- was written by the ZFS Developers as a ZFS unit test. -.SH SYNOPSIS -.LP -.BI "ztest " -.SH DESCRIPTION -.LP -This manual page documents briefly the \fBztest\fR command. -.LP -\fBztest\fR 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 -\fBztest\fR. In addition, a separate test development team wrote and +.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. -.LP -By default \fBztest\fR runs for ten minutes and uses block files -(stored in /tmp) to create pools rather than using physical disks. -Block files afford \fBztest\fR its flexibility to play around with +. +.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 /tmp may not work for you if you +However, storing the block files in +.Pa /tmp +may not work for you if you have a small tmp directory. -.LP -By default is non-verbose. This is why entering the command above will -result in \fBztest\fR quietly executing for 5 minutes. The -V option -can be used to increase the verbosity of the tool. Adding multiple -V -option is allowed and the more you add the more chatty \fBztest\fR +. +.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. -.LP -After the \fBztest\fR run completes, you should notice many 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 \fBztest\fR run by using the -E +. +.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 -.HP -.BR "\-h, -?, --help" -.IP +. +.Sh OPTIONS +.Bl -tag -width "-v v" +.It Fl h , \&? , -help Print a help summary. -.HP -.BR "\-v, --vdevs=" " (default: 5) -.IP +.It Fl v , -vdevs Ns = (default: Sy 5 ) Number of vdevs. -.HP -.BR "\-s, --vdev-size=" " (default: 64M)" -.IP +.It Fl s , -vdev-size Ns = (default: Sy 64M ) Size of each vdev. -.HP -.BR "\-a, --alignment-shift=" " (default: 9) (use 0 for random)" -.IP +.It Fl a , -alignment-shift Ns = (default: Sy 9 ) No (use Sy 0 No for random) Alignment shift used in test. -.HP -.BR "\-m, --mirror-copies=" " (default: 2)" -.IP +.It Fl m , -mirror-copies Ns = (default: Sy 2 ) Number of mirror copies. -.HP -.BR "\-r, --raid-disks=" " (default: 4 for raidz/ 16 for draid)" -.IP +.It Fl r , -raid-disks Ns = (default: Sy 4 No for raidz/ Ns Sy 16 No for draid) Number of raidz/draid disks. -.HP -.BR "\-R, --raid-parity=" " (default: 1)" -.IP +.It Fl R , -raid-parity Ns = (default: Sy 1 ) Raid parity (raidz & draid). -.HP -.BR "\-K, --raid-kind=" " (default: 'random') raidz|draid|random" -.IP -The kind of RAID config to use. With 'random' the kind alternates between raidz and draid. -.HP -.BR "\-D, --draid-data=" " (default: 4)" -.IP +.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. -.HP -.BR "\-S, --draid-spares=" " (default: 1)" -.IP +.It Fl S , -draid-spares Ns = (default: Sy 1 ) Number of dRAID distributed spare disks. -.HP -.BR "\-d, --datasets=" " (default: 7)" -.IP +.It Fl d , -datasets Ns = (default: Sy 7 ) Number of datasets. -.HP -.BR "\-t, --threads=" " (default: 23)" -.IP +.It Fl t , -threads Ns = (default: Sy 23 ) Number of threads. -.HP -.BR "\-g, --gang-block-threshold=" " (default: 32K)" -.IP +.It Fl g , -gang-block-threshold Ns = (default: Sy 32K ) Gang block threshold. -.HP -.BR "\-i, --init-count=" " (default: 1)" -.IP +.It Fl i , -init-count Ns = (default: Sy 1 ) Number of pool initializations. -.HP -.BR "\-k, --kill-percentage=" " (default: 70%)" -.IP +.It Fl k , -kill-percentage Ns = (default: Sy 70% ) Kill percentage. -.HP -.BR "\-p, --pool-name=" " (default: ztest)" -.IP +.It Fl p , -pool-name Ns = (default: Sy ztest ) Pool name. -.HP -.BR "\-f, --vdev-file-directory=" " (default: /tmp)" -.IP +.It Fl f , -vdev-file-directory Ns = (default: Pa /tmp ) File directory for vdev files. -.HP -.BR "\-M, --multi-host" -.IP +.It Fl M , -multi-host Multi-host; simulate pool imported on remote host. -.HP -.BR "\-E, --use-existing-pool" -.IP +.It Fl E , -use-existing-pool Use existing pool (use existing pool instead of creating new one). -.HP -.BR "\-T, --run-time=" " (default: 300 sec)" -.IP +.It Fl T , -run-time Ns = (default: Sy 300 Ns s) Total test run time. -.HP -.BR "\-P, --pass-time=" " (default: 60 sec)" -.IP +.It Fl P , -pass-time Ns = (default: Sy 60 Ns s) Time per pass. -.HP -.BR "\-F, --freeze-loops=" " (default: 50)" -.IP -Max loops in spa_freeze(). -.HP -.BR "\-B, --alt-ztest=" -.IP +.It Fl F , -freeze-loops Ns = (default: Sy 50 ) +Max loops in +.Fn spa_freeze . +.It Fl B , -alt-ztest Ns = Alternate ztest path. -.HP -.BR "\-C, --vdev-class-state=on|off|random" " (default: random)" -.IP +.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. -.HP -.BR "\-o, --option=" -.IP -Set global variable to an unsigned 32-bit integer value. -.HP -.BR "\-G, --dump-debug" -.IP +.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. -.HP -.BR "\-V, --verbose" -.IP +.It Fl V , -verbose Verbose (use multiple times for ever more verbosity). -.SH "EXAMPLES" -.LP -To override /tmp as your location for block files, you can use the -f +.El +. +.Sh EXAMPLES +To override +.Pa /tmp +as your location for block files, you can use the +.Fl f option: -.IP -ztest -f / -.LP -To get an idea of what ztest is actually testing try this: -.IP -ztest -f / -VVV -.LP -Maybe you'd like to run ztest for longer? To do so simply use the -T +.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: -.IP -ztest -f / -V -T 120 - -.SH "ENVIRONMENT VARIABLES" -.TP -.B "ZFS_HOSTID=id" -Use \fBid\fR instead of the SPL hostid to identify this host. Intended for use -with ztest, but this environment variable will affect any utility which uses -libzpool, including \fBzpool(8)\fR. Since the kernel is unaware of this setting +.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. -.TP -.B "ZFS_STACK_SIZE=stacksize" -Limit the default stack size to \fBstacksize\fR bytes for the purpose of -detecting and debugging kernel stack overflows. This value defaults to -\fB32K\fR which is double the default \fB16K\fR Linux kernel stack size. - +.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 +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. - -By default the stack size is limited to 256K. -.SH "SEE ALSO" -.BR "spl-module-parameters (5)" "," -.BR "zpool (1)" "," -.BR "zfs (1)" "," -.BR "zdb (1)" "," -.SH "AUTHOR" -This manual page was transferred to asciidoc by Michael Gebetsroither - from http://opensolaris.org/os/community/zfs/ztest/ +.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-module-parameters 5