readme

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

to run the fdisk program.  This will interactively prompt you for
the information to create a partition table.  The partitions are
numbered 1, 2, etc., and correspond to the names /dev/sdb1, /dev/sdb2,
etc.

Once the target disk device has a valid partition table on it,
you can mount the various partitions using the mount command.  The
easiest way to do this is to have an entry in the file /etc/fstab and
a mount-point directory in the file system.  For example, to mount the
first partition (/dev/sdb1) on disk sdb, under the name /mnt/scsi,
the directory /mnt/scsi should be created (and be empty) and the
/etc/fstab should contain a line similar to:

	/dev/sdb1	/mnt/scsi	ext2	noauto	0 0

where ext2 is the type of file system expected on that device.

The mount command is then:

	mount /mnt/scsi

The above line in /etc/fstab says that partition /dev/sdb1 should
contain an ext2 file system.  If the mount command fails, it is probably
because the partition does not contain a valid ext2 file system.
To create one, type the shell command:

	/sbin/mke2fs	/dev/sdb1

and then try the mount command again.


If the partition does contain a valid ext2 file system, but it was
corrupted in any way (probably due to a system crash when it was
last mounted), a warning message is written by the Linux File subsystem
to the /var/log/messages file.  To correct the problem, first unmount
the disk using the shell command:

	umount /mnt/scsi

and then type the shell command:

	/sbin/e2fsck	/dev/sdb1

If this program detects any problems it will attempt to correct them,
which may involve prompting you interactively to help it decide what
to do (the best choice is to accept the default action in almost all
cases).

Once the device is mounted properly, the system administrator may
have to create directories on it for use by users.  This is done
using the mkdir command, along with the chown and chgrp commands.
For example, to create a directory called xyz on the newly mounted
/mnt/scsi device for user rdr in group iol, give the sequence of shell
commands:

	mkdir		/mnt/scsi/xyz
	chown	rdr /mnt/scsi/xyz
	chgrp	iol	/mnt/scsi/xyz


6. Using the target device
--------------------------

Once the target disk device has been mounted and directories have been
created on it, ordinary (non-superuser) users can access it like they
would any other disk device.  They do not have to have root access in
order to do this.

For example, to copy a file in his current directory called project.tgz
to his new directory on the disk (and keep the same file name), user rdr
can do:

	cp project.tgz /mnt/scsi/rdr

Presumably this is a tar file.  To untar it and rebuild it, do:

	cd /mnt/scsi/rdr
	tar zxvf project.tgz
	cd project
	make

etc.


7. Bringing down the target device
----------------------------------

Once all users have finished using a device, the System Administrator
(superuser) can unmount it using the shell command:

	umount /mnt/scsi

Note that no user can have any directory on that device as his or her
current directory, or the umount will fail with a busy indication.


8. Closing the session
----------------------

Once the mounted device has been unmounted, the session established
in step 4 above can be closed by giving the shell command:

	iscsi_config down ip=123.45.67.089 host=1

See section 10 below for a complete discussion of the iscsi_config
utility.


9. Unloading the unh_iscsi_initiator module
---------------------------------------

Once the device has been closed, the unh_iscsi_initiator module can be
unloaded by giving the shell command:

	/sbin/rmmod unh_iscsi_initiator

Note that step 8 above can be skipped if the user is going to
immediately unload the module, since all connections to targets
are automatically closed when the module is unloaded.


10. multiple sessions, luns, connections
----------------------------------------

The general form of a shell command to the iscsi_config utility is:

	iscsi_config up ip=123.45.67.089 port=5142 host=1 target=2 lun=3 cid=4
  or
	iscsi_config down host=1 target=2 lun=3 cid=4

Where the "up" or "down" parameter is required, and if any other parameter
is missing, its value is assumed to be 0.

The ip and port numbers are used to locate the target device, as explained
in step 4 above, and are used only when "up" is given.


The SCSI subsystem addresses all its devices by using the quadruple:

	(host, channel, target, lun)

  or in some places (like /proc/scsi/scsi):

  	(host, channel, id, lun)

