Cross Reference: /test/ontest-stc2/src/suites/zfs/README

#
# 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 2008 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.5	08/02/27 SMI"
#

The ZFS Test Suite Gate README - Apr 2nd, 2007

Table of Contents

	1. Introduction

	2. Building & Installation

		2.1 Installing from Packages

		2.2 Uninstalling the Test Suite Package

		2.3 Building the Test Suite (optional)

	3. Running the tests

		3.1 Setting environment

		3.2 Configuring and running in global zone

		3.3 Configuring and running in local zone

		3.4 Unconfigure

================================================================================

1. Introduction

  o This message contains the basics you need to know for the ZFS test suite

================================================================================

2. Building & Installation

2.1 Installing from Packages

   o In the majority of cases, the test suite can be installed from packages. The
     package is called SUNWstc-zfs and installs into "/opt" by default. Installation is
     via the standard Solaris package installation tool pkgadd(1m). To install
     SUNWstc-zfs simply enter the following command line:

	% sudo pkgadd -d <package location>  SUNWstc-zfs

     Where <package location> refers to the path containing the SUNWstc-zfs
     package directory.

  o It is recommended that you install the packages from scratch,
    rather than on top of an existing installation.  Thus, if an old
    version of the tests is installed:

        % sudo pkgrm SUNWstc-zfs

2.2 Uninstalling the Test Suite Package

  o Prior to uninstalling the SUNWstc-zfs package, you may want to run stf_unconfigure
    from the top level directory. Typically this will be "/opt/SUNWstc-zfs". Unconfiguring
    the suite is recommended if you have previous run the suite in local zone mode. For
    more detail on how to unconfigure the suite see section 3.4.

  o To uninstall the package use the standard Solaris package installation tool pkgrm(1m)
    as follows:

        % sudo pkgrm SUNWstc-zfs

2.3 Building the Test Suite (optional)

  o This method uses the standard STF techniques to create a
    Solaris package, which will be installed under the base
    directory "/opt/SUNWstc-zfs".

    Briefly, this build and installation is performed as follows:

	# set path to STF bin directory
	% PATH=<path-to-STF>/bin/`uname -p`:$PATH
	% export PATH

	# if not using teamware, define CODEMGR_WS
	% CODEMGR_WS=<path-to-workspace>
	% export CODEMGR_WS

	% cd ${CODEMGR_WS}/src/suites/zfs
	% stf_build package
	% cd ${CODEMGR_WS}/packages/`uname -p`
	% sudo pkgadd -d `pwd` SUNWstc-zfs

  o It is recommended that you install the packages from scratch,
    rather than on top of an existing installation.  Thus, if an old
    version of the tests is installed:

	% sudo pkgrm SUNWstc-zfs

================================================================================

3. Running the tests

3.1 Setting environment

  o Add <STF Tools Path>/proto/tools/stf/bin/`uname -p` to your PATH:

	csh% set path = ( /ws/onnv-stc2/proto/tools/stf/bin/`uname -p` $path )

	sh% PATH=/ws/onnv-stc2/proto/tools/stf/bin/`uname -p`:$PATH export PATH

  o If no legal ip address was assigned to local zone, you need pkgadd
    SUNWstc-stf in global zone

	% sudo pkgadd -d /ws/onnv-stc2/packages/`uname -p` SUNWstc-stf

  o When testing with NFS, you should set the remote access permission for
    rsh/rcp on the remote server machine. You can add the permission to
    ~root/.rhosts file in the server, for example:
        server% echo "foo root" >~root/.rhosts
    Here, the 'foo' is the local host name.

--------------------------------------------------------------------------------

3.2 Configuring and running in global zone

