iscsi client library and utilities
C Shell
Switch branches/tags
Nothing to show
Pull request Compare This branch is 1630 commits behind sahlberg:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Libiscsi is a clientside library to implement the iSCSI protocol
that can be used to access resource of an iSCSI Target.

The library is fully async with regards to iscsi commands and scsi
tasks, but a sync layer is also provided for ease of use for simpler

The src directory contain 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 contain example implementation of how to
access both the sync and acync api of libiscsi.

Libiscsi is a work in progress.
It aims to become a full async library for iscsi functionality,
including all features required to establish and maintain a iscsi
session, as well as a low level scsi library to create scsi cdb's
and parse/unmarshall data-in structures.

sudo make install

Build RPM
To build RPMs run the following script from the libiscsi root directory

iSCSI URL Format
iSCSI devices are specified by a URL format on the following form :
When using CHAP authentication, username and password can be specified as part of the URL
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_PASSWORD=password iscsi-inq iscsi://ronnie@

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.


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.

The patches subdirectory contains patches to make some external packages iscsi 
aware and make them use libiscsi.
Currently we have KVM/QEMU, SG3-UTILS and MTX.
Patches for other packages would be welcome.

The test-tool subdirectory contains a iscsi/scsi test tool.
This is a tool that is aimed at providing a comprehensive iscsi and scsi
emulation test suite. 

Run 'make iscsi-test' to compile it.
Run ./test-tool/iscsi-test --help and
Run ./test-tool/iscsi-test --list
for instructions

$ ./test-tool/iscsi-test --initiator-name=iqn.ronnie.test --test=T0105_read10_invalid iscsi://
Running test T0105_read10_invalid
Read10 1 block but with iscsi ExpectedDataTransferLength==0 ... [FAILED]
Read10 of 1 block with iscsi ExpectedDataTransferLength==0 should fail.
TEST T0105_read10_invalid [FAILED]

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/ stat iscsi://
  File: `iscsi://'
  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/ cat iscsi:// >copy_of_iscsi_lun

Or using dd even :
LD_PRELOAD=./bin/ dd if=iscsi:// of=copy_of_LUN bs=10M count=1

The LD_PRELOAD hack is incomplete and needs more functions to be intercepted before becomming 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.