readme

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

 *****************************************************************************
 Installation and Design Notes for iSCSI Driver Version %VERSION% for Linux
 *****************************************************************************

 Maintained by [e-mail]

 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or (at
 your option) any later version. Please see the "GPL License" section
 for more information on this.

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 General Public License for more details.

 See the file COPYING included with this distribution for more
 details.


===============================================================================
CONTENTS
===============================================================================
  
  Product Overview
  Product Features
  Before Installing The Driver
  Installing And Removing The Driver
  Configuring And Using The Driver
  GPL License


===============================================================================
PRODUCT OVERVIEW
===============================================================================

  The iSCSI Driver provides a host with the ability to access storage
  through an IP network. The driver uses the iSCSI protocol to transport SCSI
  requests and responses over an IP network between the host and an iSCSI target
  device. The iSCSI protocol is an IETF-defined protocol for IP storage. For
  more information about the IETF standards, refer to http://www.ietf.org. 
  For more information about the iSCSI protocol, refer to the RFC 3720 at
  http://www.ietf.org/rfc/rfc3720.txt

  Architecturally, the iSCSI driver combines with the host's TCP/IP stack,
  network drivers, and Network Interface Card (NIC) to provide the same
  functions as a SCSI or a Fibre Channel (FC) adapter driver with a Host Bus
  Adapter (HBA) (see Figure 1).

  Figure 1 - iSCSI Driver Architecture 

       iSCSI Access To Storage     |  SCSI or FC Access to Storage
  ====================================================================
                                   |
        Host applications          |         Host applications
                                   |
  =======|===========|===============================|================
         |           |             |                 |
         |    +------------+       |                 |
         |    |    SCSI    |       |                 |
         |    |   driver   |       |                 |
         |    +------------+       |           +-----------+
         |    |   iSCSI    |       |           |           |
         |    |   driver   |       |           |   SCSI    |
    +---------+------------+       |           |   or FC   |
    |        TCP/IP        |       |           |  adapter  |
    +----------------------+       |           |  driver   |
    |   Network drivers    |       |           |           |
    +----------------------+       |           +-----------+
               |                   |                 |
  =============|=====================================|================
               |                   |                 |
         +-----------+             |           +-----------+
         |    NIC    |             |           |    HBA    |
         +-----------+             |           +-----------+
               |                   |                 |
  =============|=====================================|================
              _|_                  |                _|_               
            _(   )_                |              _(   )_             
          _(  IP   )_              |            _(  FC   )_           
         (_ network _)             |           (_ or SCSI _)          
           (_     _)               |             (_     _)            
             (_ _)                 |               (_ _)              
               |                   |                 |

      +------------------+         |                 |
      |  Storage Router  |         |                 |
      |    or Gateway    |         |                 |
      +------------------+         |                 |
               |                   |                 |
      +------------------+         |       +------------------+
      |     Storage      |         |       |      Storage     |
      +------------------+         |       +------------------+
      | (___)(___)(___)  |         |       | (___)(___)(___)  |
      | (___)(___)(___)  |         |       | (___)(___)(___)  |
      | (___)(___)(___)  |         |       | (___)(___)(___)  |
      | (___)(___)(___)  |         |       | (___)(___)(___)  |
      +------------------+         |       +------------------+
                                   |
  ====================================================================

  The iSCSI driver provides a transport for SCSI requests and responses to 
  storage devices via an IP network instead of using a direct attached SCSI bus
  channel or an FC connection. The Storage Router, in turn, transports these
  SCSI requests and responses received via the IP network between it and the
  storage devices attached to it.

  Once the iSCSI driver is installed, the host will proceed with a
  discovery process for storage devices as follows:

   1. The iSCSI driver requests available targets through SLP or SendTargets
      discovery mechanism as configured in the /etc/iscsi.conf configuration
      file.

   2. Each iSCSI target sends available iSCSI target names to the iSCSI driver.

   3. The iSCSI target accepts the login and sends target identifiers.

   4. The iSCSI driver queries the targets for device information.

   5. The targets respond with the device information.

   6. The iSCSI driver creates a table of available target devices.

  Once the table is completed, the iSCSI targets are available for use by the
  host using the same commands and utilities as a direct attached (e.g., via
  a SCSI bus) storage device.


===============================================================================
PRODUCT FEATURES
===============================================================================

  A list of the major features supported by the iSCSI driver are shown below.
  A more detailed description of each of these features is described in later
  sections of this document and with the associated man pages.

 1. Header and data digest support
 2. Two way CHAP authentication
 3. R2T flow control support with a target
 4. Third party multi-path support
 5. Sendtargets and SLP discovery mechanisms
 6. Dynamic target discovery
 7. Async event notifications for portal and target changes
 8. Immediate Data Support
 9. Error recovery level 0
10. iSCSI network boot support
11. Dynamic driver reconfiguration
12. Auto-mounting for iSCSI filesystems after a reboot


The following features are planned for future releases:

 1. Multiple connections per session
 2. Error recovery level 1 support in addition to level 0
 3. SNMP MIB support
 4. IPv6 support


