Cross Reference: /test/stcnv/usr/src/suites/nfs/nfsgen/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 2009 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.1	09/04/27 SMI"
#

DESCRIPTION
===========

   This test suite contains common tests for different NFS versions
   (i.e., nfsv4, future 4.1, etc).


TEST STRUCTURE
==============

      ${STF_SUITE_ROOT}
	  |- config.vars
	  |- checkenv_def
          |- configure.ksh
	  |- unconfigure.ksh
	  |- krb5_config.ksh
          |- bin
          |- lib
	  |- include
          +- setup
          |     +- nfsv4
          |     |     |- checkenv_def
          |     |     |- configure.ksh
          |     |     |- unconfigure.ksh
          |    ...
          |
          +- tests
                +- delegation
                +- openlock
		+- acl
		+- file_ops
		+- recovery
		+- stress

   - programs used by tests are put into STF_TEST_SUITE/bin
   - c function libs are put into STF_TEST_SUITE/lib
   - ksh script libs are put into STF_TEST_SUITE/include
   - test cases are grouped into 6 directories so far, more will
     be added in the later phases as needed:
	- delegation: test nfs delegation feature.
	- openlock: test nfs open/lock state management.
	- acl: test nfs acl.
	- file_ops: test file/dir operations via nfs
	- recovery: test nfs recovery feature.
	- stress: stress on open/read/write/lock ops.

   To make it easy to write and deploy multiple setups, files for a
   specific setup are placed under a dedicated subdir.

   User needs to set SETUP env variable to specify which configuration
   files to use. If SETUP=none, there will be no setup, nor any
   configuration files. If SETUP=nfsv4, top-level configuration files
   will redirect call from STF to corresponding files in setup/nfsv4.

   Top-level configuration files also perform some common tasks required
   by all setups.


INSTALLATION
============

   You can install the suite package, or install the suite source and
   build by yourself.

   1. Installing from Packages

      o In the majority of cases, the test suite can be installed from
        packages. To do that, you need to be as root. The package is
        called SUNWstc-nfs-nfsgen and installs into "/opt" by default.

        Installation is via the standard Solaris package installation
        tool pkgadd(1M). To install SUNWstc-nfs-nfsgen simply enter the
        following command line:

           # pkgadd -d <package location>  SUNWstc-nfs-nfsgen

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

        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:

           # pkgrm SUNWstc-nfs-nfsgen

      o It is also acceptable to use an nfs accessible version of the
        SUNWstc-nfs-nfsgen package.

   2. Installing the Test Suite Source

      You can install the suite source locally as any user.


UNINSTALLATION
==============

   Prior to uninstalling the test suite, you may want to run
   stf_unconfigure firstly. For more detail see UNCONFIGURATION.

   1. Uninstalling the Test Suite Package

      Use the standard Solaris package installation tool pkgrm(1M) to
      uninstall the package as root:

         # pkgrm SUNWstc-nfs-nfsgen

   2. Uninstalling the Test Suite Source

      You can remove the corresponding directory.


BUILDING
========

   If the suite is installed from packages, you can skip this section.
   If the suite source is installed locally, first you need to build
   it. This method uses the standard STF techniques to create a Solaris
   package, which will be installed under the base directory
   "/opt/SUNWstc-nfs-nfsgen".

   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

      $ cd <WS_ROOT>/usr/src/suites/nfs/nfsgen
      $ stf_build package
      $ cd <WS_ROOT>/packages/`uname -p`
      $ sudo pkgadd -d <WS_ROOT>/packages/`uname -p`/SUNWstc-nfs-nfsgen

    where WS_ROOT represents the root of the workspace under
    which the nfsgen test suite source resides.


