Cross Reference: /test/stcnv/usr/src/suites/storage/jist

#
# 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.59	08/12/04 SMI"
#

    ========================================================================
    === Java Technology based Interoperability Storage Testsuite (JIST)  ===
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Java Technology based Interoperability Storage Testsuite (JIST) is
    designed to validate ANSI T10 SCSI and Sun Microsystems, Inc ("Sun")
    SCSI Array Standards for conformity with Sun StorEdge[tm] Open SAN
    Architecture.

    The JIST Test Suite is divided between the following Test Levels, based
    on Sun SCSI Array Standards, mandatory and optional:

      * Sun Mandatory, Shall Pass Tests

      * Sun Optional, Should Pass Tests

    The JIST Test Suite organizes the Test Suites and Test Cases in
    hierarchical groupings. The Minimal Testing Requirements for
    Non-Clustered and Clustered Products are as follows:

      * Non-Clustered Configuration Components Must Complete ANSI T10 SCSI
        Single Initiator Test Suite with Level 1 Test Level, report NO
        Faults, and report NO Defects.  (See Sun Mandatory Single Initiator
        Test Execution)

      * Clustered Configurations Components Must Complete ANSI T10 SCSI
        Reservation Test Suite with Level 1 Test Level and report NO
        Faults, and report NO Defects.  (See Sun Mandatory Multiple
        Initiator Test Execution)

      * Fibre Channel Configured Components Must Complete ANSI T10 FCP and
        ANSI T11 Fibre Channel Single Initiator Test Suite with Level 1
        Test Level, report NO Faults, and report NO Defects.  (See Sun
        Mandatory Single Initiator Test Execution)

      * iSCSI Configured Components Must Complete IETF IPS iSCSI Single
        Initiator Test Suite with Level 1 Test Level, report NO Faults,
        and report NO Defects. (See Sun Mandatory Single Initiator Test
        Execution)

    The JIST Test Suite also has utility methods to conduct additional
    custom testing.  The primary utilities are as follows:

      * Accuracy Focused SCSI Write/Read/Compare Load Testing.  (See
        Write/Read/Compare Load Test Execution)

      * SCSI PERSISTENT RESERVATION Removal Testing. (See Persistent
        Reservation Removal Test Execution)

      * Fibre Channel Switch Port Fault Stress Testing.  (See Fibre
        Channel Switch Port Stress Test Execution)

      * SCSI & iSCSI Man-in-the-Middle Data and Network Fault Stress
        Testing.  (See JIST Agent Test Execution)

    Minimum Configuration Requirements are listed in "README.CONFIG".

    Please enter bugs related to the JIST Tool under BugTraq+ hierarchy in
    the "STC_BUG*" section of the STC.INFO file.

    Please direct results, questions, and comments to the mail alias listed
    in the "STC_CONTACT" in the STC.INFO file.


    JIST Makefile Build Procedure:
    ========================================================================

    USAGE: /usr/ccs/bin/make clean && /usr/ccs/bin/make package

    Run this as yourself from "<workspace>/usr/src/suites/storage/jist"
    on a Solaris 9 9/04, 10, 11, or later Sparc or x64 host.  This method
    requires Sun Studio[tm] 12 or later and Sun Java[tm] 2 Standard Edition
    (J2SE) 1.5.0, 6, or later build tools, available via local or "/ws" NFS
    mounts.  See the README.CONFIG file for more details on the Development
    Host requirements. This method requires "$HOME/.rhosts" to allow remote
    access.  If you wish to avoid "$HOME/.rhosts" use, then simply run the
    steps manually.

    Should Prototypes & Packages be forced to rebuild?
    Use the "make clean" command if you wish to force rebuild of all
    packages.  This is necessary if JIST Classes are added or removed since
    the last full build.

    Are any other gates referenced/required?
    This Makefile utilizes the fcio.h header file from the ONNV Gate and
    RFE 5029712 (PSARC 2006/063 fp(7d) FCRAW Interface).  With 5029712,
    Fibre Channel Passthru testing is possible.  Without 5029712, Fibre
    Channel Passthru testing is aborted in "lib/com/sun/jist/JIST.c".  If
    on SWAN, no changes are needed.  If off SWAN, download the latest ONNV
    source and expand under "/usr/src".

    Here is the Works:
    1. Remove previous Prototypes & Packages, if requested.
    2. Make JIST Java Class Archive (JAR).
    3. Make JIST Javadoc Documentation  Archive (JAR).
    4. Make JIST Native C Shared Library (SO) for SPARC or X86 Arch.
    5. Make JIST Solaris SUNWstc-jist Package & Offplatform Tar File.


    JIST Installation Procedure:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    If you have previously installed SUNWstc-jist or JAVAjist or SUNWjist,
    remove the old package with the following:

      * pkgrm SUNWstc-jist
      * pkgrm JAVAjist
      * pkgrm SUNWjist

    If you have previously installed a JIST Archive, remove the archive
    with the following:

      * rm -rf /opt/SUNWstc-jist

    On Solaris hosts, install the latest JIST Package with the following:

      * Download SUNWstc-jist.pkg from
        "http://dlc.sun.com/osol/test/downloads/current/" to /tmp.
      * pkgadd -d /tmp/SUNWstc-jist.pkg all

    On non-Solaris hosts, install the latest JIST Archive with the following:

      * Download SUNWstc-jist.zip from
        "http://dlc.sun.com/osol/test/downloads/current/" to /tmp.
      * cd /;unzip SUNWstc-jist.zip;chmod +x /opt/SUNWstc-jist/bin/jist

    Proceed to Test Execution Procedures.


    Sun Mandatory Single Initiator Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST Single Initiator Test Tree from Initiator Host:

      * Become UNIX/Linux Root or Windows Administrator on Initiator Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "Single Initiator" Test Tree and follow prompts.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    Sun Mandatory Multiple Initiator Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST Agent for each Initiator/Target/LUN (ITL) Combination Tested:

      * Become UNIX/Linux Root or Windows Administrator on Initiator Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select "JIST Agent" Test Tree and follow prompts.

    Start a JIST Multiple Initiator Test Tree from a Remote Host:

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "Multiple Initiator" Test Tree and follow prompts.

    Stop each JIST Agent started earlier by either telneting to the
    mangement port & entering "exitall" or by entering CTRL-C where the
    JIST Agent was started.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    Write/Read/Compare Load Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST Write/Read/Compare Load Test Tree from Initiator Host:

      * Become UNIX/Linux Root or Windows Administrator on Initiator Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "Write/Read/Compare Load" Test Tree and follow prompts.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    Persistent Reservation Removal Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST PERSISTENT RESERVE Clear Test Tree from Initiator Host:

      * Become UNIX/Linux Root or Windows Administrator on Initiator Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "PERSISTENT RESERVE Clear" Test Tree and follow prompts.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    Fibre Channel Switch Port Stress Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST Fibre Channel Switch Port Stress Test Tree from Any Host:

      * Become UNIX/Linux Root or Windows Administrator on Any Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "Fibre Channel Switch Port Stress" Test Tree and follow
        prompts.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    JIST Agent Test Execution:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    Start a JIST Agent for a Initiator/Target/LUN (ITL) Combination:

      * Become UNIX/Linux Root or Windows Administrator on Initiator Host

      * On UNIX/Linux, execute "/opt/SUNWstc-jist/bin/jist".

      * On Windows, execute "cd \opt\jist\bin" and then ".\jist.bat".

      * Select a "JIST Agent" Test Tree and follow prompts.

    Once started, a JIST Agent can be accessed by telneting to the
    management port.  Once connected, a "JIST Agent: " prompt indicates
    the JIST Agent is ready to take the next request.  JIST Agent Requests
    fall into 3 categories:

      * Exit Current or All JIST Agent Connections.

      * Execute a JIST Agent Test Tree or Leaf.

      * Inject a JIST Agent Fault Condition.

    Exiting the JIST Agent Connections is accomplished via the following
    JIST Agent Requests:

      * "exit" to exit the current JIST Agent Telnet connection and keep
        the JIST Agent operational.

      * "exitall" to exit all JIST Agent connections and gracefully
        shutdown the JIST Agent.

    Executing a JIST Agent Test Tree or Leaf is accomplished via the
    following JIST Agent Request formats:

      * "full.class.Name [option1=value1[,option2=value2[...]]]" to
        execute a JIST Test Tree.  An example execute ANSI T10 SCSI
        Write/Read/Compare Load Testing with 32 block maximum Transfer
        Length via 16 threads is
        "com.sun.jist.scsi.test.SBCrwStress maxTL=20,numThreads=10".

      * "full.class.Name#testMethod [option1=value1[,option2=value2[...]]]"
        to execute a JIST Test Leaf.  An example to execute ANSI T10
        SCSI INQUIRY EVPD Page 83 "Device Identifier" Test Leaf is
        "com.sun.jist.scsi.test.SPC12Test#testPage83".

    Injecting a JIST Agent Fault Condition is accomplished via the
    following JIST Agent Request formats:

      * "inject [Where[,option3=value3[...],]Return[,option4=value4[...]]"
        to inject a Return (Modified) Condition.  In this format, if
        option3 is equal to value3 statements are true for an iSCSI PDU,
        then the PDU is returned with modified value of option4 set to
        value4. Multiple option=value statements can be include for either
        following the Where or Return keywords.

      * "inject [Where[,option3=value3[...],]Delete" to inject a Delete
        Condition.  This operates the same as above, except if the
        Where statements are true, then the iSCSI PDU is removed from
        the data stream.

      * "inject [Where[,option3=value3[...],]Delay[Unit][=count]" to inject
        a Delay Condition.  This operates the same as above, except if the
        Where statements are true, then the iSCSI PDU data streams are
        delayed or a count of Unit Seconds.  "Unit" can be any of "Sec",
        "Milli", or "Nano".  By default, the Unit is Seconds.  The count
        is a count, in Hexadecimal, of how long to delay before allowing
	the PDUs to continue.

      * "inject [Where[,option3=value3[...],]Disconnect[Unit][=count]" to
        inject a Disconnect Condition.  This operates the same as the
        above Delay Condition, except the connection is closed after the
        count delay.

    JIST Agent Fault Condition "option" variables can be specified via
    the following formats:

      * "Offset[start[:length]]=value" to inject based on offset within
        the iSCSI PDU.  "start" and "length" specify the starting byte
        offset and length in bytes to be verified or modified.  "value"
        is a Hexadecimal encoded byte array.  This is useful for mass
        verifications and/or modifications PDU data.  Care must be taken
        to modify offsets for Digests and other length changing parameters.

      * "[protocol]VariableName=value" to inject based on JIST get/set
        method names.  "protocol" can be set to "scsi" or "iscsi" to
        explicitly refer to SCSIData or iSCSIData values.  "VariableName"
        refers to a variable with corresponding "getVariableName" and
        "setVariableName" methods.  Any variable with these entries can
        be modified in this manner.  This method automatically handles
        variable length offsets caused by Digests and related parameters.

    Stop each JIST Agent started earlier by either telneting to the
    mangement port & entering "exitall" or by entering CTRL-C where the
    JIST Agent was started.

    Conduct additional JIST Testing or proceed to JIST Results Analysis.


    JIST Results Analysis:
    ========================================================================

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************

    JIST is composed of Tens of Thousands of Low Level Tests.  To manage
    the large number of tests, the tests are groups into Trees, Branches,
    and Leaves.  The status of the Test Tree, Test Branches, and Test Leaves
    have increasing detail within the JIST Test Report.

    JIST provides additional documentation in the "doc" subdirectory of the
    JIST Log Directory.  The JIST Log Directory defaults to "/var/tmp/JIST"
    and be changed with the "logDir=..." parameter.  This is useful when
    multiple initiators are generating reports or for automatic report
    archiving.  The user running JIST will have to have write permissions
    to the directory.

      * To specify an alternate logging directory, execute
        "/opt/SUNWstc-jist/bin/jist logDir=/net/host/export/jist_logs".

    JIST provides a user selectable Report Detail Level setting
    "reportLevel".  JIST Report Detail Levels range from 0 to 9.  If not
    specified, the default JIST Report Detail Level is 5.  This can be
    provided as a option to the "/opt/SUNWstc-jist/bin/jist" script as follows.

      * To specify level 7, execute "/opt/SUNWstc-jist/bin/jist reportLevel=7".

    Here is a breakdown of the JIST Report Detail Levels.

    JIST Report Detail Level 0:

      * JIST Summary Report: This is the initial report to be reviewed once
        a Test Tree completes execution.  This contains summary information
        on Test Tree Status, Test Configuration, Test Leaf Runs, Test Leaf
        Passes, Test Leaf Faults, Test Leaf Defects, Test Leaf Bypasses, and
        Total Execution Time.  This report gives a one screen summary of the
        test tree execution.  Based on the "reportLevel" option specified,
        additional information will be provided and linked to this report.
	This report is called "index.html" in the report directory.

      * JIST Test Leaf Runs Report:  This report provides a listing of all
        JIST Test Leaf Passes, Faults, Defects, & Bypasses in the order they
        are executed.  This is a good report to monitor during the execution
        of a Test Tree.  Based on the "reportLevel" option specified,
        additional information will be provided in this report.  This report
        is called "total.html" in the report directory.

      * JIST Test Leaf Detail Reports:  This is a grouping of reports, one
        per Test Leaf.  These reports contain a 3 column table of records
        of test execution and/or test result information.  Based on the
        "reportLevel" option specified, additional information will be
        provided in this report.  These reports are called "test###.html"
        in the report directory, with "###" is a increasing hexadecimal
        number.

    JIST Report Detail Level 1:

      * JIST Report Detail Level 0 reports.

      * JIST Test Configuration Report:  This is the configuration snapshot
        of the device path being tested.  This was formerly the top of the
        JIST Report.  This report is called "config.html" in the report
        directory.

      * JIST Test Report, "CONFIG" Records:  Any "CONFIG" records will be
        logged at this level.

    JIST Report Detail Level 2:

      * JIST Report Detail Level 1 reports.

      * JIST Test Leaf Faults Report:  This report provides a listing of
        all Test Leaves ending due to a fault, such as out of memory.
        All faults should be corrected prior to reviewing additional test
        results.  This report is called "fault.html" in the report
        directory.

      * JIST Test Report, "FAULT" Records:  Any "FAULT" records will be
        logged at this level.

    JIST Report Detail Level 3:

      * JIST Report Detail Level 2 reports.

      * JIST Test Leaf Defects Report:  This report provides a listing of
        all Test Leaves ending with one or more defects identified, such
        as unexpected SCSI Status value.  Defects indicate design issues
        in the test configuration and most likely require software and/or
        hardware changes to be addressed.  No faults or defects can be
        identified to pass a Test Tree.  This report is called "defect.html"
        in the report directory.

      * JIST Test Report, "DEFECT" Records:  Any "DEFECT" records will be
        logged at this level.

    JIST Report Detail Level 4:

      * JIST Report Detail Level 3 reports.

      * JIST Test Report, "SENT" Records:  This is not an additional report,
        but rather additional detail within JIST Detail Reports.  "SENT"
        records are used to log the outgoing SCSI Command Descriptor Block
        being sent.

    JIST Report Detail Level 5:

      * JIST Report Detail Level 4 reports.

      * JIST Test Leaf Bypasses Report:  This report provides a listing of
        all Test Leaves ending due to an acceptable bypass condition,
        such as bypassing Sun Optional Test Leaves during testing of Sun
        Mandatory Test Leaves.  Bypasses indicate a condition necessary for
        the Test Leaf to execute was not present in the Test Configuration.
        This is normally only reviewed after no faults or defects were
        identified.  This report is called "bypass.html" in the report
        directory.

      * JIST Test Report, "BYPASS" Records:  Any "BYPASS" records will be
        logged at this level.

    JIST Report Detail Level 6:

      * JIST Report Detail Level 5 reports.

      * JIST Test Report, "DATA" and "SENSE" Records:  This is not an
        additional report, but rather additional detail within JIST Detail
        Reports.  "DATA" and "SENSE" records are used to log the resulting
        SCSI Data Buffer and the incoming SCSI Sense Buffer related to the
        above "SENT" record.  "DATA" records are logged when SCSI Status
        and SCSI Sense Key/ASC/ASCQ are both zero.  "SENSE" records are
        logged when either are non-zero.

    JIST Report Detail Level 7:

      * JIST Report Detail Level 6 reports.

      * JIST Test Leaf Passes Report:  This report provides a listing of
        all Test Leaves ending without any fault, defect, or bypass
        identified.  This report is called "pass.html" in the report
        directory.

      * JIST Test Report, "PASS" Records:  Any "PASS" records will be
        logged at this level.

    JIST Report Detail Level 8:

      * JIST Report Detail Level 7 reports.

      * JIST Test Report, Logic "DEBUG" Records:  This is not an additional
        report, but rather additional detail within JIST Detail Reports.
        Level 8 provides JIST Debugging information in the JIST Logic
        through JIST Remote Test layers.  This level of logging is not
        normally needed by users of JIST.

    JIST Report Detail Level 9:

      * JIST Report Detail Level 8 reports.

      * JIST Test Report, Dispatch "DEBUG" Records: This is not an
        additional report, but rather additional detail within JIST Detail
        Reports.  Level 9 provides the most verbose logging including
        detailed JIST Agent Proxy Intercepts and JIST Dispatch logging.
        This level of logging is not normally needed by users of JIST.

    ************************************************************************
    ****    WARNING : JIST DESTROYS DATA STORED ON THE TARGET DEVICE    ****
    ************************************************************************
`Name`	`Date`	`Size`
Up to higher level directory
`bin/`	17-Jun-2009
`doc/`	17-Jun-2009
`etc/`	17-Jun-2009
`lib/`	17-Jun-2009
`Makefile`	17-Jun-2009	`38.6K`
`pkgs/`	17-Jun-2009
`README`	17-Jun-2009	`23.3K`
`README.CONFIG`	17-Jun-2009	`5.2K`
`STC.INFO`	09-Sep-2009	`4.6K`