readme

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

14-Oct-2003			    iscsi_initiator							RPM 1.4.01
						---------------

	vi: set autoindent tabstop=4 shiftwidth=4 :

Note:	this document is written in ordinary ASCII text with tabs set
		to a width of 4.

This directory contains the C source code for the UNH initiator
reference implementation.  It depends on code contained in
../common and ../security that is shared by both the reference
initiator and the reference target.

The current code supports draft 20 of the proposed iSCSI standard.

The current code supports the following features of the standard:
	-	header and data digests
	-	CHAP and SRP authentication methods
	-	multiple simultaneous sessions
	-	multiple LUNs per session
	-	multiple connections per session
	-	normal and discovery sessions
	-	redirection on login
	-	all combinations of InitialR2T and ImmediateData keys
	-	arbitrary (legal) values for MaxRecvDataSegmentLength,
		MaxBurstLength and FirstBurstLength
	-	arbitrary number of outstanding R2Ts
	-	data and data-sequences in any order
	-	error recovery levels 0, 1.
	-	optional periodic nop "ping" to/from target
	-	all PDU types, including SNACK
	-   ipV6 addressing 
	-   Initial SNMP iSCSI MIB statistics.

We do not yet support:
	-	markers
	-	bidirectional commands
	-	Additional Header Segments (AHS)

	
The following sequence of steps details the process necessary to
use this module.  You must run as root (super user) to perform
steps 1 through 5 inclusive, and steps 7 through 9 inclusive
(i.e., an ordinary user can only perform step 6, which is to
use a target device after it has been set up).


1. Making the loadable unh_iscsi_initiator module
-------------------------------------------------

Doing a "make" in the directory above this will create a module
called unh_iscsi_initiator.o which must be dynamically loaded
into the Linux kernel using /sbin/insmod:

		/sbin/insmod unh_iscsi_initiator.o

(See also the file ../cmd/ini-install)
This module has been tested for various kernel versions up through 2.4.20.
The Makefile expects that the path "/lib/modules/`uname -r`/build" contains
the source for the running kernel (where `uname -r` produces a string
such as "2.4.20-18.9").


2. Loading the unh_iscsi_initiator module
-------------------------------------

While running as part of the kernel, the unh_iscsi_initiator writes
information to the file /var/log/messages.  The best way to see what
the unh_iscsi_initiator is doing is to open a separate window and in
that window type:
	tail -f /var/log/messages
which will "hang" on the /var/log/messages file and will write to
the screen each new line added to the end of that file.

As part of loading the module, unh_iscsi_initiator registers itself
with the Linux SCSI subsystem under the name "iscsi_initiator" as a
Host Bus Adapter (HBA) with 1 device.  The Linux SCSI subsystem will
assign a "host" number to this HBA at this time.
Be careful -- this host number is simply a sequential counter
maintained by the Linux SCSI subsystem and the value assigned to the
unh_iscsi_initiator HBA depends on the number of other SCSI HBAs
registered with the Linux SCSI subsystem prior to the time the
unh_iscsi_initiator module is loaded.  If your system has no other SCSI
HBAs, then the unh_iscsi_initiator will be assigned host number 0.  If
you have a SCSI disk adaptor, then that adaptor will be host 0 and the
unh_iscsi_initiator will be number 1. etc.

Next, the SCSI subsystem attempts to probe the target devices attached to
the unh_iscsi_initiator HBA, but since this is entirely a software entity,
there are currently no devices, so a number of
	Target n not logged in
messages are written to /var/log/messages.  The SCSI subsystem
attempts no further action on any of these targets until the
user takes the actions described next.


3. Configuring the unh_iscsi_initiator module
---------------------------------------------

As part of loading the unh_iscsi_initiator module, an internal table
of parameter keys is initialized to the default values.  These can be
changed (configured) using the program ../cmd/iscsi_manage.
In addition, this program can also be used to force certain behavior
from the unh_iscsi_initiator.  (See the file ../cmd/ini-manage which
contains lots of examples of this.)

For example, to set the value of a parameter key when the
unh_iscsi_initiator has been assigned host number 1, type the following
shell command after the unh_iscsi_initiator module has been loaded:

	../cmd/iscsi_manage init set InitialR2T=No host=1

When the login process is started (see section 4), all keys set in
this manner will be offered to the target as part of the login
negotiation process.  Note that the first command line parameter
to this program is "init" to indicate "initiator" because the same
iscsi_manage program is also used to configure the reference target,
in which case the first command line parameter would be "target".


This command can be repeated any number of times with different keys.

