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
=============
./bin/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:
./bin/iscsi-test-cu -l to list all tests.
./bin/iscsi-test-cu -t <test-suite> <iscsi-url> to run a test suite
./bin/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


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=./bin/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=./bin/ld_iscsi.so cat iscsi://127.0.0.1:3262/iqn.ronnie.test/2 >copy_of_iscsi_lun

Or using dd even :
$ LD_PRELOAD=./bin/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.