3.2.1 Configure the tests

  o You'll need at least two scratch disks. Configure the two scratch disks,
    c0t13d0 and c0t14d0 for example:

	% cd /opt/SUNWstc-zfs; stf_configure -c DISKS="c0t13d0 c0t14d0"

  o By default the test suite runs all test assertions. However, the test
    suite can be configured for test runs of varying length by using the
    RUNTIME parameter. Valid runtime lengths are: short, medium and
    long (the default). For example, the following command will configure
    the test suite for the shortest possible runtime:

	% cd /opt/SUNWstc-zfs; stf_configure -c DISKS="c0t13d0 c0t14d0" \
	    -c "RUNTIME=short"

    Note that hardware speed is also a significnat contributor to the
    runtime length of the test suite.

  o Configuring this test suite will destroy all existing pools.
    If you  want to preserve existing pools you should use the KEEP
    parameter. For example:

	% cd /opt/SUNWstc-zfs; stf_configure -c DISKS="c0t13d0 c0t14d0" \
	    -c "KEEP=poolA poolB"

  o If you want to run the test suite with remote support, you should  assign
    one or more machines as remote testing hosts. Meanwhile, you also need to
    specify disks for each remote host. Optionally, you can specify test
    scripts location directory on the remote host. The descriptions of variables
    are as follows:

    RHOSTS -- The remote hosts list.
    RDISKS -- The corresponding scratch disks list for each host in RHOSTS list.
	      You need to quote the disks of each host, for example:
		 RDISKS="'c0t0d0 c0t1d0' 'c0t2d0'"
	      which specifies scratch disks for two remote hosts.
	      You can assign 'detect' for a remote host, which  means let
	      the program to detect any available disks for testing in a
	      remote host.
    RTEST_ROOT -- The temporary directory to store test scripts and files on the
		  remote host. By default it's set to /var/tmp/SUNWstc-zfs/tmp.

    Here is an example about how to customize the testing:
        % cd /opt/SUNWstc-zfs
        % stf_configure -c DISKS="c0t13d0 c0t14d0" -c RHOSTS="foo1 foo2" \
                        -c RDISKS="'c0t1d0 c0t2d0' 'detect'"
    In this example, there are two remote hosts -- "foo1" and "foo2":
    "foo1" is assigned two disks -- c0t1d0 and c0t2d0 for testing;
    "foo2" is assigned 'detect', which will detect any available scratch
    disks in "foo2" for remote support testing.

  o If you want to run the test suite on iSCSI targets, you need to specify
    iscsi variable to do the configuration, in addition to specify RHOSTS
    and RDISKS.
    Currently, only one value "remote" is supported for iscsi variable.

    Here is an example
	% cd /opt/SUNWstc-zfs
	% stf_configure -c DISKS="c0t13d0 c0t14d0" -c RHOSTS="host1" \
			-c RDISKS="'detect'" -c iscsi="remote"
    In this example, all available scratch disks detected on host1 will
    be configured as iSCSI targets on zfs, the local host will serve
    as iSCSI initiator, the test suite will run on the iSCSI targets
    at local host.

  o In addition, all variables to stf_configure can be set through setting
    environment variables or defining in a file. For example:
        In Korn Shell, you can export all variables as environment variables:

        % export DISKS="c0t13d0 c0t14d0"
        % export KEEP="poolA poolB"
        % export RUNTIME="long"
        % export RHOSTS="foo1 foo2"
	% export RDISKS="'c0t1d0 c0t2d0' 'detect'"
	% export RTEST_ROOT="/export/tmp"
        % stf_configure
        ...
        or, you can define all variables in a file and then via "-f" option of
        stf_configure to export the vairables:
        % echo "export DISKS=\"c0t13d0 c0t14d0\"" >/tmp/vars.cfg
        % echo "export KEEP=\"poolA poolB\"" >>/tmp/vars.cfg
        % echo "export RUNTIME=\"LONG\"" >>/tmp/vars.cfg
        % echo "export RHOSTS=\"foo1 foo2\"" >>/tmp/vars.cfg
	% echo "export RDISKS=\"'c0t1d0 c0t2d0' 'detect'\"" >>/tmp/vars.cfg
	% echo "export RTEST_ROOT=\"/export/tmp\"" >>/tmp/vars.cfg
        % stf_configure -f /tmp/vars.cfg

  o For stf_configure options refer to the STF User's Guide.

3.2.2 Run the tests

  o To execute all of the modes on current system platform:

	% cd /opt/SUNWstc-zfs; stf_execute

  o To execute in a specific mode:

	% stf_execute -m <mode>

  o To execute only test cases in a specific directory:

	% cd /opt/SUNWstc-zfs/<test directory>; stf_execute

  o For other stf_execute options, refer to the STF User's Guide.

  o Note:

	NIS client service will be disabled during tests/func/acl subsets
    execution temporarily, and its state will be restored after that.

--------------------------------------------------------------------------------

3.3 Configuring and running in local zone

3.3.1 Configure the tests

  o Firstly, configure in the global zone to create a local zone and export the
    pool to the local zone.  You'll need at least two scratch disks.
    You can assign a zone name, zone root and IP address for the local zone.
    All parameters are optional. Syntax as,

	stf_configure -c DISKS="<DISKS>" -c zone=new [-c zone_name=<zone_name>] [-c zone_root=<zone_root>] [-c zone_ip=<zone_ip>]

    For example,

	% cd /opt/SUNWstc-zfs; stf_configure -c DISKS="c0t13d0 c0t14d0" -c zone=new

  o Note: '-c zone=new' forces the creation a fresh zone. While 'zone=existing'
    will try to use an existing zone if possible or create a new one if no
    existing zone is found.

  o Note:
	If zone_name is NOT given, the default name of zone is `hostname`001
	If zone_root is NOT given, the default residence of zone is /export/home

  o Then, login to local zone.

	% sudo zlogin zone001

  o In local zone su to non-root user 'zone' which has be created automatically
    during the stf_configure process which was executed from the global zone.

	# su - zone

  o Configure in local zone

	% cd /opt/SUNWstc-zfs; /opt/SUNWstc-stf/bin/`uname -p`/stf_configure

3.3.2 Running the tests

  o To execute all of the modes on current system platform

	% cd /opt/SUNWstc-zfs;
	% /opt/SUNWstc-stf/bin/`uname -p`/stf_execute

  o To execute in a specific mode:

	% /opt/SUNWstc-stf/bin/`uname -p`/stf_execute -m <mode>

  o To execute only test cases in a specific directory:

	% cd /opt/SUNWstc-zfs/<test directory>
	% /opt/SUNWstc-stf/bin/`uname -p`/stf_execute

--------------------------------------------------------------------------------

3.4 Unconfigure the suite.

  o Use the STF unconfigure tool.

        % cd /opt/SUNWstc-zfs; stf_unconfigure

================================================================================