[src/trunk]: src/external/cddl/osnet/usr.bin/ztest Add a draft manual for zte...

[sevan <sevan%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/716e60ba9a9f
branches:  trunk
changeset: 446494:716e60ba9a9f
user:      sevan <sevan%NetBSD.org@localhost>
date:      Sat Dec 08 01:28:27 2018 +0000

description:
Add a draft manual for ztest(1), based on the comments from zfstest.c (WIP).

diffstat:

 external/cddl/osnet/usr.bin/ztest/ztest.1 |  154 ++++++++++++++++++++++++++++++
 1 files changed, 154 insertions(+), 0 deletions(-)

diffs (158 lines):

diff -r d4cbdbafd1ef -r 716e60ba9a9f external/cddl/osnet/usr.bin/ztest/ztest.1
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/external/cddl/osnet/usr.bin/ztest/ztest.1 Sat Dec 08 01:28:27 2018 +0000
@@ -0,0 +1,154 @@
+.\"     $NetBSD: ztest.1,v 1.1 2018/12/08 01:28:27 sevan Exp $
+.\"
+.\" Copyright (c) 2018 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Sevan Janiyan <sevan%NetBSD.org@localhost>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"/
+.Dd December 8, 2018
+.Dt ZTEST 1
+.Os
+.Sh NAME
+.Nm ztest
+.Nd ZFS stress test utility
+.Sh SYNOPSIS
+.Nm
+.Op Fl vsamrRdtgikpfVETFPBh
+.Sh DESCRIPTION
+The
+.Nm
+utility stress tests the DMU, ZAP, SPA components of ZFS from user space.
+.Pp
+.Nm
+provides a simple routine to test the functionality of a component task.
+These simple routines can then be used to stress test through parallel
+execution.
+Tests are run as child processes of the main process.
+.Pp
+The checksum and compression functions are changed each time a dataset is
+opened to introduce varying combinations of checksum and compression from block
+to block among objects.
+.Pp
+While tests are running, faults are injected into the pool to verify
+self-healing ability.
+.Pp
+To verify that the on-disk consistency is never lost after a crash, child
+processes are killed at random with a SIGKILL signal, after which the parent
+process invokes a new child to run the test again on the same storage pool.
+.Pp
+The main
+.Nm
+process uses an
+.Xr mmap 2
+temporary file to pass information to child processes which allows shared
+memory to survive
+.Xr exec 3
+syscall.
+A copy of the ztest_shared_hdr_t struct containing information on the size and
+number of shared structures in the file is always stored at offset 0 of the
+file.
+.Pp
+For backwards compatibility testing
+.Nm
+can invoke an alternative version of
+.Nm
+after a SIGLKILL using the
+.Fl B
+flag.
+.sp
+The following options are available:
+.sp
+.Fl v
+vdevs (default: 5)
+.sp
+.Fl s
+size of each vdev (default: 256M)
+.sp
+.Fl a
+alignment shift (default: 9) use 0 for random
+.sp
+.Fl m
+mirror copies (default: 2)
+.sp
+.Fl r
+raidz disks (default: 4)
+.sp
+.Fl R
+raidz parity (default: 1)
+.sp
+.Fl d
+datasets (default: 7)
+.sp
+.Fl t
+threads (default: 23)
+.sp
+.Fl g
+gang block threshold (default: 32K)
+.sp
+.Fl i
+init count (default: 1) initialize pool i times
+.sp
+.Fl k
+kill percentage (default: 70%)
+.sp
+.Fl p
+pool name (default: ztest)
+.sp
+.Fl f
+dir (default: /tmp) file directory for vdev files
+.sp
+.Fl V
+verbose (use multiple times to increase verbosity)
+.sp
+.Fl E
+use existing pool instead of creating new one
+.sp
+.Fl T
+time (default: 300 sec) total run time
+.sp
+.Fl F
+freezeloops (default: 50) max loops in
+.Fn spa_freeze
+.sp
+.Fl P
+passtime (default: 60 sec) time per pass
+.sp
+.Fl B
+alt ztest (default: <none>) alternate ztest path
+.sp
+.Fl h
+(print help)
+.Sh AUTHORS
+This man page was written by
+.An Sevan Janiyan
+.Aq sevan%NetBSD.org@localhost .
+.Sh CAVEATS
+To allow for backward compatibilty testing using older versions of
+.Nm
+the information stored in the
+.Xr mmap 2
+temporary file passed from parent process to child must
+remain compatible with older versions of
+.Nm .