ISCSI-TEST-CU(1)

💖 ISCSI-TEST-CU 💖

okay bestie, so this is the manual page for iscsi-test-cu, section 1 of the manuals. it's a whole test suite for iSCSI/SCSI and honestly? it's giving "i will find out if your target is lying to you" energy. periodt. 🦋

---

✨ NAME ✨

iscsi-test-cu — the iSCSI/SCSI test suite, aka your new favorite way to bully a storage target (affectionately) 💅

---

✨ 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. that's the whole vibe, no notes. 🫶

---

🌸 ISCSI PORTAL URL FORMAT 🌸

the iSCSI portal format goes a little something like this:

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

• Port is the TCP port on the target to connect to. the default is 3260. lowkey iconic default, ngl.
• 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. (env vars > typing secrets in shell history, fr fr 🙈)
• Host can be specified either as a hostname, an IPv4 address or an IPv6 address.

examples, because we love a demonstration ✨:

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> — every test uses at least one iSCSI connection to the target, and this is the initiator name used for that primary session. 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, like 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 . — cute little hierarchy, obsessed.

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. versatility? we love her.

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 mutate the data, such as the Write* tests, you must specify the --dataloss flag.

🚨 bestie listen to me. the tests that require --dataloss will overwrite the data on the LUN, and any and all data on that LUN will be destroyed when running these tests. gone. obliterated. not coming back. 💀

• -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. like, truly, deeply, in your soul want to. 😭

• -V, --Verbose-scsi — the tests aim 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. (wireshark: the final boss 🧚)

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 is 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. the classic. the icon. 💅

---

🌈 SEE ALSO 🌈

http://github.com/sahlberg/libiscsi — go peek, it's where all the lore lives ✨

---

and that's the whole page, bestie!! this one is from iscsi-test-cu and it's dated 02/16/2015. thanks for reading, you absolute main character — go run some tests and slay 💖🎀🦋💜