Provided by: libiscsi-bin_1.19.0-3build2_amd64 bug

NAME

       iscsi-test-cu - iSCSI/SCSI test suite

SYNOPSIS

       iscsi-test-cu [ OPTIONS ] <ISCSI-PORTAL>

       iscsi-test-cu [-i --initiator-name=<IQN>] [-I --initiator-name-2=<IQN>] [-l --list]
                     [-t --test=<family>|*[.<suite>|*[.<test>|*]]] [-d --dataloss]
                     [-s --allow-sanitize] [-V --Verbose-scsi] [-x --xml] [-? --help]

DESCRIPTION

       iscsi-test-cu is a test suite for iSCSI/SCSI.

ISCSI PORTAL URL FORMAT

       iSCSI portal format is
       'iscsi://[<username>[%<password>]@]<host>[:<port>]/<iqn-name>/<lun>'

       Port is the TCP port on the target to connect to. Default is 3260.

       Username and password are only required if the target requires CHAP authentication.
       Optionally you can specify the username and password via the environment variables
       LIBISCSI_CHAP_USERNAME and LIBISCSI_CHAP_PASSWORD.

       Host can be specified either as a hostname, an IPv4 address or an IPv6 address. Examples:

                iscsi://192.0.2.1/iqn.ronnie.test/1
                iscsi://[2001:DB8::1]:3261/iqn.ronnie.test/1
                iscsi://ronnie%password@iscsi.example.com/iqn.ronnie.test/1

OPTIONS

       -i --initiator-name=<IQN>
           All tests use at least one iSCSI connection to the target and this is the initiator
           name used for that primary session and it defaults to
           'iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test'

           This argument is used to change what initiator name to use for the primary session.

       -I --initiator-name-2=<IQN>
           Some tests use a second connection to the target, such as the 'it nexus loss tests'.
           The default name used for this second connection is
           'iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test-2'

           This argument is used to change what initiator name to use for the secondary session.

       -l --list
           This argument lists all available tests.

           The tests are divided up into 'families', 'suites' and 'tests' separated by '.'.

               iscsi-test-cu -l
               ALL
               ALL.CompareAndWrite
               ALL.CompareAndWrite.Simple
               ALL.CompareAndWrite.Miscompare
               ALL.GetLBAStatus
               ALL.GetLBAStatus.Simple
               ALL.GetLBAStatus.BeyondEol
               ...

       -t --test=<family>|*[.<suite>|*[.<test>|*]]
           This argument specifies a comma-separated list of the test expressions to run. If this
           argument is omitted then all tests will be executed. You can also just specify a
           filename from which to read the list of tests.

               To run all tests:
               iscsi-test-cu --test=ALL iscsi://192.0.2.1/iqn.ronnie/test/1

               To run the READ16 test suite:
               iscsi-test-cu --test=SCSI.Read16.* \
                 iscsi://192.0.2.1/iqn.ronnie/test/1

               To just run a single specific test:
               iscsi-test-cu --test=iSCSI.iSCSIResiduals.Read10Invalid \
                 iscsi://192.0.2.1/iqn.ronnie/test/1

               Run all tests in the TestUnitReady suite and also the Reaqd16.Flags test
               iscsi-test-cu --test=SCSI.TestUnitReady.*,SCSI.Read16.Flags \
                 iscsi://192.0.2.1/iqn.ronnie/test/1

               Run all tests listed in the file ~/tests-to-run
               iscsi-test-cu --test=~/tests-to-run
                 iscsi://192.0.2.1/iqn.ronnie/test/1

       -d --dataloss
           By default the test tool will only run non-destructive tests. To test commands that
           mutates the data, such as the Write* tests you must specify the --dataloss flag.

           The tests that requre --dataloss will overwrite the data on the LUN and any and all
           data on that LUN will be destroyed when running these tests.

       -s --allow-sanitize
           The SBC SANITIZE opcode is expected to take significant time before it completes and
           thus tests for this opcode are not suitable for normal test runs.

           By default any SBC SANITIZE tests will be skipped. Use these arguments if you really
           want to perform SANITIZE tests.

       -V --Verbose-scsi
           The tests aims to be self-documenting. By specifying the -V flag the test tool will
           print all SCSI commands that are sent to the device, the arguments and the expected
           result.

           If a test fails, re-run the failing test with the -V argument to see why it failed. If
           that also fails it is time to pull out wireshark and have a look at what happened.

               iscsi-test-cu --test SCSI.Read10.BeyondEol iscsi://192.0.2.1/iqn.ronnie.test/1 -V
               Suite: Read10
                 Test: BeyondEol ...
                   Test READ10 1-256 blocks one block beyond the end
                   Send READ10 (Expecting LBA_OUT_OF_RANGE) LBA:2097152 blocks:1 rdprotect:0 dpo:0 fua:0 fua_nv:0 group:0
                   [OK] READ10 returned ILLEGAL_REQUEST/LBA_OUT_OF_RANGE.
               ...

       -x --xml
           This option to produce test results in machine readable format for automated testing.

           iscsi-test-cu can produce machine-readable test results for consumption by your CI
           server. Use the --xml option with any test suite(s), and a file called
           CUnitAutomated-Results.xml will be written to your current working directory. These
           results can be converted to JUnit format using this script:
           http://git.cyrusimap.org/cyrus-imapd/plain/cunit/cunit-to-junit.pl

           The return status of the script reflects whether the tests were successful or not. If
           you would rather have the script return a status to reflect whether the conversion
           from cunit to junit was successful you can patch the script with this:

               diff --git a/cunit-to-junit.pl.orig b/cunit-to-junit.pl
               index 7cf9320..9182ff0 100644
               --- a/cunit-to-junit.pl.orig
               +++ b/cunit-to-junit.pl
               @@ -226,4 +226,4 @@ foreach my $s (@suites)
                }

                print "$0: ran $nrun tests, $nfailed failed\n";
               -exit(1) if ($nfailed > 0);
               +#exit(1) if ($nfailed > 0);

       -? --help
           Display basic help text.

SEE ALSO

       http://github.com/sahlberg/libiscsi