diff --git a/doc/Makefile.am b/doc/Makefile.am index 08e6e5e..293c644 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,11 +1,12 @@ XSLTPROC = /usr/bin/xsltproc # Manpages -man1_MANS = iscsi-inq.1 iscsi-ls.1 iscsi-swp.1 +man1_MANS = iscsi-inq.1 iscsi-ls.1 iscsi-swp.1 iscsi-test-cu.1 EXTRA_DIST = iscsi-inq.1 iscsi-inq.xml \ iscsi-ls.1 iscsi-ls.xml \ - iscsi-swp.1 iscsi-swp.xml + iscsi-swp.1 iscsi-swp.xml \ + iscsi-test-cu.1 iscsi-test-cu.xml .xml.1: if BUILD_MANPAGES diff --git a/doc/iscsi-ls.1 b/doc/iscsi-ls.1 index f0630c0..dd97aa5 100644 --- a/doc/iscsi-ls.1 +++ b/doc/iscsi-ls.1 @@ -2,12 +2,12 @@ .\" Title: iscsi-ls .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.78.1 -.\" Date: 03/22/2014 +.\" Date: 03/24/2014 .\" Manual: iscsi-ls: list iSCSI targets and LUNs .\" Source: iscsi-ls .\" Language: English .\" -.TH "ISCSI\-LS" "1" "03/22/2014" "iscsi\-ls" "iscsi\-ls: list iSCSI targets" +.TH "ISCSI\-LS" "1" "03/24/2014" "iscsi\-ls" "iscsi\-ls: list iSCSI targets" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- diff --git a/doc/iscsi-test-cu.1 b/doc/iscsi-test-cu.1 new file mode 100644 index 0000000..b096244 --- /dev/null +++ b/doc/iscsi-test-cu.1 @@ -0,0 +1,191 @@ +'\" t +.\" Title: iscsi-test-cu +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.78.1 +.\" Date: 03/24/2014 +.\" Manual: iscsi-test-cu: iSCSI/SCSI protocol test suite +.\" Source: iscsi-test-cu +.\" Language: English +.\" +.TH "ISCSI\-TEST\-CU" "1" "03/24/2014" "iscsi\-test\-cu" "iscsi\-test\-cu: iSCSI/SCSI pr" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +iscsi-test-cu \- iSCSI/SCSI test suite +.SH "SYNOPSIS" +.HP \w'\fBiscsi\-test\-cu\ [\ OPTIONS\ ]\ \fR\ 'u +\fBiscsi\-test\-cu [ OPTIONS ] \fR +.HP \w'\fBiscsi\-test\-cu\fR\ 'u +\fBiscsi\-test\-cu\fR [\-i\ \-\-initiator\-name=] [\-I\ \-\-initiator\-name\-2=] [\-l\ \-\-list] [\-t\ \-\-test=|*[\&.|*[\&.|*]]] [\-d\ \-\-dataloss] [\-s\ \-\-allow\-sanitize] [\-u\ \-\-usb] [\-V\ \-\-Verbose\-scsi] [\-x\ \-\-xml] [\-?\ \-\-help] +.SH "DESCRIPTION" +.PP +iscsi\-test\-cu is a test suite for iSCSI/SCSI\&. +.SH "ISCSI PORTAL URL FORMAT" +.PP +iSCSI portal format is \*(Aqiscsi://[[%]@][:]//\*(Aq +.PP +Port is the TCP port on the target to connect to\&. Default is 3260\&. +.PP +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\&. +.PP +Host can be specified either as a hostname, an IPv4 address or an IPv6 address\&. Examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf + 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 + +.fi +.if n \{\ +.RE +.\} +.sp +.SH "OPTIONS" +.PP +\-i \-\-initiator\-name= +.RS 4 +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 \*(Aqiqn\&.2007\-10\&.com\&.github:sahlberg:libiscsi:iscsi\-test\*(Aq +.sp +This argument is used to change what initiator name to use for the primary session\&. +.RE +.PP +\-I \-\-initiator\-name\-2= +.RS 4 +Some tests use a second connection to the target, such as the \*(Aqit nexus loss tests\*(Aq\&. The default name used for this second connection is \*(Aqiqn\&.2007\-10\&.com\&.github:sahlberg:libiscsi:iscsi\-test\-2\*(Aq +.sp +This argument is used to change what initiator name to use for the secondary session\&. +.RE +.PP +\-l \-\-list +.RS 4 +This argument lists all available tests\&. +.sp +The tests are divided up into \*(Aqfamilies\*(Aq, \*(Aqsuites\*(Aq and \*(Aqtests\*(Aq separated by \*(Aq\&.\*(Aq\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +iscsi\-test\-cu \-l +ALL +ALL\&.CompareAndWrite +ALL\&.CompareAndWrite\&.Simple +ALL\&.CompareAndWrite\&.Miscompare +ALL\&.GetLBAStatus +ALL\&.GetLBAStatus\&.Simple +ALL\&.GetLBAStatus\&.BeyondEol +\&.\&.\&. + +.fi +.if n \{\ +.RE +.\} +.sp +.RE +.PP +\-t \-\-test=|*[\&.|*[\&.|*]] +.RS 4 +.sp +.if n \{\ +.RS 4 +.\} +.nf +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\&.* \e + iscsi://192\&.0\&.2\&.1/iqn\&.ronnie/test/1 + +To just run a single specific test: +iscsi\-test\-cu \-\-test=iSCSI\&.iSCSIResiduals\&.Read10Invalid \e + iscsi://192\&.0\&.2\&.1/iqn\&.ronnie/test/1 +\&.\&.\&. + +.fi +.if n \{\ +.RE +.\} +.sp +.RE +.PP +\-d \-\-dataloss +.RS 4 +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\&. +.sp +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\&. +.RE +.PP +\-s \-\-allow\-sanitize +.RS 4 +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\&. +.sp +By default any SBC SANITIZE tests will be skipped\&. Use these arguments if you really want to perform SANITIZE tests\&. +.RE +.PP +\-u \-\-usb +.RS 4 +SCSI devices that sit behind a USB bus are on linux limited to maximum 120k for any single SCSI Read*/Write*\&. +.sp +When testing against a USB SCSI device you need to specify these arguments so that the tests will clamp the read/write size to a maximum of 120k\&. +.RE +.PP +\-V \-\-Verbose\-scsi +.RS 4 +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\&. +.sp +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\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +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\&. +\&.\&.\&. + +.fi +.if n \{\ +.RE +.\} +.sp +.RE +.PP +\-x \-\-xml +.RS 4 +This option to produce test results in machine readable format for automated testing\&. +.sp +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 +.RE +.PP +\-? \-\-help +.RS 4 +Display basic help text\&. +.RE +.SH "SEE ALSO" +.PP +\m[blue]\fB\%http://github.com/sahlberg/libiscsi\fR\m[] diff --git a/doc/iscsi-test-cu.xml b/doc/iscsi-test-cu.xml new file mode 100644 index 0000000..e1b4b41 --- /dev/null +++ b/doc/iscsi-test-cu.xml @@ -0,0 +1,250 @@ + + + + + iscsi-test-cu + 1 + iscsi-test-cu + iscsi-test-cu: iSCSI/SCSI protocol test suite + + + + + iscsi-test-cu + iSCSI/SCSI test suite + + + + + 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 + -u --usb + -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>|*]] + + + +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 +... + + + + + + -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. + + + + + -u --usb + + + SCSI devices that sit behind a USB bus are on linux limited + to maximum 120k for any single SCSI Read*/Write*. + + + When testing against a USB SCSI device you need to specify these + arguments so that the tests will clamp the read/write size to + a maximum of 120k. + + + + + -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 + + + + + -? --help + + + Display basic help text. + + + + + + + + SEE ALSO + + + + + + diff --git a/packaging/RPM/libiscsi.spec.in b/packaging/RPM/libiscsi.spec.in index d1a82ac..3905e63 100644 --- a/packaging/RPM/libiscsi.spec.in +++ b/packaging/RPM/libiscsi.spec.in @@ -105,6 +105,7 @@ Test tool for iSCSI/SCSI targets %files testsuite %defattr(-,root,root) %{_bindir}/iscsi-test-cu +%{_mandir}/man1/iscsi-test-cu.1.gz %changelog