xref: /netbsd-src/external/bsd/iscsi/dist/doc/README (revision 2f24582978112bccc072c8d33b43050a4f554290)

---------------------------------------
Intel iSCSI v20 Reference Implementation
---------------------------------------

This is a software implementation of iSCSI v20.  Included in this distribution
are both host and target mode drivers with built in conformance and performance
tests, and sockets tests that can be used to simulate TCP traffic identical to
that generated between a real iSCSI host and target.

See PERFORMANCE for information regarding the expected performance of this
distribution.

This code has been successfully compiled and tested on Redhat 8.0
(kernel version 2.4.18-14) and Redhat 9.0 (kernel version 2.4.20)
with UP and SMP configurations.

-------------------
Starting the System
-------------------

1a) Modify the array in initiator.c to contain your target ip addresses and port
   numbers. If you specify a TargetName there will be no discovery process. For
   example, targets 0 and 2 below will first be discovered. Target 1 will not.
   ISCSI_PORT is the default port defined in iscsi.h and currently set to 3260.

   static INITIATOR_TARGET_T g_target[CONFIG_INITIATOR_NUM_TARGETS] = {
   {"192.168.10.10", ISCSI_PORT, "",                     NULL, 0},
   {"192.168.10.11", ISCSI_PORT, "iqn.com.intel.abc123", NULL, 0},
   {"192.168.10.12", ISCSI_PORT, "",                     NULL, 0}};

   The initiator currently only connects to one of the discovered targets. If
   multiple TargetNames and TargetAddresses are returned, all but 1 are ignored.

1b) Alternately for the kernel mode driver you may specify ip addresses
   in a file in the local directory called "./intel_iscsi_targets". This
   file will also be looked for in the /etc directory or you may specify
   the file name as a module parameter to the insmod command using the
   "gfilename" argument, (insmod intel_iscsi.o gfilename="./targets").
   The format for the contents of of the file is:
       ip=192.168.10.10
       ip=192.168.10.11 name=iqn.com.intel.abc123 port=3260
       ip=192.168.10.12
   The name and port fields are optional.  If name is not specified, there
   will be a discovery process.  If port is not specified, the default port
   of 3260 will be used.

1c) For the user mode intiator, if the first entry of the g_target array has ip
   address "151.0.1.1", the initiator will prompt the user to enter the number
   of targets and their ip addresses.

2) Modify the following constant in initiator.h accordingly:

   #define CONFIG_INITIATOR_NUM_TARGETS 3

3) Run "make" to build each of:

   intel_iscsi.o - kernel mode iSCSI initiator
   kramdisk.o    - kernel mode iSCSI target ramdisk
   ufsdisk       - user mode iSCSI target (disk stored as file in /tmp)
   ufsdisk_mmap  - same as ufsdisk, but uses mmap
   uramdisk      - user mode iSCSI ramdisk
   utest         - user mode iSCSI test suite
   ktest         - invokes same tests as utest, but from within device driver
   usocktest     - user mode sockets test that simulates iSCSI traffic

4) Start a user level target (uramdisk, ufsdisk, ufsdisk_mmap) on each target
   machine:

   Usage: -t <name>           iSCSI TargetName (dflt "iqn.com.intel.abc123")
          -p <port>           Port Number (dflt 3260)
          -b <block len>      Block Length (dflt 512)
          -n <num blocks>     Number of Blocks (dflt 204800)


   Or start the kernel level target (kramdisk.o):

   Usage: insmod kramdisk.o port=<port>
                            block_len=<block length>
                            num_blocks=<number of blocks>


   With ufsdisk and ufsdisk_mmap you can directly access a device in /dev by
   creating a symbolic link in /tmp to point to the appropriate device. For
   example:

   "ln -s /dev/sdd /tmp/iqn.com.intel.abc123_3260_iscsi_disk_lun_0"

   And kramdisk.o only operates in ramdisk mode.

5) Run utest.  If you did not successfully connect to each target machine you
   specified in initiator.c, then there was a problem.  Make sure initiator.h
   and initiator.c were correctly edited and all your targets had been started.

6) As root, run "insmod ./intel_iscsi.o."  You should see output similar to the
   following when either viewing /var/log/messages or running dmesg:

     *********************************************
     *           PARAMETERS NEGOTIATED           *
     *                                           *
     *        InitiatorName:               Intel *
     *       InitiatorAlias:               Intel *
     *          SessionType:              normal *
     *           TargetName: iqn.com.intel.abc12 *
     *********************************************
     *********************************************
     *              LOGIN SUCCESSFUL             *
     *                                           *
     *                  CID:                   0 *
     *                 ISID:                   0 *
     *                 TSID:                   1 *
     *                CmdSN:                   0 *
     *             MaxCmdSN:                   0 *
     *            ExpStatSN:                   0 *
     *********************************************
     Vendor: Intel     Model: Intel Labs iSCSI  Rev: 2
     Type:   Direct-Access                      ANSI SCSI revision: 02
     Detected scsi disk sdb at scsi2, channel 0, id 0, lun 0
     SCSI device sdb: 204800 512-byte hdwr sectors (105 MB)
     sdb: unknown partition table

   You can now use the device as you would any other SCSI device.  You can also
   view driver statistics by viewing the file in /proc/scsi/iscsi.  Writing to
   the file (e.g. echo reset > /proc/scsi/iscsi/1) will reset all counters.

------------------
Testing the System
------------------

Once your targets and host have been started, you can test the installation
using either a single target, or by creating a RAID volume over multiple
targets.

To test a single target you can either directly read and write the device by
opening, for example, /dev/sdd. Or you can create a filesystem on the device:

	fdisk /dev/sdd
	mkfs /dev/sdd1
	mount -t ext2 /dev/sdd1 /mnt/iscsi_fs

To test a multiple target installation, you can create a RAID volume,
virtualizing multiple targets as one SCSI device.  The Linux RAID modules
will either need to be installed or compiled into the kernel.  The file
/etc/raidtab must be created to reflect your targets.  For example,

	raiddev /dev/md0
	raid-level              0
	nr-raid-disks           5
	persistent-superblock   0
	chunk-size              64

	device                  /dev/sdd
	raid-disk               0
	device                  /dev/sde
	raid-disk               1
	device                  /dev/sdf
	raid-disk               2
	device                  /dev/sdg
	raid-disk               3
	device                  /dev/sdh
	raid-disk               4


After initialized the raid device with "mkraid /dev/md0," you can use /dev/md0
as though it were a normal SCSI device.  For example,

	mkfs /dev/md0
	mount -t ext2 /dev/md0 /mnt/iscsi_fs

--------------------
When Things Go Wrong
--------------------

Check the kernel error messages /var/log/messages or run the dmesg command to
see any errors reported from the host driver. The targets will report target
errors to standard output.

If you need more fine grained debugging, modify the Makefile to turn on the
compilation flag CONFIG_ISCSI_DEBUG. Then run "make clean," and then "make."
You can select which type of debugging statements get printed by modifying
iscsiutil.h

-------------------------------------
Interoperability with Cisco Initiator
-------------------------------------

The target is tested to be interoperable with Cisco Initiator release
3.4.1.1