===============================================================================
BEFORE INSTALLING THE DRIVER
===============================================================================

  The iSCSI driver, README file, and example configuration files are
  available on the Linux-iSCSI project homepage at:

    http://linux-iscsi.sourceforge.net

  In addition, at the website you can get information about the availability
  of new drivers, updated drivers, driver compatibility, and other relevant
  information.


===============================================================================
INSTALLING AND REMOVING THE DRIVER
===============================================================================

  This section describes the procedures for installing and removing the 
  iSCSI Driver covering the following topics:

    System Requirements
    Tested Hardware and Software
    Installation Procedure
    Removal Procedure
    Driver Upgrade Procedure
    Kernel Upgrade Procedure


-------------------
SYSTEM REQUIREMENTS
-------------------

  The 4.0.2 iSCSI Driver for Linux requires a host running the Linux 
  operating system with a kernel version of 2.6.10. Compilation will require
  the kernel header files matching the kernel version you wish to run the 
  driver on.

  If you are running a kernel binary compiled for you by a Linux vendor,
  the iSCSI driver must be compiled against the source code distributed
  by the Linux vendor, without any modifications. The process of compiling
  a custom kernel from source makes modifications to the files in the
  kernel source tree, and an iSCSI driver compiled against a modified
  kernel source tree may not run on a kernel binary distributed by your
  Linux vendor.  If you have already made changes to the kernel source
  tree and you wish to run the iSCSI driver on one of the vendor's kernel
  binaries, you will need to reinstall the kernel source code provided
  by your Linux vendor.

  The iSCSI driver requires support in the 2.6 Linux kernel for the following
  modules.

    1. CONFIG_SCSI
    2. CONFIG_CRYPTO
    3. CONFIG_CRYPTO_MD5
    4. CONFIG_CRYPTO_CRC32C

  The driver also requires the iscsi_transport_class.ko module. For 2.6.10,
  this module is included with this package (it can also be found in 2.6.11
  and above kernel source tree). The module is installed to the same location
  the iscsi_sfnet driver is.

  The iSCSI driver requires udev to be installed on the system for creation
  of iSCSI control device. The package can be downloaded from the
  following URL:

    http://kernel.org/pub/linux/utils/kernel/hotplug/udev-021.tar.gz
     
  The hotplug program is a pre-requisite for udev. The current version of
  the iSCSI driver is compiled and tested with hotplug package
  'hotplug-2003_08_05.tar.gz'. If this hotplug package is currently
  not installed, it can be obtained from the linux-hotplug project on
  sourceforge at:

    http://linux-hotplug.sourceforge.net

  The iSCSI driver requires sysfsutils package to be installed on the system.
  The current version of the iSCSI driver is compiled and tested with the
  sysfsutils package 'sysfsutils-1.2.0.tar.gz'. If the sysfsutils package is
  not currently installed, it can be obtained from the following URL:

    http://sourceforge.net/projects/linux-diag/

  There are some issues with the 2.6 Linux kernel code that can cause
  problems when using SCSI devices. Those know issues are:

   - Linux kernels have a known bug in the buffer and page cache design.
     When any writes to a buffered block device fail, it is possible
     for the unwritten data to be discarded from the caches, even though
     the data was never written to disk. Any future reads will get the
     prior contents of the disk, and it is possible for applications to
     get no errors reported.

     This occurs because block I/O write failures from the buffer
     cache simply mark the buffer invalid when the write fails. This
     leaves the buffer marked clean and invalid, and it may be
     discarded from the cache at any time.  Any future read either
     finds no existing buffer or finds the invalid buffer, so the
     read will fetch old data from disk and place it in the cache.

     If the fsync(2) function initiated the write, an error may be
     returned.  If memory pressure on the cache initiated the write,
     the unwritten buffer may be discarded before fsync(2) is ever
     called, and in that case fsync will be unaware of the data loss,
     and will incorrectly report success.

     There is currently no reliable way for an application to ensure
     that data written to buffered block devices has actually been
     written to disk.  Buffered data may be lost whenever a buffered
     block I/O device fails a write.

   - All Linux 2.6 kernels may trigger TCP retransmits from
     the iSCSI target system even though no packets were lost,
     mis-ordered or duplicated by the connecting network.
     Setting the sysctl variable net.ipv4.tcp_low_latency (if it
     exists) to 1 may reduce or eliminate the TCP retransmits.
 
  - RealTek ethernet controller RTL-8029 may encounter transmission
    problems under heavy load which may cause a system panic.

  - Intel ethernet controller Ethernet Pro 100 has two drivers eepro and
    e100. When the former is used, the network card may cease to function
    under heavy load conditions. It is recommended that you use e100.

  - The linux-2.6.10 has a bug in the SCSI middle layer. This bug can
    cause an oops on the system. The details of reproducing the bug and
    the fix can be found at Sourceforge:
    [ 1115345 ] Segmentation fault on stopping the driver
    http://sourceforge.net/tracker/index.php?func=detail&aid=1115345&group_id=26396&atid=387023
    This bug is fixed in linux-2.6.11.

----------------------------
TESTED HARDWARE AND SOFTWARE
----------------------------

  The 4.0.2 version of iSCSI driver has been tested successfully using the
  software and equipment listed below. The driver should also work with other
  software and hardware configurations not listed below, assuming they are
  consistent with the System Requirements described earlier in this document.