#
# 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.9	09/09/17 SMI"
#

******************************************************************************
*                                  COMSTAR                                   *
******************************************************************************
DESCRIPTION:
===========
The COMSTAR framework supports FC, FCoE, iSCSI, and iSER Target providers.

The test suite is mainly designed to test the functionality of framework, 
FC, FCOE, iSCSI and iSER target provider.  Although the operation of the
initiator is tested in the execution of the target tests.

The test hardware topology involves one Target host and one Initiator host, and 
possibly switchs depending upon the individual target provider type.  Due to the
hardware dependencies for each framework, it is unlikely that the entire suite
would be run on one configuration.  See each specific framework section for
individual requirements.

The tests should be run from the target host.

PREREQUISITES:
=============
1. The Initiator Host requires that the following package(s) are 
   installed on the test host:
        - SUNWstc-diskomizer 

   	Please download the latest package at 
	http://dlc.sun.com/osol/test/downloads/current/

	A good candidate package for the i386 plaform is 
	http://dlc.sun.com/osol/test/downloads/current/SUNWstc-diskomizer-YYYYMMDD.i386.tar.bz2
		
	After downloading the package, as root do the following:
		# gtar -jxvf SUNWstc-diskomizer-YYYYMMDD.i386.tar.bz2	
		# pkgadd -d packages/i386/ SUNWstc-diskomizer

	The SUNWstc-diskomizer pkg must be installed in the default directory:
	/opt/SUNWstc-diskomizer 

2. The target Host requires that the following package(s) are 
   installed on the test host:
	- SUNWstc-tetlite

	Please download the latest package at 
	http://dlc.sun.com/osol/test/downloads/current/

	A good candidate package for the i386 plaform is 
		http://dlc.sun.com/osol/test/downloads/current/SUNWstc-tetlite-YYYYMMDD.i386.tar.bz2
		
	After downloading the package, as root do the following:
		# gtar -jxvf SUNWstc-tetlite-YYYYMMDD.i386.tar.bz2	
		# pkgadd -d packages/i386/ SUNWstc-tetlite

	It is also acceptable to use an NFS-accessible location of the tetlite 
	package.

3. The test suite can be installed locally to the test host for target provider
   or accessed via nfs over the network from a server.  To install the
   test suite, as root do:

        pkgadd -d <package location> SUNWstc-storage-comstar

   Where <package location> is the path containing the SUNWstc-storage-comstar 
	package directory.

   It is also acceptable to use an NFS accessible location of the test suite 
	package.

   ALTERNATIVELY, the test suite source can be installed and built.  To
   build the test suite source, as any user, do:

        $ export CTI_ROOT=/opt/SUNWstc-tetlite/contrib/ctitools
        $ export PATH=$CTI_ROOT/bin:$PATH
        $ export CC=/usr/bin/gcc (e.g C complier location)
        $ cd /export/home/comstar (e.g suit source location)
        $ /usr/ccs/bin/make

   To install test suite binaries in the proto tree, do
        $ /usr/ccs/bin/make install

   To create installable test suite packages, do
        $ /usr/ccs/bin/make package

4. The Initiator and Target hosts must be configured to accept rcp and 
   rsh calls from test hosts.

5. It's assumed that the following CONFIGURATION, and EXECUTION steps in 
   Comstar are performed in a single shell environment. If they are performed 
   in different shell environment, please set up CTI_ROOT and PATH for each
   operation.

Please refer to the PREREQUISITES segment for each target type for the target
suite specific prerequisites.

CONFIGURATION:
=============
Please refer to the TEST SUITE CONFIGURATION segment for each target in each
individual target provider section.

EXECUTION:
=============
Please refer to the TEST SUITE EXECUTION segment for each target in each 
individual target provider section.

******************************************************************************
*                                  FC TARGET                                 *
******************************************************************************

PREREQUISITES:
============
1. The test configuration requires both a FC Initiator and FC Target host, 
   which are both connected to a  Qlogic Switch. The FC Initiator Host will 
   be rebooted automatically during Fault Injection testing.  The test 
   requires at least two FC ports on both the target and the initiator.

