xref: /test/ontest-stc2/src/suites/nfs/fnfs/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.7	08/05/29 SMI"
#

DESCRIPTION:
===========
  This test suite tests the new automounter in both kernel and the daemon.

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-fnfs and installs into "/opt" by default.
      Installation is via the standard Solaris package installation
      tool pkgadd(1M). To install SUNWstc-fnfs simply enter the
      following command line:

        # pkgadd -d <package location>  SUNWstc-fnfs

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

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

        # pkgrm SUNWstc-fnfs

    o It is also acceptable to use an nfs accessible version of the
      SUNWstc-fnfs 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-fnfs

  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, maybe 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-fnfs".

  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/nfs/fnfs
    % stf_build package
    % cd ${CODEMGR_WS}/packages/`uname -p`
    % sudo pkgadd -d `pwd` SUNWstc-fnfs

PREREQUISITES:
=============
  This is a client test suite, but we will need a NFS server system and
  a filesystem from server to help testing the NFS mounting. Therefore,
  two systems are needed.

  Please prepare the followings before running the tests, otherwise
  tests may fail unexpectedly:

  1. Make sure STF Tools be in your PATH.

  2. Define following environment variables:
       % setenv SERVER your_remote_hostname_which_runs_nfsd->REQUIRED

     The following variables are optional, if not set, the default
	  value (see config.vars) will be used:
       % setenv MNTPTR Path_for_$SERVER_to_export->OPTIONAL
       % setenv TMPDIR tmpdir_for_temp_files->OPTIONAL

  3. SERVER must be different from the local_host.

  4. You can define DNS_SERVER as your dns server, make sure the dns server
     is available before testing, the default value is jurassic.sfbay.sun.com

  5. Both systems under test (the SERVER and local_host) must be able to
     do rcp/rsh to each other as root (i.e. add + to ~root/.rhosts).

  6. The test suite requires "root" to run (for server setup and client
     map installation).  You can either run it as root, or enter the root
     password when it is prompted on command line when you do 'stf_configure'
     as a regular user.

  7. Trusted Extensions over a CIPSO connection

     If you want to test NFSv4 in Trusted Extensions over a CIPSO connection
     you MUST define the variable "ZONE_PATH" with <non-global zone path>

         example:
             stf_configure -c "SERVER=myserver" -c "ZONE_PATH=/zone/public"

         This would produce the resultant MNTPTR default of:
             /zone/public/stc2_FNFS_$CLIENT

     The default for this ZONE_PATH is NULL.

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=myserver
           # stf_configure

        2) use '-c' option
           # stf_configure -c "SERVER=myserver" \
                -c "DEBUG=ck_master:ck_mthome"

        3) use '-f' option
           # echo "export SERVER=myserver" > /tmp/varfile
           # stf_configure -f /tmp/varfile

EXECUTION:
=========
  At execution phase, you can only run 'stf_execute', or run stf_execute with
  '-c' option specifying other optional variables which will override those
  specified at configure phase.

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

UNCONFIGURATION:
===============
  You can run from the top level directory.
  # stf_unconfigure

HOW TO TURN ON DEBUGGING:
========================
  1. To turn on one testcase's debug output, set the variable DEBUG with
     the testcase's name before running the test. For example:
       DEBUG=ck_cachefs01
  2. To turn on more than one testcase's debug output, use ":" to sepatate
     different testcase's name. For example:
       DEBUG=ck_cachefs01:ck_cachefs02
  3. To turn on the debug output of all testcase, set the variable DEBUG with
     "all". For example:
       DEBUG=all

TEST DEVELOPMENT:
================
  If you develop new test case to this suite, you must:
  - name the new test starting with 'ck_'

TEST STRUCTURE:
==============
  STF_TEST_SUITE--bin
                |-doc
                |-include
                |-tests-----basic
                          |-misc
                          |-mntnet
                          |-mt
                          |-offset
                          |-others
                          |-readdir

- Programs used by tests are put into STF_TEST_SUITE/bin
- ksh script libs are put into STF_TEST_SUITE/include
- test cases are grouped into directories below:
  - basic:   Test basic map formats
  - misc:    Test miscellaneous features that need to restart autofs service
  - mntnet:  Test features related to "-host" map
  - mt:      Test multi-thread features
  - offset:  Test maps using offset entries
  - others:  Test miscellaneous features that do NOT need to restart
             autofs service
  - readdir: Test readdir operation on miscellaneous maps

- all maps setup for each subdir (except misc) are found in stf_setup/cleanup
  inside the subdir.

NOTE:
====

  - Some tests depend heavily on the naming services (e.g. NIS+) and the
    automounter maps provided by the server.  Tests may fail with unstable
    naming services and if the maps are being changed at the time the tests
    are running or if there is any inconsistency between naming maps.

  - Tests may also fail if the network between the local system and SERVER
    is unstable.

    Please verify the failing tests by running them manually,
    e.g. "stf_execute -r ck_master".

  - Since the suite includes negative tests, there will be lots of messages
    printed from the console when those tests are executed.  If the tests
    pass, you can just ignore those messages.

GOTCHAS:
=======
  1. Tests ck_cachefs01 and ck_cachefs02 may fail with the following message:
	 ck_cachefs01: FAILED
		       2:stat(/ck_cachefs01_A/t1/.t1) failed : Permission denied

     and the console of the client shows:
	 Jul  9 19:23:55 pulsanet1 cachefs: WARNING: CacheFS: not enough space
	 to create sos3:_small_CFS_t1:_cfs_t1

     This is NOT a test bug, but a bug in ON/CacheFS.  See bugid 4090474 for
     more information and this bug has been closed as "WILL NOT FIX".


**************************************************************************


Last Modified: 08/05/29