readme

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

  service configuration changes on the hosts accessing the associated
  storage devices. For example, changing the instance configuration
  may change the device presentation to the host's iSCSI driver,
  effectively changing the name or number assigned to the device
  by the host operating system. Certain configuration changes,
  such as adding or deleting targets, adding or deleting LUNs
  within a particular target, or adding or deleting entire instances
  may change the order of the devices presented to the host.
  Even if the host is only associated with one SCSI routing
  service instance, the device order could make a difference.

  Typically, the host operating system assigns drive identifications
  in the order they are received based on certain criteria. Changing
  the order of the storage device discovery may result in a changed
  drive identification. Applications running on the host may require
  modifications to appropriately access the current drives.

  If an entire SCSI routing service instance is removed, or there
  are no targets available for the host, the host's iSCSI driver
  configuration file must be updated to remove the appropriate
  reference before restarting the iSCSI driver. If a host's iSCSI
  configuration file contains an IP address of a SCSI routing
  service instance that does not exist, or has no targets available
  for the host, the iSCSI driver will not complete a login and
  will keep on trying to discover targets associated with this SCSI
  routing service instance.


  In general, the following steps are normally required when reconfiguring
  iSCSI storage:

   1. Unmount any filesystems and stop any applications using iSCSI
      devices.

   2. Stop the iSCSI driver by entering:

        /etc/init.d/iscsi stop

   3. Make the appropriate changes to the iSCSI driver
      configuration file. Remove any references to iSCSI
      DiscoveryAddresses that have been removed, or that
      no longer have valid targets for this host.

   4. Modify /etc/fstab.iscsi and application configurations as
      appropriate.

   5. Restart the iSCSI driver by entering:

        /etc/init.d/iscsi start 

  Failure to appropriately update the iSCSI configuration using 
  the above procedure may result in a situation that prevents 
  the host from accessing iSCSI storage resources.


-------------------------------
TARGET AND LUN DISCOVERY LIMITS
-------------------------------

  The bus ID and target ID are always zero in the new one hba per transport
  model since every target will have one hba instance. The host ID is unique
  for every target and changes across reboots. Totally 0 to 2^23 -1 hosts can
  be allocated on a linux system. The lun ID is assigned by the iSCSI target,
  the iSCSI intiator driver currently supports 256 LUNs per target.
  If a LUN ID > 256 it will be ignored by the driver and will not be
  configured in the system.


-------------------------------
SERVICE LOCATION PROTOCOL (SLP)
-------------------------------

  Target discovery through SLP is supported by the driver and can be used
  in addition to or in place of the DiscoveryAddress mechanism.
  Two types of entries in the /etc/iscsi.conf file determine how the SLP
  queries will be made by the driver to discover iSCSI targets:

   - "SLPUnicast=<IP Address>" entries /etc/iscsi.conf specify the driver to
      unicast a SLP query to discover iSCSI targets using TCP/IP to the
      specified <IP Address> (assuming this IP Address corresponds to that of a
      SLP Service Agent(SA) or a SLP Directory Agent(DA)).

   - "SLPMulticast=<comma separated list of host system IP addresses or
     "none" or "all"> entries in /etc/iscsi.conf specify the list of host
     system network IP addresses corresponding to the networks over which SLP
     queries will be multicast.

  Both these types of entries can occur multiple times in /etc/iscsi.conf
  with each entry defining a separate SLP query to be done. The driver uses the
  union of the discovery information from all discovery sources when deciding
  which target sessions to establish. For more information about the SLP
  protocol, refer to the IETF standards at http://www.ietf.org.

  *****************************************************************************
  NOTE: openslp release 1.1.4 and onwards is required for discovering iSCSI
	  targets using SLP discovery mechanism. Uncomment the following line
	  in Makefile to enable SLP:
		#ENABLE_SLP:= 1
  *****************************************************************************


------------------
iSCSI NETWORK BOOT 
------------------

 The Linux iSCSI driver has been designed to support various network boot
 applications. iSCSI network boot allows a user to boot a computer without a
 directly attached disk and instead, use a networked iSCSI disk drive. As with
 any iSCSI disk, even though it is not directly attached to the computer
 accessing it, the disk appears to the computer as if it were directly attached
 via the IP network connection.

 Shown below are two iSCSI network boot programs that are available today:

  1. Cisco's Network Boot program (iNBP) available from:

       http://www.cisco.com/en/US/products/hw/ps4159/ps2160/products_
              installation_and_configuration_guides_list.html

  2. PXELINUX which is a derivative of SYSLINUX available from:

       http://www.kernel.org/pub/linux/utils/boot/syslinux/

  The Cisco Network Boot program has been tested and works with this version of
  the Linux iSCSI driver. The PXELINUX program has not been tested.

  Detailed instructions for installing and configuring the network boot programs
  listed above can be found in the documentation supplied on their websites. In
  addition, an open source replication utility used for cloning a complete image
  from one disk to another disk (usually an iSCSI disk or LUN) can be found at:

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


---------------------
TARGET AUTHENTICATION
---------------------

  The CHAP authentication mechanism provides for two way authentication between
  the target and the initiator. The CHAP authentication capability must also be
  available on the iSCSI target device for this feature to work.

  The username and password for both the initiator and the target needs to be
  added to the /etc/iscsi.conf file. The username and password can be specified
  as global values or can be made specific to each target address. Please refer
  to the Editing The iscsi.conf File section of this document for a more
  detailed description of these parameters.