PREREQUISITES
=============

   Below are the requirements common to all setups:

   1. You must have at least two machines. One is test client where
      you run those tests, another one is NFS server which is accessed
      remotely. Some tests(recovery, delegation) need three machines,
      you should set variable 'CLIENT2" as the second client's name.

   2. All systems under testing (including the local system) must
      enable r* service (i.e., run the command "netservices open")
      and be able to do rcp/rsh to each other as root; (i.e., add
      "local_host_name root" to ~/.rhosts on server, and comment out
      CONSOLE entry in /etc/default/login).

   3. The suite requires the "root" password to do setup. You can
      either run the suite as root, or enter the root password when
      it asks on command line when you do 'stf_configure' as a regular
      user.

   4. Make sure STF tools be in your PATH.

   5. You must set SETUP env variable to specify the setup on which
      you want to run your tests. Currently it can have two values:

         nfsv4  -   run tests on NFSV4.0 protocol
         none   -   run tests on the environment user set up manually.

      "none" setup is a special setup. In this setup, the test suite
      won't do any setup. That means user should set up a workable
      environment manually before he runs tests, and set up env
      variables needed by tests correctly. If you want to use this
      mode, see more details in "MANUAL SETUP" section below.

   6. Except SETUP=none, SERVER env variable must be set to specify
      server machine.

   7. If you run tests on TX, you must specify ZONE_PATH env variable
      to specify the pathname to labeled zone root file system.

   8. If user set SHROPT to "sec=krb5" (or "sec=krb5i", "sec=krb5p")
      Then test will setup kerberos environment in all machine.
      In that case, STC krb5tools are required. This test suite
      can use either a local installation of the SUNWstc-krb5tools
      package, or a remote, NFS-mounted location of the tools.
      KRB5TOOLS_HOME points to its root directory. Its default value is
      /opt/SUNWstc-krb5tools. To use krb5tools from elsewhere,
      simply set KRB5TOOLS_HOME in your environment, or use the '-c' option,
      for example:

	$ stf_configure -c \
		"KRB5TOOLS_HOME=/ws/stcnv-gate/proto/tools/krb5tools"

      Krb5 tests also uses four other env variables: DNS_DOMAIN,
      SRV_DNS_DOMAIN, CLT2_DNS_DOMAIN, DNS_SERVER:

	DNS_DOMAIN     - client dns domain. Default value is
			 sfbay.sun.com.
	SRV_DNS_DOMAIN  CLT2_DNS_DOMAIN
		       - server dns domain and client2 dns domain.
		         If users don't specify them, the values are
			 got from the following resources:
			   - /etc/resolv.conf
			   - default as DNS_DOMAIN
			 So user needs to set them if the machine has
			 a different DNS domain than client.
	DNS_SERVER     - a dns server that can resolve client
			 and server's dns names.

      Notes:
      - Currently openlock tests don't support krb5 config.
      - DNS_DOMAIN, SRV_DNS_DOMAIN, CLT2_DNS_DOMAIN is used to construct
      full qualified domain name for client and server, so they
      cannot be, for example, "sun.com", instead they should
      be "sfbay.sun.com", "ireland.sun.com", etc. BTW, although
      test scripts can get client and server's full qualified
      domain name automatically from dns sever, that requires
      reverse dns lookup has been set up for machines being
      queried, which is not always true for lab machines.

   9. If not all systems participating in test execution are of a single
      architecture (a "cross-architecture" testing scenario), the user shall
      be prepared to pkgadd, install, mount or in some other manner make
      available the appropriate test binaries on all systems participating
      in the test. or install test suite for all architectures into the client.
      And make sure the root directory of test suite on all systems is
      the SAME path. For example, CLIENT2 - sparc; client - i386, if we have
      a binary in client located under /opt/SUNWstc-suite/bin/386/foo,
      then we can also find a sparc binary in server or client under
      /opt/SUNWstc-suite/bin/sparc/foo.


   Below are requirements specific to nfsv4 setup:

   1. By default, the test will detect automatically the filesystem type of
      $SHRDIR on SERVER. If filesystem type is ZFS, tests will run over ZFS;
      if filesystem type is UFS, tests will run over UFS.

      If SERVER is zfs boot, and you want to run the tests over UFS, you
      must provide a dir based on UFS and define it to SHRDIR variable;
      Similarly, if SERVER is ufs boot, and you also want to run the tests
      over ZFS, you must provide a dir based on ZFS and define it to
      SHRDIR variable.


