readme

ISCSI user client software.Client would be used to access the IPSAN server.

  The test programs used were a variety of commercial applications and custom
  scripts that generated various types of traffic loads including raw and
  filesystem I/O, with and without errors being injected.

  1. Distributions:
       - None, since no 2.6 distributions were available when the driver was
         tested

  2. Machines:
       - Datanet Eclipse Server - 1 CPU
       - IBM Netfinity 8656 - 1 CPU
       - Compaq Evo Workstation - 1 CPU
       - Eclipse Server - 2 CPUs
       - Compaq Proliant DL360 - 2 CPUs

  3. Filesystems:
       - ext2
       - ext3


----------------------
INSTALLATION PROCEDURE
----------------------

  There are two ways of installing the iSCSI driver, viz.,

      1. Install iSCSI driver as a part of linux kernel.
      2. Install iSCSI driver as an external module.

  From linux-iscsi-4.0.1.2 onwards, release consists of following three 
  files:

    1. linux-iscsi-kernel-<ver>.patch - iSCSI kernel patch for linux 
       kernel

    2. linux-iscsi-user-<ver>.tgz - Contains iSCSI daemon and utilities.

    3. linux-iscsi-<ver>.tgz - Complete tar-ball containing kernel and 
       user code.

  Use files 1 and 2 for installing iSCSI driver as part of kernel.
  Use file 3 for installing iSCSI driver as an external kernel module.


  Installing iSCSI Driver as part of kernel
  ----------------------------------------

  1. Download linux-iscsi-kernel-<ver>.patch file to a working 
     directory (e.g., /usr/src/iscsi) where <ver> is the driver version 
     (e.g., 4.0.1.2).

  2. Apply the patch by executing the following command:

	patch -p0 < linux-iscsi-kernel-<ver>.patch

     Now change to kernel source top level directory (e.g. /usr/src/linux) and
     verify that under drivers/scsi, a directory named "iscsi-sfnet" has been
     created.

  3. Under kernel source top level directory (e.g. /usr/src/linux), execute
     make menuconfig and select iSCSI driver support
	
     To make iscsi driver built-in the kernel:

	Device Drivers  --->	
		SCSI device support  --->	
			SCSI low-level drivers  ---> 
				iSCSI Driver support  --->	
					<*> Provides ability to access 
						storage using iSCSI protocol

     To make iscsi as an internel kernel module:
   
	Device Drivers  --->	
		SCSI device support  --->	
			SCSI low-level drivers  ---> 
				iSCSI Driver support  --->	
					<M> Provides ability to access 
						storage using iSCSI protocol

  4. Compile the iSCSI driver as shown:

	make (Needed only if you have selected iSCSI driver an kernel builtin)
	make modules
	make modules_install

  5. Reboot the system, with kernel image generated in step 4, if you have 
     selected iSCSI driver as kernel builtin.

  6. Download "linux-iscsi-user-<ver>.tgz" file to a  working directory
     (e.g., /usr/src/iscsi)

  7. Change to the working directory created in step 6 and use tar(1) to
     uncompress the source archive. The archive will contain a subdirectory
     named linux-iscsi-<ver>. For example:

        cd /usr/src/iscsi
        tar xvzf linux-iscsi-user-4.0.1.tgz 
        cd linux-iscsi-4.0.1

  8. Your working directory (/usr/src/iscsi in the example above) now contains
     source files related to iSCSI daemon and utilities.

  9. Compile the iSCSI daemon and utilities sources by entering:
	   
         make

  10. As root, install the iSCSI daemon and utilities by entering:

         make install

  11. You may need to verify the order of the boot script because the iSCSI
      daemon tries to get a TCP connection to each configured iSCSI target
      and if the network interface has not started by the time the boot
      script runs, the connection(s) will not occur. Also, if you are using a
      non-RedHat Linux distribution you may need to edit your boot scripts to
      properly run the iSCSI setup script. You may also need to verify the order
      of the shutdown script.

  12. Edit /etc/iscsi.conf to setup the correct IP addresses and other required
      driver parameters. Refer to the Editing The iscsi.conf File section of
      this document for more information on the settings used in this file.

  13. Start the driver by entering the following command.

        /etc/init.d/iscsi start

      This should configure devices and cause the iSCSI driver to be loaded.

      Normal disk commands like mkfs and fsck will work on the iSCSI devices
      just like they work on a local hard drive.


  Installing iSCSI driver as an externel module
  ---------------------------------------------

  1.  Download the linux-iscsi-<ver>.tgz file to a working directory (e.g.,
      /usr/src/iscsi) where <ver> is the driver version (e.g., 4.0.1). If the
      directory already exists, remove any files from a previous installation.

  2.  Change to the working directory created in step 1 and use tar(1) to
      uncompress the source archive. The archive will contain a subdirectory
      corresponding to the archive name. For example:

         cd /usr/src/iscsi
         tar xvzf linux-iscsi-4.0.1.tgz
         cd linux-iscsi-4.0.1

      Your working directory (/usr/src/iscsi in the example above) now contains
      the iSCSI package. The package contains the driver and associated files.

  3.  Compile the iSCSI driver. If your kernel sources are not in the usual
      place, add 'TOPDIR=/path/to/kernel' or edit the definition of TOPDIR in
      the makefile. If your kernel configuration file is not in the usual
      place, add 'KERNEL_CONFIG=/path/to/.config' or edit the definition of
      KERNEL_CONFIG in the makefile. Compile the driver by entering:

         make

  4.  As root, install the driver by entering:

         make install

  5.  You may need to verify the order of the boot script because the iSCSI
      daemon tries to get a TCP connection to each configured iSCSI target
      and if the network interface has not started by the time the boot
      script runs, the connection(s) will not occur. Also, if you are using a
      non-RedHat Linux distribution you may need to edit your boot scripts to
      properly run the iSCSI setup script. You may also need to verify the order
      of the shutdown script.

  6.  Edit /etc/iscsi.conf to setup the correct IP addresses and other required
      driver parameters. Refer to the Editing The iscsi.conf File section of
      this document for more information on the settings used in this file.

  7.  Start the driver by entering the following command.

        /etc/init.d/iscsi start

      This should configure devices and cause the iSCSI driver to be loaded. 

      Normal disk commands like mkfs and fsck will work on the iSCSI devices
      just like they work on a local hard drive.

