182 lines
6.4 KiB
Plaintext
182 lines
6.4 KiB
Plaintext
Libiscsi is a client-side library to implement the iSCSI protocol that can be used
|
|
to access the resources of an iSCSI target.
|
|
|
|
The library is fully asynchronous with regards to iSCSI commands and SCSI tasks,
|
|
but a synchronous layer is also provided for ease of use for simpler
|
|
applications.
|
|
|
|
The src directory contains a handful of useful iSCSI utilities such as logging in
|
|
to and enumerating all targets on a portal and all devices of a target.
|
|
|
|
The examples directory contains example implementation of how to access both the
|
|
synchronous and asynchronous APIs of libiscsi.
|
|
|
|
Libiscsi is a work in progress.
|
|
It aims to become a fully asynchronous library for iSCSI functionality, including
|
|
all features required to establish and maintain an iSCSI session, as well as a
|
|
low-level SCSI library to create SCSI CDBs and parse/unmarshall data-in structures.
|
|
|
|
|
|
Installation
|
|
============
|
|
./autogen.sh
|
|
./configure
|
|
make
|
|
sudo make install
|
|
|
|
|
|
Build RPM
|
|
=========
|
|
To build RPMs run the following script from the libiscsi root directory
|
|
./packaging/RPM/makerpms.sh
|
|
|
|
iSCSI URL Format
|
|
================
|
|
iSCSI devices are specified by a URL format of the following form :
|
|
iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn>/<lun>
|
|
Example:
|
|
iscsi://server/iqn.ronnie.test/1
|
|
When using CHAP authentication, username and password can be specified as part of the URL
|
|
iscsi://ronnie%password@server/iqn.ronnie.test/1
|
|
but this may make the user and password visible in log files as well as in ps aux output.
|
|
So it is also possible to provide either just the password or both the password and username
|
|
via environment variables.
|
|
The username and/or password can be set via
|
|
LIBISCSI_CHAP_USERNAME=ronnie
|
|
LIBISCSI_CHAP_PASSWORD=password
|
|
|
|
Example:
|
|
LIBISCSI_CHAP_PASSWORD=password iscsi-inq iscsi://ronnie@10.1.1.27/iqn.ronnie.test/1
|
|
|
|
|
|
IPv6 support
|
|
============
|
|
Libiscsi supports IPv6, either as names resolving into IPv6 addresses or when
|
|
IPv6 addresses are explicitely set in the URL.
|
|
When specifying IPv6 addresses in the URL, they have to be specified in
|
|
[...] bracket form.
|
|
|
|
Example:
|
|
iscsi://[fec0:2727::3]:3260/iqn.ronnie.test/1
|
|
|
|
|
|
Header Digest
|
|
=============
|
|
Libiscsi supports HeaderDigest.
|
|
By default, libiscsi will offer None,CRC32C and let the target pick whether
|
|
Header digest is to be used or not.
|
|
This can be overridden by an application by calling iscsi_set_header_digest()
|
|
if the application wants to force a specific setting.
|
|
|
|
|
|
Patches
|
|
=======
|
|
The patches subdirectory contains patches to make some external packages
|
|
iSCSI-aware and make them use libiscsi.
|
|
Currently we have SG3-UTILS and MTX.
|
|
Patches for other packages would be welcome.
|
|
|
|
|
|
ISCSI-TEST-CU
|
|
=============
|
|
iscsi-test-cu is a CUnit based test tool for scsi and iscsi.
|
|
|
|
iscsi-test-cu depends on the CUnit library and will only build if libcunit can be
|
|
found during configure.
|
|
|
|
The configure script will check if a suitable libcunit is available and only
|
|
build the test tool if it can find libcunit.
|
|
This test is done toward the end of the configure phase and should result
|
|
in a line similar to :
|
|
|
|
checking whether libcunit is available... yes
|
|
|
|
Some example commands:
|
|
iscsi-test-cu -l to list all tests.
|
|
iscsi-test-cu -t <test-suite> <iscsi-url> to run a test suite
|
|
iscsi-test-cu -t <test-suite>.<test> <iscsi-url> to run a specific test
|
|
|
|
Most tests only require a single login to the target, but some tests,
|
|
for example the it nexus loss tests may need to login two separate sessions.
|
|
By default the initiator names use for the logins will be
|
|
"iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test";
|
|
for the primary connection for all tests, and
|
|
"iqn.2007-10.com.github:sahlberg:libiscsi:iscsi-test-2"
|
|
for the secondary connection for the test that needs two sessions.
|
|
These names can be controlled by using the arguments
|
|
--initiator-name and --initiator-name-2
|
|
|
|
The tests are all self-documented to describe what they test and how they test.
|
|
Use -V with a test to print the documentation for a test.
|
|
|
|
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
|
|
|
|
On Linux, the test tool can also access SG_IO devices directly. Just specify the
|
|
device as /dev/sg* instead of the iSCSI URL.
|
|
|
|
Example:
|
|
sudo iscsi-test-cu --test LINUX.Read10.Simple /dev/sg1
|
|
|
|
|
|
LD_PRELOAD FUN
|
|
==============
|
|
There is a small LD_PRELOAD hack in the src directory that intercepts a handful
|
|
of system calls and converts iSCSI URLs to look and behave as if they are normal
|
|
read-only files.
|
|
This allows using standard UNIX tools to become iSCSI-aware with no
|
|
modifications.
|
|
|
|
For example:
|
|
The stat command: this shows the size of the iSCSI LUN as if it was a normal file:
|
|
$ LD_PRELOAD=ld_iscsi.so stat iscsi://127.0.0.1:3262/iqn.ronnie.test/2
|
|
File: `iscsi://127.0.0.1:3262/iqn.ronnie.test/2'
|
|
Size: 3431540736 Blocks: 0 IO Block: 0 regular file
|
|
Device: 0h/0d Inode: 0 Links: 0
|
|
Access: (0444/-r--r--r--) Uid: ( 0/ root) Gid: ( 0/ root)
|
|
Access: 1970-01-01 10:00:00.000000000 +1000
|
|
Modify: 1970-01-01 10:00:00.000000000 +1000
|
|
Change: 1970-01-01 10:00:00.000000000 +1000
|
|
|
|
The cat command, which allows you to read/dump a iSCSI LUN to a file :
|
|
$ LD_PRELOAD=ld_iscsi.so cat iscsi://127.0.0.1:3262/iqn.ronnie.test/2 >copy_of_iscsi_lun
|
|
|
|
Or using dd even :
|
|
$ LD_PRELOAD=ld_iscsi.so dd if=iscsi://127.0.0.1:3262/iqn.ronnie.test/2 of=copy_of_LUN bs=10M count=1
|
|
|
|
The LD_PRELOAD hack is incomplete and needs more functions to be intercepted
|
|
before becoming fully functional. Patches welcome!
|
|
|
|
For now, it is sufficiently complete for trivial commands like stat and cat.
|
|
You probably need to implement at least lseek, pread, pwrite before it becomes
|
|
really useful.
|
|
|
|
|
|
SUPPORTED PLATFORMS
|
|
===================
|
|
libiscsi is pure POSIX and should with some tweaks run on any host that
|
|
provides a POSIX-like environment.
|
|
|
|
Libiscsi has been tested on:
|
|
* Linux (32 and 64 bit)
|
|
* Cygwin
|
|
* FreeBSD
|
|
* Windows (Win7-VisualStudio10)
|
|
* OpenSolaris
|
|
* Solaris 11 : Use "gmake" to build.
|
|
* OS X
|
|
|
|
RELEASE TARBALLS
|
|
================
|
|
Release tarballs are available at https://sites.google.com/site/libiscsitarballs/libiscsitarballs/
|
|
|
|
|
|
MAILINGLIST
|
|
===========
|
|
A libiscsi mailing list is available at http://groups.google.com/group/libiscsi
|
|
Announcements of new versions of libiscsi will be posted to this list.
|