OPTIONAL SETTINGS
=================

   The following env variables(especially SHROPT and MNTOPT) may be
   useful when running tests:

      SHRDIR  -  shared directory on server (default is "/nfsgen_share")
      SHROPT  -  share options (default is anon=0 since ACL tests need it)
      MNTDIR  -  mount directory on client (default is "/nfsgen_mount"),
		 All tests are run in this directory
      MNTOPT  -  mount options (default is "rw")
      STRESS_TIMEOUT - By default, the stress test will return TIMEOUT if
		execution time of single test exceeds 3 hours(10800s). If you
		change the value of the variables in stress/stress.vars,
		you may need to reset STRESS_TIMEOUT to your expected time.
      NFSGEN_DEBUG  - debug variable, which can be set with
                 1) "all" for whole suite,
                 2) the name of test scripts you want to debug(e.g. srv_setup),
                 3) name of function in test scripts(e.g. wait_now),
		 4) "RUN_CHECK_CMD" or "RUN_CHECK_ALL" for commands
		    called by RUN_CHECK() function,
                 5) "RSH" to get output from the "RSH()" function
		 6) combination of 2-5, separated by ":".

   The test suite provides many other env variables for customizing
   test environment, but they should work out of box and are not
   suggested to change. If you have any questions on them, feel
   free to send email to maintainer of this suite, which you can
   find in STC.INFO file under the test suite's root directory.


CONFIGURATION
=============

   You can choose one of the following ways to define the variables
   and configure your suite from the top level directory.

      1) define environment variables

         $ export SERVER=foo
         $ stf_configure

      2) use '-c" option
         $ stf_configure -c "SERVER=foo" -c ...

      3) use '-f' option
         $ stf_configure -f ./myconf


EXECUTION
=========

   At execution phase, you can only use 'stf_execute' to run whole suite or
   specified tests via '-r' option.

   Although stf_execute supports "-c" option to specify variables which
   overrides those specified at configuration phase, you MUST NOT do that
   for nfs suites, i.e., stf_execute -c "CLIENT2=client2" -c "SHRDIR=testdir",
   since the suite has done corresponding configuration against those variables,
   re-defining them at execution phase may cause confusing. But you can
   print debugging info into journal file via 'stf_execute -c "NFSGEN_DEBUG=:xx:"',
   which is an exception.

   All results will be saved in the journal file under
   /var/tmp/nfsgen/results or the directory defined by 'STF_RESULTS'.

   Notes:
   - Some tests call ipfilter to block packets, but ipfilter doesn't work
     with RDMA configuration, so if you run the suite w/RDMA, those tests
     (clntrecov_rw_pos01,clntrecov_rw_pos02) may return TIMEOUT.


UNCONFIGURATION
===============

   You can run the following command from the top level directory

      $ stf_unconfigure


TEST DEVELOPMENT
================

   *NOTE*: This section is intended only for people who work on
   this test suite. If you don't want to change the test suite, add
   new setup or tests, you can skip this section.

   nfsgen test suite is unique in that it supports multiple setups,
   new setups, as well as new tests, can be added over time. For this
   purpose, it is important to define the interface between setup
   code and tests.

   Tests can make the following assumptions on the test execution
   environment:

      1) a test directory with read/write/search access($MNTDIR)
      2) both client and server have same nfs mapid domain($NFSMAPID_DOMAIN)
      3) both client and server have a same local group($TGROUP),
      4) both client and server have two same local users($TUSER01 and $TUSER02),
         they MUST be in $TGROUP and can be any valid user known by both client
	 and server. If SETUP!=none, the suite configuration will
	 create in locally in both client and server.

   All setup "plugins" should provide this, and tests are not
   expected to change them during execution.


MANUAL SETUP
============

   As we mentioned before, when user sets SETUP variable, he can
   set it to "none". This means user will set up the whole test
   environment manually and let the test suite skip configuration
   phase(however, user still needs to run stf_configure, which is
   a step required by STF. It is just that stf_configure will
   effectively do nothing in term of test environment setup.) This
   feature is believed to be useful in some cases.

   It should be noted that in this case, user is required to not
   only set up a workable test environment, but also to set those
   env variables correctly which compose of the interface between
   setup code and tests(see "TEST ENVIRONMENT INTERFACE" section).

   These variables are:

      MNTDIR           -  test directory
      NFSMAPID_DOMAIN  -  nfs mapid domain
      TGROUP           -  a regular group on both client and server
      TUSER01          -  a regular user in TGROUP on both client and server
      TUSER02          -  a regular user in TGROUP on both client and server
      TestZFS          -  If exported filesystem on the server is ZFS,
                          the variable should be set to 1.
      CLIENT2 	       -  Optional, if you set it, you should make sure
			  the machine can be access via rsh/rcp as root.


   In this case, if you want to run acl tests, you still refer to
   the README file under tests/acl to do more manual setup.

   When SETUP variable is not set to none, the tests under open and
   lock directories run separately with delegation on and off. But
   if the variable is set to none, these tests only run with current
   delegation configuration on the server.