---------------------------
EDITING THE ISCSI.CONF FILE
---------------------------

  The /etc/iscsi.conf file is used to control the operation of the iSCSI driver
  by allowing the user to configure the values for a number of programmable
  parameters. These parameters can be setup to apply to specific configuration
  types or they can be setup to apply globally. The configuration types that are
  supported are:

    - DiscoveryAddress = SCSI routing instance IP address with format a.d.c.d
                         or a.b.c.d:n or hostname.
    - TargetName = Target name in 'iqn' or 'eui' format
                   e.g.: TargetName = iqn.1987-05.com.cisco:00.0d1d898e8d66.t0
    - Subnet = Network portal IP address with format a.b.c.d/n or a.b.c.d&hex

  The complete list of parameters that can be applied either globally or to the
  configuration types listed above are shown below. Not all parameters are
  applicable to all configuration types. Some of the parameters are actual
  iSCSI login keys, and others are just configuration options for the 
  initiator.

  ___________________________________________________________________________

          KEYS                      DESCRIPTION              DEFAULT VALUE
  ___________________________________________________________________________

   OutgoingUsername      CHAP username used for initiator           -
                         authentication by the target.

   OutgoingPassword      CHAP password used for initiator           -
                         authentication by the target.

   IncomingUsername      CHAP username for target                   -
                         authentication by the initiator.

   IncomingPassword      CHAP password for target                   -
                         authentication by the initiator.

   HeaderDigest          Type of header digest support the         prefer-off
                         initiator is requesting of the target.

   DataDigest            Type of data digest support the           prefer-off
                         initiator is requesting of the target.

   SLPUnicast            Single IP address of the SLP service       -
                         or directory agent.

   SLPMulticast          Multicast IP addresses used to discover    -
                         SLP service or directory agents.

   PollInterval          Time interval between successive SLP      5 min
                         queries sent out.

   LoginTimeout          Time interval to wait for a response      15 sec
                         to a login request to be received from
                         a target before failing a connection
                         attempt.

   AuthTimeout           Time interval to wait for a response      45 sec
                         to a login request containing
                         authemtication information to be
                         received from a target before failing
                         a connection attempt.

   IdleTimeout           Time interval to wait for on a            60 sec
                         connection before sending a ping when
                         there are no active tasks in the
                         session.

   ActiveTimeout         Time interval to wait for on a             5 sec
                         connection before sending a ping when
                         there are active tasks in the session.

   PingTimeout           Time interval to wait for a ping          5 sec
                         response after a ping is sent before
                         failing a connection.

   ConnFailTimeout       Time interval to wait before failing      0 sec
                         SCSI commands back to an application
                         for unsuccessful commands.

   AbortTimeout          Time interval to wait for a abort         10 sec
                         command to complete before declaring
                         the abort command failed.

   ResetTimeout          Time interval to wait for a reset         30 sec
                         command to complete before declaring
                         the reset command failed.

   Enabled               Enable/Disable a target or list of        yes
                         targets.

   InitialR2T            Enabling/disabling of R2T flow control    no
                         with the target.

   ImmediateData         Enabling/disabling the sending of         yes
                         unsolicited data burst with the iSCSI
                         command PDU.

   MaxRecvDataSegment    Maximum number of bytes that the          128K
   Length                initiator can receive in an iSCSI PDU.

   FirstBurstLength      Maximum number of bytes of unsolicited    256K
                         data the initiator is allowed to send.

   MaxBurstLength        Maximum number of bytes for the SCSI      16M
                         payload negotiated by initiator.

   TCPWindowSize         Maximum number of bytes that can be       256K
                         sent over a TCP connection by the
                         initiator before receiving an
                         acknowledgement from the target.

   Continuous            Enabling/disabling the discovery          yes
                         session to be kept alive. If 
                         Continuous = "yes" and a "Reject(0x3f)" 
                         message is received from the target in 
                         response to the ping (NOP_OUT) message 
                         sent by the initiator, the Continuous
                         parameter will be set to "no" and no 
                         further ping messages will be sent by
                         the initiator.

   SendAsyncText         Enable/disable sending "X" keys related to  	yes
                         Async events; Cisco target only.

  A detailed description for each of these parameters is included in both the
  man page and the included sample iscsi.conf file. Please consult these sources
  for examples and more detailed programming instructions.


-------------------------------
TUNING iSCSI TIMEOUT PARAMETERS
-------------------------------

  - ConnFailTimeout (Default = 0)

  Set this value to fail commands when there is network problem. Default
  value of 0 means that commands will not be failed. You might want to
  change ConnFailTimeout under following scenario:

  If the network is down for sufficiently long time, the application
  doing I/Os to iSCSI device will seem to hang. At this point, you
  might want to fail the I/Os by setting ConnFailTimeout to a reasonably
  low value. This will fail the I/Os to the application and the
  application will resume.

 *****************************************************************************
 NOTE: The above timeout can usually be changed dynamically by following the 
       instructions under Dynamic Driver Reconfiguration section. The above