where the host, target (id) and lun numbers are taken from the parameters
to the iscsi_config command, and the channel number is always 0 for the
reference implementations.  The host number must match that assigned to
the reference module when it was first loaded in step 2 above.  The
target and lun numbers can be chosen by the user, subject to the
restrictions:

	0 <= target < MAX_TARGET_IDS (currently 10)
and
	0 <= lun < MAX_LUNS (currently 8)

where MAX_TARGET_IDS and MAX_LUNS are compile-time constants defined in
the file "initiator/iscsi_initiator.h".


The cid number is a user-chosen number to identify the connection within
the session, subject to the restriction:

	0 <= cid <= 255

where 255 is a hard limit so that the cid value will fit in 1 byte.
(We do not anticipate more than 256 connections per session, even though
the standard allows for a cid value up to 65536!)


Rules for bringing up a new session, lun or connection:

	1.	The host number must match the number assigned to the iscsi
		reference initiator module when it was loaded and registered with
		the SCSI subsystem (step 2 above).

	2.	If the target number does NOT match that of any currently
		configured session, then start a new session (subject to the
		restriction of at most MAX_TARGET_IDS simultaneous sessions.
		The lun associated with this new session will be as given, and
		the cid for the first connection of this session will be as given.
		The new connection will be logged in and a new device will appear
		at the SCSI level (sdc, st4, etc.).

	3.	If the target number matches a currently configured session, then
		if the lun number does NOT match that of any currently configured
		lun for this session, add this lun to this session (subject to the
		restriction of at most MAX_LUNS simultaneous luns per session.
		The cid number is ignored in this case (because PDUs for any lun
		can be sent over any connection belonging to the session).  A new
		device will appear at the SCSI level (sdc, st4, etc.).


	4.	If the target number matches a currently configured session, and
		if the lun number matches a currently configured lun of this
		session, then if the cid number does NOT match that of any
		currently configured connection for this session, add a new
		connection to this session (subject to the restriction of at most
		MaxConnections connections per session, as negotiated during the
		very first login that established this session).  NO new device
		will appear at the SCSI level because the number of connections
		per session is an internal iSCSI matter, and is not seen outside
		iSCSI.

	5.	If the target number matches a currently configured session, and
		if the lun number matches a currently configured lun of this
		session, and if the cid number matches a currently configured
		connection of this session, then this is an error and the "up"
		is not performed.


Rules for bringing down a session, lun or connection:

	1.	The host number must match the number assigned to the iscsi
		reference initiator module when it was loaded and registered with
		the SCSI subsystem (step 2 above).

	2.	If the target number matches a currently configured session, and
		if the lun number matches a currently configured lun of this
		session, and if the cid number matches a currently configured
		connection of this session, then this connection is closed and
		removed from the session.  If this was the last connection
		associated with this session, then the entire session is closed
		too.  There is NO effect at the SCSI level unless the entire
		session is closed, in which case only the device indicated by
		the target and lun numbers will be removed.  This can cause
		problems if other devices were associated with this session,
		since they are not removed at the SCSI level.  This is because
		the iscsi_config program does not maintain any state and does
		not know what these other devices were.

	3.	If the target number matches a currently configured session, and
		if the lun number matches a currently configured lun of this
		session, and if the cid number does NOT match that of any
		currently configured connection for this session, then remove this
		lun from this session.  The corresponding device at the SCSI level
		will also be removed.  If this was the last lun associated with
		this session, then the entire session and all its remaining
		connections are closed too, and the device indicated by the target
		and lun numbers will be removed at the SCSI level.  This can cause
		problems if other devices were associated with this session, since
		they are not removed at the SCSI level.  This is because the
		iscsi_config program does not maintain any state and does not know
		what these other devices were.


	4.	If the target number matches a currently configured session, and
		if the lun number does NOT match a currently configured lun of
		this session, then close the entire session and all its remaining
		connections.  The cid number is ignored in this situation.  The
		device indicated by the target and lun numbers will be removed at
		the SCSI level.  This can cause problems if other devices were
		associated with this session, since they are not removed at the
		SCSI level.  This is because the iscsi_config program does not
		maintain any state and does not know what these other devices were.

	5.	If the target number does NOT match a currently configured
		session, then this is an error and the "down" is not performed.



 ipV6 Notes


 Included are updated cmd/iscsi_config.c to accept ipv6 addresses.

 Of course, several of the files in initiator/ and target/ and
 common/ were also changed to accommodate the ipv6 addresses.
 Now wherever there is an ip=, what follows the = can be
 ipv4 or ipv6.  There are lots of (now commented out) examples
 that are used for testing in the file cmd/ini-m1.
 That is how to tell the initiator to connect to a target using
 ipv6.

 To configure the target to use ipv6, you need to modify the
 file target/iscsi_portal_group.c.  At the end of that file is
 a table, and initialization for it.  The first 3 fields in each
 entry in that table are the IP address as a string, the port number
 as a string, and the portal group tag as a number.  The IP address
 can be ipv4 dotted decimal, or ipv6 in the bracketed notation
 refered to in Draft 20 section 12.8 and RFC 2732.  The first 2
 fields are strings, because these strings are used by the target
 to compose its responses to a SendTargets request during a
 discovery session.  Again there are (now commented out) examples
 in that file of how it is done.


 co-existing a IPv^6 on a V4 network ?

 I found out the hard way that our mods correctly deal with IPv6
 global scope address, but not link scope addresses
 (in IPv4 everything is global scope).  This is because link
 scope addresses need extra information (the interface name,
 like "eth0", "eth1") and we do not now provide a mechanism
 to deal with this extra info.  The global scope addresses
 do not need this, and work fine.

 Setting up IPV6 using only link scope addresses is trivial.
 You only need to do 2 things:
 1. add the line NETWORKING_IPV6=yes
    to the file /etc/sysconfig/network
 2. be sure the module ipv6 is loaded (or compiled in the kernel)
	When you bring up the network, you have IPv6, but with link scope
	addresses only, and this coexists with IPv4 on all the eth0, eth1,
	etc.  The IPv6 address is automatically constructed from the
	ethernet address.  The problem is, we can't use these addresses.
	I didn't find out about this until I tried it -- we did all our
	development on machines that had global scope address configured,
	so I wasn't even aware of the problem.

	To configure real global scope addresses requires a real, separate
	IPv6 network with IPv6 switches.  That's all I know about it --
	the IPv6 group in our lab set everything up for us, and it just
	worked.  But we can't get it to work on the ipv4 network that
	our iscsi group runs because we don't have the ipv6 capable
	switches (and we don't have the know-how to do the configuration,
	although we could learn that from the ipv6 group).

	If we have a chance, we can add the extra info so link scope
	addresses will work.  Then we can test on our own network.
	However, the IPv6 people claim these link scope addresses
	are almost never used (I can see why) and that it probably
	wasn't worth the effort to get them to work.  Certainly
	for the upcoming IPv6 plugfest we will not be needing or
	using them, since everyone there will be using global
	scope addresses.  Apparently the IPv6 group itself uses
	only global scope addresses.


 Notes on FKT.
 
 The initiator includes hooks for a tool called FKT:
 Fast Kernel Tracing, which allows us to trace every
 cycle in the kernel.  Using this we can see the flow
 through all the kernel routines, modules, etc.
 There are 2 ways to use this tool (both methods can be
 used simultaneously)  1 is to plant explicit probe macros
 at various points in the kernel code.  The other, which
 is best used with modules, is to compile the code using
 the gcc option -finstrument-functions.  This causes gcc
 to generate a call to an instrumentation fuction on every
 function entry and function return.  Just by supplying this
 compile-time option our iscsi modules will be traced by our
 FKT tool.  However, many functions are small, auxiliary
 functions that are not of much interest in following the
 flow, and they just clutter up the output generated by the
 tool (which is voluminous anyway).  So by applying the
 __attribute__  (no_instrument_function)
 to those functions, we are telling gcc that if the
 -finstrument_function optiion is in effect, then don't
 instrument this function (and if the -finstrument_function
 option is not in effect, the attribute is ignored).

 This tool is very useful -- I have already used it to find
 several problems with our memory management, have used it
 to reduce the number of function calls that "do nothing"
 because a test in the function causes it to return quickly,
 and even to find a bad gig card that was causing our initiator
 to freeze.