2. The FC Target Host must NOT have any existing LUs or related 
   configuration information such as target group, host group, view entry 
   or mapping association before test execution. 

3. It is required that all other target providers be disabled prior to
   test suite execution.  For instance, the SMF services for
   /network/iscsi/target, and /system/iscsitgt must be disabled.
   Otherwise, unexpected test failures will result.

4. Operations on the systems under test, beyond the execution of the test 
   suite are prohibited during test suite execution.  Any external LUN
   operations could impact the test suite results. 

5. For QLOGIC HBA, it's mandatory to switch into target mode manually 
   after an OS refresh installation. Please refer to the web page 
   on opensolaris.org for the procedure:
   http://wikis.sun.com/display/OpenSolarisInfo/How+to+Configure+Fibre+Channel+Ports
   
   Contact the HBA specific vendor or product team for target mode implications 
   as they become qualified and supported for Comstar.

TEST SUITE CONFIGURATION:
=========================
Test suite configuration must be done as root.

1. Set up the following environment variables
        # CTI_ROOT=/opt/SUNWstc-tetlite/contrib/ctitools
        # PATH=$CTI_ROOT/bin:$PATH

2. To configure the test suite :

# run_test \
  -v FC_IHOST=<FC Initiator IP Addr> \
  -v EXPECT=<EXPECT Script Parser Location> \
  -v "BDEVS=\"<device list separated by spaces>\"" \ 
        (Example: -v "BDEVS=\"/dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2\"")
  -v "RDEVS=\"<Raw device list separated by spaces>\"" \ 
        (Example: -v "RDEVS=\"/dev/rdsk/c0t1d0s2 /dev/rdsk/c0t2d0s2\"")
  -v FC_TARGET_SWITCH_PORT=<FC Switch Model:FC Switch IP:Admin:Passwd:Port1,Port2...> \
        (Example: -v FC_TARGET_SWITCH_PORT=QLOGIC:127.0.0.1:admin:password:1,2)
  comstar fc_configure

The configuration file will be created as a result of the arguments specified 
in the run_test command line.    Once the configuration operation has been
run successfully, you may check and/or correct the information in the 
<test suite location>config/test_config file.

Other configurable variables that can be set in the configuration line :

FC_IHOST        - [ fc initiator host ip address ] is required
                - currently only supports one fc initiator host 

EXPECT          - [ Expect script parser location ] is optional
                - defaults to /usr/bin/expect

BDEVS           - [ block device list ] is required
		- slice information is required
		- the default configuration creates 8 1Gb LUNs
		- this can only be changed in the configuration. Otherwise, this
		  is the minimum test suite requirment for the device size. 

RDEVS           - [ raw disk device list ] is required
		- slice information is required
		- the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size.

FC_TARGET_SWITCH_PORT
                - [ fc target host topology in fabric switch ] is required
                - QLOGIC and BROCADE fabric switches are supported
                - for fault injection testing of target side cable pull 

TEST SUITE EXECUTION :
====================
The test suite execution is required to be done as root.

To run the entire test suite do the following.

# run_test comstar fc

To execute individual scenarios (sbdadm, stmfadm, misc, fcinfo, libstmf)

# run_test comstar <scenario>

# run_test comstar sbdadm

To execute Test Purposes within a scenario :

# run_test comstar sbdadm/<test case dir>:<test purpose number>

# run_test comstar sbdadm/create:1
# run_test comstar stmfadm/create:1-2
# run_test comstar fc/fault/forcelip:1,2

Test case directories are sbdadm, stmfadm, misc, fault, and libstmf

TEST SUITE UNCONFIGURE :
======================

# run_test comstar fc_unconfigure

******************************************************************************
*                                ISCSI TARGET                                *
******************************************************************************

PREREQUISITES:
============
1. Test configuration requires both a ISCSI Initiator and ISCSI Target host.

   On both hosts, it is necessary to have an additional 2 NICs for test 
   transports.  Hosts will have an on-board interface to house the host 
   IP address being used for rsh communication between the target and 
   initiator host.  The other two NICs should be configured with IPs
   under different subnets for physical multi-path. 

   The ISCSI Initiator host will be rebooted automatically during 
   Fault Injection testing.