In order to have a valid login to a normal session, at least the
TargetName and InitiatorName keys should be set (although for testing
purposes, these can be omitted).  If no keys are set by this
configuration tool, then no keys will be offered to the target during
the login phase.  All keys defined by the draft standard can be
configured in this way.

A second form of configuration is to use "restore" instead of "set",
and to omit any "key=value" after the "restore".  This restores
all parameters values and forced values (see below) to their
default values.  When writing shell scripts containing manage
commands, the first command should always be:

	../cmd/iscsi_manage init restore host=1

so that scripts will always restore the configuration to a known
default before making changes.

A third form of configuration is to use "force" instead of "set"
as the second command line parameter to the iscsi_manage program.
In this case, the parameter following the "force" will have the
form "option" or "option=value", depending on the "force" option.
For example, giving the shell command:

	../cmd/iscsi_manage init force s host=1

		forces the iscsi_initiator to start in the security
		parameter negotiation stage, even if no security parameter
		keys have been configured to be sent to the target.

Other possible "force" configuration options are:

	../cmd/iscsi_manage init force o host=1

		forces the iscsi_initiator to offer the operational
		parameter negotiation stage, even if no operational parameter
		keys have been configured to be sent to the target.

	../cmd/iscsi_manage init force r host=1

		forces the iscsi_initiator to reply to all boolean key
		offers, even in the 2 special cases when replies to boolean
		offers can be omitted (when the offer to a boolean AND function
		is No, and when the offer to a boolean OR function is Yes.)
		Without this force, the iscsi_initiator will omit these optional
		replies.

	../cmd/iscsi_manage init force f host=1

		forces the iscsi_initiator to use the "flat space
		addressing method", as described in SAM-2 section 4.12.6, when
		packing an ordinary LUN number into the 8-byte LUN structure
		described in SAM-2 section 4.12.3.  Without this force, the
		iscsi_initiator uses the "peripheral device addressing method",
		as described in SAM-2 section 4.12.5, by default.

	../cmd/iscsi_manage init force n=20 host=1

		forces the iscsi_initiator to send NopOut PDUs to the
		target if there has been no activity on a connection for 20
		seconds or more.

	../cmd/iscsi_manage init force p=10 host=1

		forces the iscsi_initiator to use a retransmission wait period
		of 10 seconds during error recovery.

	../cmd/iscsi_manage init force sch=1 host=1

		forces the iscsi_initiator to use one of the following scheduling
		algorithms for sending commands over multiple connections:
				sch=0	all commands send on first connection -- the default
				sch=1	distribute commands over all connections in a
						round-robin fashion
				sch=2	map each LUN onto exactly one connection
						(not implemented yet)

	../cmd/iscsi_manage init force t host=1

		forces the iscsi_initiator to use target confirmation in a
		CHAP or SRP authentication exchange.  The default is not to
		use target confirmation after an initiator successfully
		responds to a target challenge.

	../cmd/iscsi_manage init force b host=1

		forces the iscsi_initiator to use base64 format when sending
		a large-binary-value in CHAP or SRP authentication keys.  The
		default is hex format.

	../cmd/iscsi_manage init force px="peer secret string" host=1

		forces the iscsi_initiator to use the "peer secret string"
		as the secret when generating the CHAP_R response to send
		back to the target in response to a challenge from the
		target.  There is no default value, so a "px" value must be
		forced if CHAP authentication is to be used.

	../cmd/iscsi_manage init force pn="peer name string" host=1

		forces the iscsi_initiator to use the "peer name string" as
		the CHAP_N value to send back to the target in response to a
		challenge from the target.  There is no default value, so a
		"pn" value must be forced if CHAP authentication is to be used.

	../cmd/iscsi_manage init force lx="local secret string" host=1

		forces the iscsi_initiator to use the "local secret string"
		as the secret when checking CHAP_R responses sent from the
		target in response to a confirmation challenge to the target.
		There is no default value, so an "lx" value must be forced if
		CHAP authentication is to be used and the "t" option has also
		been forced.

	../cmd/iscsi_manage init force ln="local name string" host=1

		forces the iscsi_initiator to use the "local name string"
		to check the CHAP_N value sent from the target in response
		to a confirmation challenge to the target.  There is no default
		value, so an "ln" value must be forced if CHAP authentication
		is to be used and the "t" option has also been forced.

	../cmd/iscsi_manage init force cl=256 host=1

		forces the iscsi-initiator to use 256 as the length in bytes
		of the large-binary-value generated as the value of CHAP_C
		when sending a challenge to the target.  The maximum allowed
		value after the "=" is 1024.

	../cmd/iscsi_manage init force sx="SRP secret string" host=1

		forces the iscsi_initiator to use the "SRP secret string" as
		the secret when generating and checking SRP challenges sent
		to/from the target.  There is no default value, so an "sx"
		value must be forced if SRP authentication is to be used.

	../cmd/iscsi_manage init force sn="SRP name string" host=1

		forces the iscsi_initiator to use the "SRP name string" as the
		value of the SRP_U key sent to the target.  There is no
		default value, so an "sn" value must be forced if SRP
		authentication is to be used.

	../cmd/iscsi_manage init force sg=SRP_1536 host=1

		forces the iscsi_initiator to use group SRP_1536 during
		an SRP authentication.  The allowed values after the "="
		are: SRP-768, SRP-1024, SRP-1280, SRP-1536, and SRP-2048.
		The default is SRP_1536 if no "sg" value is forced.

