NetBSD-5.0.2/dist/iscsi/doc/README
---------------------------------------
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