readme

iscsi源代码 UNH的progect 有initiator端和target端的源码

Updated 27-May-2004 by RDR

*************************************************************************
Target Features:

1) Supports draft 20 (RFC 3720)
2) Supports multiple sessions, multiple connections per session
3) Supports multiple devices
4) Supports multiple listening sockets
5) Supports header digest, data digest
6) Supports ErrorRecoveryLevel 1
7) Supports IPv4 and IPv6 addresses.
8) Supports 4 modes for emulating target storage


*************************************************************************
Naming on the target:

In the following discussion, the following terms are used:

target platform - the computer hardware on which the target module code is
		loaded and executed.  This platform must run the Linux
		operating system.

target modules - the software package that is loaded as modules to implement
		the functionality of an iscsi target.  There are 2 modules,
		both created in the src/target directory:
		unh_iscsi_target.o - is the iscsi part of the target, which
			implements the iscsi protocol and deals with TCP/IP.
		unh_scsi_target.o - is the scsi part of the target, which
			implements either the emulation of a scsi target or
			the interface to a real scsi target, depending on
			the mode of operation
		These modules provide access to a set of target controllers.

target controller - one of several objects accessible to an iscsi initiator via
		the target modules.  These are identified by numbers 0, 1, 2,
		..., MAX_TARGETS-1.  Each controller in turn provides access to
		a set of target logical units, which are given numbers (called
		LUNs) 0, 1, 2, ..., MAX_LUNS-1.

target logical unit - the storage object itself.  This is identified in the
		target modules by a controller number and a Logical Unit Number
		(LUN).  All SCSI commands are delivered by iSCSI to a single
		target logical unit.


The target iscsi module defines target controllers that have the names:
	iqn.2002-10.edu.unh.iol.iscsi.draft20-target:0
	iqn.2002-10.edu.unh.iol.iscsi.draft20-target:1
	iqn.2002-10.edu.unh.iol.iscsi.draft20-target:2
	. . .
where the number following the colon (:) at the end of each name is the
number of the controller referenced by that name.  These are the ONLY names
that can be requested by an initiator during the login phase with the key
TargetName=.  For example, an initiator could send the following key in the
first login request pdu it sends on a new connection:

	TargetName=iqn.2002-10.edu.unh.iol.iscsi.draft20-target:2

The association between this name and the actual controller on the target
platform depends on the mode in which the target scsi module is running.
There are 4 modes, as explained below:
	MEMORYIO
	DISKIO
	FILEIO
	GENERICIO

Each target controller itself can further define Logical Units (LUs) which
are the actual storage objects and which are referred to by Logical Unit
Numbers (LUNs) 0, 1, 2, ...  The association of an LU to physical storage
depends on which mode the target scsi module is running in.  To an initiator,
each [controller number, LUN] pair represents a separate mountable storage
device.


*************************************************************************
Modes of Target scsi Module Operation:

Before compiling the UNH scsi target module, you need to set options in the
file scsi_target.h.  The most important option is the mode of operation that
the target scsi module will run in.  There are 4 choices: MEMORYIO mode,
DISKIO mode, FILEIO mode and GENERICIO mode.  To set one of these options,
you need to uncomment the one you want and comment out all other options in the
source file scsi_target.h.  For example, the following selects the DISKIO mode:

//# define MEMORYIO	/* for performance studies */
# define DISKIO		/* to a real disk */
//# define FILEIO	/* to a file on the system */
//# define GENERICIO	/* when the scsi_do_req is not working */


Note -- you MUST select exactly one of these options.  Chaos will result
if you try to select more than one, or if you do not select any.
The distributed version selects FILEIO.

MEMORYIO
--------
When MEMORYIO is selected, there are no real storage objects on the target
platform.  When the target scsi module is asked to send data to an initiator,
the target scsi module will just send garbage data.  When the target scsi
module is asked to receive data from an initiator, it will just throw
the data away.  Thus the initiator is unable to read back what it just wrote,
because the target scsi module does not actually store anything sent to it.
This mode is used only to test the performance of the iSCSI/TCP/IP/network
stack.

In MEMORYIO mode, the target scsi module initializes itself to recognize
MAX_TARGETS target controllers, where MAX_TARGETS is defined in scsi_target.h
(the distributed version sets this to 8).  Furthermore, each controller is set
up to recognize MAX_LUNS logical units, where MAX_LUNS is defined in
scsi_target.h (the distributed version sets this to 16).


DISKIO
------
When installing a target scsi module compiled with DISKIO selected, the target
scsi module will search all available scsi disk HBAs (or tape HBAs if
TAPE_DEVICE is defined) on the target platform and will assign a controller
number to each of these HBAs, starting with 0 for the first HBA it finds.
The number of LUNs per HBA depends on the scsi HBA itself, since that HBA may
be any type of scsi controller with any number of actual storage devices
behind it.