2. The iSCSI Target Host should NOT have any existing LUs or related
   configuration information such as target group, host group, view 
   entry or mapping association before test execution. 

3. It is required that all other target providers be disabled prior to
   test suite execution.  For instance, the SMF services for
   /system/iscsitgt must be disabled.  Otherwise, unexpected test
   failures will result.

4. Operations on the systems under test, beyond the execution of the test 
   suite are prohibited during test suite execution.  Any external LUN
   operations could impact the test suite results. 

TEST SUITE CONFIGURATION :
========================
Test suite configuration must be done as root.

1. Set up the following environment variables
        # CTI_ROOT=/opt/SUNWstc-tetlite/contrib/ctitools
        # PATH=$CTI_ROOT/bin:$PATH

2. To configure the test suite :

# run_test \
  -v TRANSPORT=SOCKETS
  -v EXPECT=<EXPECT Script Parser Location>
  -v ISCSI_THOST=<ISCSI Target IP Addr> \
  -v ISCSI_IHOST=<ISCSI Initiator IP Addr> \
  -v ISNS_HOST=<ISNS Target IP Addr> \
  -v "BDEVS=\"<device list separated by space>\"" \ 
        (Example: -v "BDEVS=\"/dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2\"")
  -v "RDEVS=\"<Raw device list separated by space>\"" \ 
        (Example: -v "RDEVS=\"/dev/rdsk/c0t1d0s2 /dev/rdsk/c0t2d0s2\"")
  comstar iscsi_configure

The configuration file will be created as a result of the arguments specified 
in the run_test command line.  Once the configuration operation has been
run successfully, you may check and/or correct the information in the 
<test suite location>config/test_config file.

Other configurable variables that can be set in the configuration line :

TRANSPORT       - [ SOCKETS or ALL transport can be specified ]
                - SOCKETS transport goes through only the ethernet interfaces
                - ALL transport goes through all the networking interfaces

EXPECT          - [ Expect script parser location ] is optional
                - default is /usr/bin/expect

ISCSI_THOST     - [ iscsi target host ip address ] is required
                - only supports one target initiator host nowadays

ISCSI_IHOST     - [ iscsi initiator host ip address ] is required
                - only supports one iscsi initiator host nowadays

ISNS_HOST       - [ isns server host ip address ] is required

BDEVS           - [ block disk device list ] is required
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size. 

RDEVS           - [ raw disk device list ] is required 
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size.

ISCSI_TARGET_SWITCH_PORT
                - [ ethernet interface topology on switch ] is currently 
                  unsupported
                - switch cable pull is unsupported currently

RADIUS_HOST     - [ radius server host ip address ] is optional
                - radius authentication feature is currently unsupported 
                - RADIUS_HOST defaults to ISCSI_IHOST implicitly for 
                  itadm utility testing

TEST SUITE EXECUTION :
==================== 
The test suite execution is required to be run as root.

After the configuration step, to run the entire test suite do the following.

# run_test comstar iscsi

To execute individual scenarios (itadm, iscsi_auth, iscsi_discovery, iscsi_io,
iscsi_fs, iscsi_smf, iscsi_visible)

# run_test comstar <scenario>

# run_test comstar itadm

To execute Test Purposes within a scenario :

# run_test comstar iscsi/<test case dir>:<test purpose number>

# run_test comstar iscsi/auth:1
# run_test comstar iscsi/auth:1-2
# run_test comstar iscsi/auth:1,2

Test case directories are iscsi,itadm

TEST SUITE UNCONFIGURE :
======================

# run_test comstar iscsi_unconfigure


******************************************************************************
*                                 ISER TARGET                                *
******************************************************************************

The ISER tests are currently the same set as the iscsi, and it's the 
installation of the IB equipment and configuration of the interfaces that 
load the IB modules and exercise that code.

PREREQUISITES:
============
1. Test configuration requires both ISER Initiator and ISER Target hosts.

   On both hosts, it is necessary to have an additional 2 IB HCAs for test 
   transports.  Hosts will have an on-board interface to house the host 
   IP address being used for rsh communication between the target and 
   initiator host.  The other two IB HCAs should be configured with IPs
   under different subnets for physical multi-path.  It is acceptable to 
   have one IB interface, and a additional sockets interface configured to
   satisfy the additional 2 transport requirement.  Or you can utilize 2 
   socket addresses to test iSER in sockets mode.

   The ISER Initiator host will be rebooted automatically during 
   Fault Injection testing.