Typically the collection of iscsi_manage commands necessary to configure
the unh_iscsi_initiator module correctly for a certain target are written
in a shell command file that is made executable so that just typing
the name of that single file will run all the necessary iscsi_manage
commands in sequence.  This file should probably also end with the command
described in section 4 to active the module once it has been configured.
A example file called "ini-manage" is included in the "cmd" directory
of the distribution.


4. Opening connections to target devices
----------------------------------------

After the unh_iscsi_initiator module has been loaded and configured,
it must be explicitly directed to make connections to target devices.
This is done using a second program, called iscsi_config.  In order to
use this, the DNS name or IP address of the target must be known.  In
addition, if the target is expecting connections on any port other than
the WKP (3260), this must also be known in advance.  (See section 10
below for a complete discussion of the iscsi_config utility.)  The
shell level command that causes the initiator to attempt to connect to
the target at IP address 123.45.67.089 and WKP 3260 is:

	iscsi_config up ip=123.45.67.089 lun=0 host=1
 or
	iscsi_config up ip=123.45.67.089 port=3260 lun=0 host=1

This will cause iscsi_initiator to create a new session and a new
connection to that target, and if that succeeds, to then start
the login phase negotiations by sending a login PDU to the target.
If security parameter keys have been configured, or if the security
negotiation stage has been forced during the configuration, this
first login will be in the security negotiation stage (CSG=0);
otherwise it will be in the operational negotiation stage (CSG=1).

The login phase will then proceed, using as many exchanges of login
and login reply PDUs as necessary until either the login fails or
the iscsi_initiator receives a valid login response with a transition
to the Full Feature Phase (i.e., T=1 and NSG=3).

On a successful transition to Full Feature Phase, the iscsi_initiator
will enable any digests negotiated during the Login Phase, and then
the SCSI subsystem will be informed that there is now a device
available on the unh_iscsi_initiator HBA.  The SCSI subsystem will then
give the iscsi_initiator an INQUIRY command, which will be sent to the
target and the reply given back to the SCSI subsystem, which will then
report the information it has received by writing appropriate messages
to the /var/log/messages file.  It is via the INQUIRY command that the
SCSI subsystem finds out the type of device represented by the target
(i.e., direct access (disk), sequential access (tape), etc.).

The actions that follow depend on the type of device offered by the
target.  If that device is a disk, the SCSI subsystem will next send,
via the iscsi_initiator, a TEST_UNIT_READY command, and if that is
successful, it is followed by a READ_CAPACITY command.  If that is
successful, the SCSI subsystem will report the size of the disk and
the size of blocks on the disk (again by writing messages to the
/var/log/messages file), and will then issue a READ_10 command to
read block 0 from the disk.

Note that if lun=0 is ommitted from the above iscsi_config command,
then after the transition to FUll Feture Phase ALL luns, not just
lun 0, will be probed via INQUIRY commands, as just described.


As with the assignment of a host number to the unh_iscsi_initiator HBA,
devices activated by the iscsi_config program are assigned the next
device name of the appropriate type according to the current state of
the Linux system.  For example, the first SCSI disk activated on a
Linux system is given the name sda, the second is given the name sdb,
etc.  Therefore, if the iscsi_config program has activated a target
disk, it will be called sda or sdb or sdc, etc., depending on how many
other scsi disks have been activated prior to issuing the iscsi_config
command.  Similarly, if the device activated by the iscsi_config
program is a tape, the names assigned are st0, st1, st2, etc.
These names are printed by the SCSI subsystem in the /var/log/messages
file after a successful login.


5. Setting up the target device
-------------------------------

If the target device is a disk, then the Linux system expects block 0
to contain a partition table in a standard format.  If this is not
found, the message "unknown partition table" will be written to the
/var/log/messages file.  At this point you will have to run the
fdisk program to create a valid partition table.  If your disk has
been assigned the name sdb, then give the shell command:

	/sbin/fdisk	/dev/sdb