Note: Before installing a target scsi module compiled in DISKIO mode, be sure
that none of the scsi disks (or tapes) are mounted on the target platform
(i.e., be sure they exist as just devices, not mounted devices).  This is
because the initiator will eventually mount these on the initiator platform
via the target modules, and the initiator will then believe that the device is
"local" to the initiator platform.  If it is also mounted on the target
platform, chaos will result.  


FILEIO
------
FILEIO mode is the most flexible mode of target scsi module operation.
It allows you to configure as many target controllers and luns as you want,
each of which is a file or a device accessible via the file system on the
target platform.  Normally, these objects are ordinary files in the host file
system of the target platform, but to the initiator they look just like
local disks attached to the initiator platform.  The contents of these files
is determined entirely by the actions of the initiator, and when used like
local disks each file will contain a super block, and a complete,
self-contained file system.

By default, when the target scsi module is installed in FILEIO mode, it
creates (if not already created) MAX_FILE_TARGETS times MAX_FILE_LUNS files.
These two defines are in the file scsi_target.c, and are set to 2 for
MAX_FILE_TARGETS and 4 for MAX_FILE_LUNS in the distributed version,
which means that 8 files are created (this emulates 2 target controllers,
numbers 0 and 1, with each controller having 4 LUNs, numbers 0, 1, 2 and 3).
These 8 default files in the distributed version have the names:
	scsi_disk_file_0_0
	scsi_disk_file_0_1
	scsi_disk_file_0_2
	scsi_disk_file_0_3
	scsi_disk_file_1_0
	scsi_disk_file_1_1
	scsi_disk_file_1_2
	scsi_disk_file_1_3
where the first digit is the controller number and the second digit is the LUN.
By redefining MAX_FILE_TARGETS and MAX_FILE_LUNS, you can create as many
default files as you want, up to a maximum of MAX_TARGETS and MAX_LUNS.
The size of each default file is FILESIZE blocks, and the number of bytes
in each block is BLOCKSIZE.  These two symbols are defined in the file
scsi_target.h, and in the distributed version are set to (4096 * 1024) for
FILESIZE, and 512 for BLOCKSIZE (which means that the maximum size of each
default file is 4096 * 1024 * 512 = 2,147,483,648 bytes = 2 Gigabytes).
However, storage for these files is allocated only as it is used.

In addition to the default files, which are created (if they do not
already exist) when a target scsi module compiled for FILEIO mode is loaded,
it is possible to dynamically add or remove other files while the target
scsi module is running.  This is done via the /proc file system by writing
appropriate commands to the file /proc/scsi_target/scsi_target.
To add a new file, use the addfile command.  To remove an existing file,
use the delfile command. For example,

	echo > /proc/scsi_target/scsi_target \
  "addfile targetid=1 lun=4 filename=xyz blocksinfile=262144 blocksize=512"

would create (if it does not already exist) a file called "xyz" and would
cause the target scsi module to regard this as LUN 4 of target controller 1.
In order to access this controller, the name given by the initiator during
a login negotiation would be:

	TargetName=iqn.2002-10.edu.unh.iol.iscsi.draft20-target:1

where the number after the colon (:) is the target controller number 1.
The initiator would see this mountable storage device as having a block size of
512 bytes per block, and a total of 262144 blocks (for a total of
134,217,728 bytes = 128 Megabytes), and would have to refer to it as LUN 4
in all SCSI commands sent to it.

When adding a new file, the targetid parameter must have a value less than
MAX_TARGETS, and the lun parameter must have a value less than MAX_LUNS.
In addition, there must not already be a file with that targetid and lun
combination in use.

Note that the initiator uses the number after the colon (:) in the
TargetName value to select which of the many target controllers on the target
module it wishes to connect to.  The initiator does NOT use the name of
the file (xyz in the above example), because, in theory, the initiator does
not even know that the storage object is implemented as a file -- the initiator
simply sees it as a storage device of some sort.  There is no way to have
the UNH iscsi target module recognize any other TargetName values.

Note also that within a given target controller, the use of the LUN is
handled by the SCSI subsystem on that initiator platform.  The LUN number is
generated by that SCSI subsystem and is given to the iscsi initiator by
that SCSI subsystem.  The iscsi initiator simply passes it on to the target
iscsi module, which passes it to the target scsi module where it is used in
DISKIO mode (along with the target controller number) to select the appropriate
file.

Finally, note that the name following the filename= parameter can be any
existing file or device on the target platform that can be accessed via
the Linux file system interface (i.e., open, close, read, write, seek).
In particular, it can be a block special device in the /dev directory,
which means that FILEIO mode can be used to enable the target to access
non-scsi disks.