2. ISER Target Host should NOT have any existing LUs and related
   configuration information such as target group, host group, view 
   entry and mapping association before test execution. 

3. It is required that all other target providers be disabled prior to
   test suite execution.  For instance, the SMF services for
   /system/iscsitgt must be disabled. Otherwise, unexpected test
   failures will result.

4. Operations on the systems under test, beyond the execution of the test 
   suite are prohibited during test suite execution.  Any external LUN
   operations could impact the test suite results. 

TEST SUITE CONFIGURATION :
========================
Test suite configuration must be done as root.
        
1. Set up the following environment variables
        # CTI_ROOT=/opt/SUNWstc-tetlite/contrib/ctitools
        # PATH=$CTI_ROOT/bin:$PATH

2. To configure the test suite :

# run_test \
  -v TRANSPORT=ISER
  -v EXPECT=<EXPECT Script Parser Location>
  -v ISCSI_THOST=<ISCSI Target IP Addr> \
  -v ISCSI_IHOST=<ISCSI Initiator IP Addr> \
  -v ISNS_HOST=<ISNS Target IP Addr> \
  -v "BDEVS=\"<Block device list separated by spaces>\"" \ 
        (Example: -v "BDEVS=\"/dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2\"")
  -v "RDEVS=\"<Raw device list separated by spaces>\"" \ 
        (Example: -v "RDEVS=\"/dev/rdsk/c0t1d0s2 /dev/rdsk/c0t2d0s2\"")
  -v ISER_TARGET_SWITCH_PORT=<IB Switch Model:IB Switch IP Addr:Admin:Passwd:Port1,Port2...> \
        (Example for TOPSPIN 120: 
                -v ISER_TARGET_SWITCH_PORT=TOPSPIN:127.0.0.1:admin:admin:1,2)
        (Example for TOPSPIN 360:
                -v ISER_TARGET_SWITCH_PORT=TOPSPIN:127.0.0.1:admin:admin:16/1,16/2)
  comstar iscsi_configure

The configuration file will be created as a result of the arguments specified 
in the run_test command line.   Once the configuration operation has been
run successfully, you may check and/or correct the information in the 
<test suite location>config/test_config file.

Other configurable variables that can be set in the configuration line:

TRANSPORT       - [ ISER, SOCKETS or ALL transport can be specified ]
                - SOCKETS transport goes through only the ethernet interfaces
                - ISER transport goes through only the infiniband interfaces
                - ALL transport goes through all the networking interfaces

EXPECT          - [ Expect script parser location ] is optional
                - default is /usr/bin/expect

ISCSI_THOST     - [ iscsi target host ip address ] is required
                - the suite currently only supports one initiator host

ISCSI_IHOST     - [ iscsi initiator host ip address ] is required
                - the suite currently only supports one initiator host

ISNS_HOST       - [ isns server host ip address ] is required

BDEVS           - [ block device list ] is required
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size. 

RDEVS           - [ raw device list ] is required
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size.


ISER_TARGET_SWITCH_PORT
                - [ infiniband interface topology on switch ] is optional
                - only supports TOPSPIN infiniband switch nowadays

RADIUS_HOST     - [ radius server host ip address ] is optional
                - radius authentication feature is currently unsupported 
                - RADIUS_HOST defaults to ISCSI_IHOST implicitly for 
                  itadm utility testing

TEST SUITE EXECUTION :
==================== 
The test suite execution is required to be run as root.

To run the entire test suite do the following.

# run_test comstar iscsi

To execute individual scenarios (itadm iscsi_auth iscsi_discovery iscsi_io
iscsi_fs iscsi_smf iscsi_visible)

# run_test comstar <scenario>

# run_test comstar itadm

To execute Test Purposes within a scenario :

# run_test comstar iscsi/<test case dir>:<test purpose number>