*******************************************************************************
NOTE: Before you begin, make sure that your iSCSI target is connected to your
      network. If another version of the Linux driver is currently installed
      (it may have been included with your Linux distribution), you will need to
      remove it before installing a newer driver version. See the installed
      driver's documentation for detailed procedures on removing the driver.
*******************************************************************************

-----------------
REMOVAL PROCEDURE
-----------------

  1. While logged in as root, stop the driver by entering:

        /etc/init.d/iscsi stop

  2. De-install the iSCSI driver package by entering:

        make remove

     This will delete the appropriate files from /lib/modules and
     /sbin.  The configuration files in /etc are not deleted, since
     they will be needed if another driver version is installed later.

  3. Go to the directory (e.g., /usr/src/iscsi) where iSCSI sources are
     present and remove the sources as shown:

     cd /usr/src/iscsi
     rm -rf linux-iscsi-<ver>		(in case of external kernel module)
     rm -rf linux-iscsi-user-<ver>	(in case iSCSI is part of kernel)

  4. If iSCSI driver is compiled as part of kernel, then change to
     kernel source directory, execute make menuconfig and un-select 
     the iSCSI driver support:

	Device Drivers  --->	
		SCSI device support  --->	
			SCSI low-level drivers  --->
				iSCSI Driver support  --->	
					<> Provides ability to access 
						storage using iSCSI protocol

     1. If iscsi driver was built-in kernel, then
       
         make 
         make modules
         make modules_install

        Reboot the system with new kernel image.   

     2. If iscsi driver was compiled as an internel kernel module, then

         make modules
	 make modules_install


------------------------
DRIVER UPGRADE PROCEDURE
------------------------

  To upgrade the iSCSI driver to the latest version, first deinstall the 
  existing package following the steps given in the Removal Procedure section
  of the README for the driver you currently have installed.

  Upon successful deinstallation, install the latest driver as described in the
  Installation Procedure section of the README for the new driver.


------------------------
KERNEL UPGRADE PROCEDURE
------------------------

  Because the iSCSI driver contains a Linux kernel module, the driver must
  be rebuilt and reinstalled if you make any changes to your Linux
  kernel. To remove, rebuild, and reinstall the driver, enter the following
  commands while logged in as root:

      make remove
      make clean
      make
      make install

  Because some Linux distributions include versions of this driver in their
  kernel source tree, recompiling your kernel source tree may create an
  older version of the iSCSI kernel module. The driver will fail to operate
  correctly if there is a version mismatch between the iSCSI daemon and the
  iSCSI kernel module.

  If your kernel source tree already contains a version of this driver
  different from the one you have installed, you must disable the iSCSI
  driver in your kernel configuration before recompiling a new kernel from
  source. Leaving the iSCSI driver enabled in the kernel configuration
  during a kernel rebuild may result in a newer iSCSI kernel module being
  replaced by an older version from the kernel source tree.


===============================================================================
CONFIGURING AND USING THE DRIVER
===============================================================================

  This section describes a number of topics related to configuring and using 
  the iSCSI Driver for Linux. The topics covered include:

    Starting and Stopping the iSCSI driver
    Rebooting Linux
    Device Names
    Auto-Mounting Filesystems
    Log Messages
    Dynamic Driver Reconfiguration
    Async Event Notification
    iSCSI HBA Status
    Using Multipath I/O Software
    Making Storage Configuration Changes
    Target and LUN Discovery Limits
    Service Location Protocol (SLP)
    Target Authentication