DOCS: Add an initial manpage for iscsi-test-cu
This commit is contained in:
Ronnie Sahlberg
@@ -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
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
.\" Title: iscsi-ls
|
||||
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
|
||||
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
|
||||
.\" 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
|
||||
.\" -----------------------------------------------------------------
|
||||
|
||||
191
doc/iscsi-test-cu.1
Normal file
191
doc/iscsi-test-cu.1
Normal file
@@ -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 <http://docbook.sf.net/>
|
||||
.\" 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\ ]\ <ISCSI\-PORTAL>\fR\ 'u
|
||||
\fBiscsi\-test\-cu [ OPTIONS ] <ISCSI\-PORTAL>\fR
|
||||
.HP \w'\fBiscsi\-test\-cu\fR\ 'u
|
||||
\fBiscsi\-test\-cu\fR [\-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]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
iscsi\-test\-cu is a test suite for iSCSI/SCSI\&.
|
||||
.SH "ISCSI PORTAL URL FORMAT"
|
||||
.PP
|
||||
iSCSI portal format is \*(Aqiscsi://[<username>[%<password>]@]<host>[:<port>]/<iqn\-name>/<lun>\*(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=<IQN>
|
||||
.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=<IQN>
|
||||
.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=<family>|*[\&.<suite>|*[\&.<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[]
|
||||
250
doc/iscsi-test-cu.xml
Normal file
250
doc/iscsi-test-cu.xml
Normal file
@@ -0,0 +1,250 @@
|
||||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<refentry id="iscsi-test-cu.1">
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>iscsi-test-cu</refentrytitle>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refmiscinfo class="source">iscsi-test-cu</refmiscinfo>
|
||||
<refmiscinfo class="manual">iscsi-test-cu: iSCSI/SCSI protocol test suite</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
|
||||
<refnamediv>
|
||||
<refname>iscsi-test-cu</refname>
|
||||
<refpurpose>iSCSI/SCSI test suite</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<cmdsynopsis>
|
||||
<command>iscsi-test-cu [ OPTIONS ] <ISCSI-PORTAL></command>
|
||||
</cmdsynopsis>
|
||||
|
||||
<cmdsynopsis>
|
||||
<command>iscsi-test-cu</command>
|
||||
<arg choice="opt">-i --initiator-name=<IQN></arg>
|
||||
<arg choice="opt">-I --initiator-name-2=<IQN></arg>
|
||||
<arg choice="opt">-l --list</arg>
|
||||
<arg choice="opt">-t --test=<family>|*[.<suite>|*[.<test>|*]]</arg>
|
||||
<arg choice="opt">-d --dataloss</arg>
|
||||
<arg choice="opt">-s --allow-sanitize</arg>
|
||||
<arg choice="opt">-u --usb</arg>
|
||||
<arg choice="opt">-V --Verbose-scsi</arg>
|
||||
<arg choice="opt">-x --xml</arg>
|
||||
<arg choice="opt">-? --help</arg>
|
||||
</cmdsynopsis>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1><title>DESCRIPTION</title>
|
||||
<para>
|
||||
iscsi-test-cu is a test suite for iSCSI/SCSI.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1><title>ISCSI PORTAL URL FORMAT</title>
|
||||
<para>
|
||||
iSCSI portal format is 'iscsi://[<username>[%<password>]@]<host>[:<port>]/<iqn-name>/<lun>'
|
||||
</para>
|
||||
<para>
|
||||
Port is the TCP port on the target to connect to. Default is 3260.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Host can be specified either as a hostname, an IPv4 address or an
|
||||
IPv6 address.
|
||||
|
||||
Examples:
|
||||
<screen format="linespecific">
|
||||
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
|
||||
</screen>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>OPTIONS</title>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry><term>-i --initiator-name=<IQN></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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'
|
||||
</para>
|
||||
<para>
|
||||
This argument is used to change what initiator name to use
|
||||
for the primary session.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-I --initiator-name-2=<IQN></term>
|
||||
<listitem>
|
||||
<para>
|
||||
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'
|
||||
</para>
|
||||
<para>
|
||||
This argument is used to change what initiator name to use
|
||||
for the secondary session.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-l --list</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This argument lists all available tests.
|
||||
</para>
|
||||
<para>
|
||||
The tests are divided up into 'families', 'suites' and 'tests'
|
||||
separated by '.'.
|
||||
|
||||
<screen format="linespecific">
|
||||
iscsi-test-cu -l
|
||||
ALL
|
||||
ALL.CompareAndWrite
|
||||
ALL.CompareAndWrite.Simple
|
||||
ALL.CompareAndWrite.Miscompare
|
||||
ALL.GetLBAStatus
|
||||
ALL.GetLBAStatus.Simple
|
||||
ALL.GetLBAStatus.BeyondEol
|
||||
...
|
||||
</screen>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-t --test=<family>|*[.<suite>|*[.<test>|*]]</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<screen format="linespecific">
|
||||
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
|
||||
...
|
||||
</screen>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-d --dataloss</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-s --allow-sanitize</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
By default any SBC SANITIZE tests will be skipped. Use these
|
||||
arguments if you really want to perform SANITIZE tests.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-u --usb</term>
|
||||
<listitem>
|
||||
<para>
|
||||
SCSI devices that sit behind a USB bus are on linux limited
|
||||
to maximum 120k for any single SCSI Read*/Write*.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-V --Verbose-scsi</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
<screen format="linespecific">
|
||||
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.
|
||||
...
|
||||
</screen>
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-x --xml</term>
|
||||
<listitem>
|
||||
<para>
|
||||
This option to produce test results in machine readable format
|
||||
for automated testing.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry><term>-? --help</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Display basic help text.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
|
||||
<refsect1><title>SEE ALSO</title>
|
||||
<para>
|
||||
<ulink url="http://github.com/sahlberg/libiscsi"/>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user