# run_test comstar iscsi/auth:1
# run_test comstar iscsi/auth:1-2
# run_test comstar iscsi/auth:1,2

Test case directories are iscsi,itadm

TEST SUITE UNCONFIGURE :
======================

# run_test comstar iscsi_unconfigure

******************************************************************************
*                                 FCOE TARGET                                *
******************************************************************************

PREREQUISITES:
============
1. The test configuration requires both a FC Initiator and FCoE Target hosts, 
   which are both connected to a CISCO NEXUS Switch.  The FC Initiator Host 
   will be rebooted automatically during Fault Injection testing.

2. The FCoE Target Host should NOT have any existing LUs and related 
   configuration information such as target group, host group, view entry 
   and mapping association before test execution. 

3. It is required that all other target providers be disabled prior to
   test suite execution.  For instance, the SMF services for
   /network/iscsi/target, and /system/iscsitgt must be disabled.
   Otherwise, unexpected test failures will result.

4. Operations on the systems under test, beyond the execution of the test 
   suite are prohibited during test suite execution.  Any external LUN
   operations could impact the test suite results. 

5. The FCoE target project is integrated into Solaris Nevada snv_112, 
   FCoE Target Host has to be upgraded to snv_112 or above.

TEST SUITE CONFIGURATION:
=========================
Test suite configuration must be done as root.

1. Set up the following environment variables
        # CTI_ROOT=/opt/SUNWstc-tetlite/contrib/ctitools
        # PATH=$CTI_ROOT/bin:$PATH

2. To configure the test suite :

# run_test \
  -v FC_IHOST=<FC Initiator IP Addr> \
  -v EXPECT=<EXPECT Script Parser Location> \
  -v "BDEVS=\"<Block device list separated by spaces>\"" \ 
        (Example: -v "BDEVS=\"/dev/dsk/c0t1d0s2 /dev/dsk/c0t2d0s2\"")
  -v "RDEVS=\"<Raw device list separated by spaces>\"" \ 
        (Example: -v "RDEVS=\"/dev/rdsk/c0t1d0s2 /dev/rdsk/c0t2d0s2\"")
  -v FC_TARGET_SWITCH_PORT=<FCoE Switch Model:FCoE Switch IP:Admin:Passwd:Port1,Port2...> \
        (Example: -v FC_TARGET_SWITCH_PORT=NEXUS:127.0.0.1:admin:password:1,2)
  comstar fcoe_configure

The configuration file will be created as a result of the arguments specified 
in the run_test command line.  There is no need to manually edit the 
configuration file as is required by some of the other test suites. 

Other configurable variables that can be set in the configuration line :

FC_IHOST        - [ fc initiator host ip address ] is required
		- currently only supports one fc initiator host

EXPECT          - [ Expect script parser location ] is optional
                - defaults to /usr/bin/expect

BDEVS           - [ block device list ] is required
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size. 

RDEVS           - [ raw device list ] is required
                - slice information is required
                - the default configuration creates 8 1Gb LUNs
                - this can only be changed in the configuration. Otherwise, this
                  is the minimum test suite requirment for the device size.

FC_TARGET_SWITCH_PORT
                - [ FCoE target host topology in fabric switch ] is required
                - CISCO NEXUS switches are supported
                - For fault injection testing of target side cable pull 

TEST SUITE EXECUTION :
====================
The test suite execution is required to be run as root.

To run the entire test suite do the following.

# run_test comstar fcoe

To execute individual scenarios (sbdadm stmfadm misc fcinfo libstmf)

# run_test comstar <scenario>

# run_test comstar fcoe/visible

To execute Test Purposes within a scenario :

# run_test comstar fcoe/<test case dir>:<test purpose number>

# run_test comstar fcoe/fcadm/create:1
# run_test comstar fcoe/fcadm/create:1-2
# run_test comstar fcoe/fault/forcelip:1,2

Test case directories are fcoe

TEST SUITE UNCONFIGURE :
======================

# run_test comstar fcoe_unconfigure

Indexes created Mon Nov 23 06:24:11 UTC 2009

Terms of Use | Privacy | Trademarks | Copyright Policy | Site Guidelines | Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
Copyright © 1995-2008 Sun Microsystems, Inc.