readme

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

    Editing The iscsi.conf File
    Tuning iSCSI Timeout Parameters
    iSCSI Commands and Utilities
    Driver File Listing


--------------------------------------
STARTING AND STOPPING THE iSCSI DRIVER
--------------------------------------

  To manually start the iSCSI driver enter:

          /etc/init.d/iscsi start

  The iSCSI initialization will report information on each detected
  device to the console or in dmesg(8) output. For example:
  
  ********************************************************************
  Vendor: SEAGATE   Model: ST39103FC         Rev: 0002
  Type:   Direct-Access                      ANSI SCSI revision: 02
  Detected scsi disk sda at scsi0, channel 0, id 0, lun 0
  SCSI device sda: hdwr sector= 512 bytes.
                               Sectors= 17783240 [8683 MB] [8.7 GB]
  sda: sda1
  ********************************************************************

  To see the iscsi devices currently available on this system, use the
  utility:

    /sbin/iscsi-ls -l

  If there are problems loading the iSCSI kernel module, diagnostic
  information will be placed in /var/log/iscsi.log.

  To manually stop the iSCSI driver enter:

     /etc/init.d/iscsi stop

  When the driver is stopped, the init.d script will attempt to kill all
  processes using iSCSI devices by first sending them "SIGTERM" and then
  by sending any remaining processes "SIGKILL". The init.d script will 
  then unmount all iSCSI devices in /etc/fstab.iscsi and kill the iSCSI
  daemon terminating all connections to iSCSI devices. It is important to
  note that the init.d script may not be able to successfully unmount
  filesystems if they are in use by processes that can't be killed. It is
  recommended that you manually stop all applications using the filesystem
  on iSCSI devices before stopping the driver. 

  It is very important to unmount all filesystems on iSCSI devices before
  stopping the iSCSI driver. If the iSCSI driver is stopped while iSCSI
  devices are mounted, buffered writes may not be committed to disk and file
  system corruption may occur.


---------------
REBOOTING LINUX
---------------

  To safely reboot a Linux system, enter the following command:

      reboot
        OR
     /sbin/shutdown -r now 

  All iSCSI devices should be unmounted prior to a system shutdown or reboot.
  See the Starting And Stopping The Driver section of this document for a more
  detailed description of the unmounting process.


------------
DEVICE NAMES
------------

  iSCSI driver uses the default kernel names for iSCSI device. This
  is inline with other SCSI devices and transports like FC/SATA.

  Since Linux assigns SCSI device nodes dynamically whenever a
  SCSI logical unit is detected, the mapping from device nodes
  (e.g., /dev/sda or /dev/sdb) to iSCSI targets and logical units may
  vary.

  Variations in process scheduling and network delay may result in
  iSCSI targets being mapped to different SCSI device nodes every time
  the driver is started.  Because of this variability, configuring
  applications or operating system utilities to use the standard
  SCSI device nodes to access iSCSI devices may result in SCSI
  commands being sent to the wrong target or logical unit.

  The above issues justify the need for persistent device naming for
  iSCSI devices. If you intend to have persistent names for iSCSI devices,
  you can make use of one or more schemes available for 2.6 kernel users.
 
  a) Udev - udev can be used to provide persistent names for all types of
  devices. scsi_id program which provides serial number for a given block
  device is integrated with udev and can be made use for persistency.

  b) Devlabel - This is another user application which can be configured
  to provide persistent naming. It ensures the devices get the same name
  by mapping the device serial number with desired device name in a
  database.

  c) UUID & LABEL based mouting - Filesystems provide facility to mount
  devices by UUID or LABEL and hence ensure persistency across reboots.


-------------------------
AUTO-MOUNTING FILESYSTEMS
-------------------------

  Filesystems installed on iSCSI devices cannot be automatically mounted at
  system reboot due to the fact that the IP network is not yet configured at
  mount time. However, the driver provides a method to auto-mount these
  filesystems as soon as the iSCSI devices become available (i.e., after the IP
  network is configured).

  To auto-mount a filesystem installed on an iSCSI device, follow these steps:

   1. List the iSCSI partitions to be automatically mounted in
      /etc/fstab.iscsi which has the same format as /etc/fstab. The
      /etc/fstab.iscsi file will not be overwritten when the driver is
      installed nor will removing the current version of the driver delete
      /etc/fstab.iscsi. It is left untouched during an install.

   2. For each filesystem on each iscsi device(s), enter the logical volume on
      which the filesystem resides. The mount points must exist for the 
      filesystems to be mounted. For example, the following /etc/fstab.iscsi
      entries will mount the two iSCSI devices specified (sda and sdb);

      *************************************************************************
      #device                   mount      FS      mount      backup      fsck 
      #to mount                 point      type    options    frequency    pass
      /dev/sda                 /mnt/t0    ext2    defaults      0          0
      /dev/sdb                 /mnt/t1    ext2    defaults      0          0
      *************************************************************************

   3. Upon a system restart, the iSCSI startup script invokes the
      iscsi-mountall script will try to mount iSCSI devices listed in
      /etc/fstab.iscsi file. iscsi-mountall tries to mount the iSCSI devices
      for "NUM_RETRIES" (default value 10) number of times, at an interval of
      "SLEEP_INTERVAL" seconds (default value 1) between each attempt, giving
      the driver the time to establish a connection with an iSCSI target.
      The value of these parameters can be changed in the iscsi-mountall script
      if the devices are not getting configured in the system within the
      default time periods.

  Due to variable network delays, targets may not always become available in the
  same order from one boot to the next. Thus, the order in which iSCSI devices
  are mounted may vary and may not match the order the devices are listed in
  /etc/fstab.iscsi You should not assume mounts of iSCSI devices will occur in
  any particular order.

  Because of the variability of the mapping between SCSI device nodes
  and iSCSI targets, it is always recommended to either mount the iSCSI
  device nodes which have persistent device names, mount filesystem UUIDs
  or labels (see man pages for mke2fs, mount, and fstab), or use logical
  volume management (see Linux LVM) to avoid mounting the wrong device due
  to device name changes resulting from iSCSI target configuration changes
  or network delays.


------------
LOG MESSAGES
------------

  The iSCSI driver contains components in the kernel and user level.
  The log messages from these components are sent to syslog. Based on the
  syslogd configuration on the Linux host, the messages will be sent to the
  appropriate destination. For example, if /etc/syslog.conf has the following
  entry:
  
     *.info /var/log/messages

  then all log messages of level 'info' or higher will be sent to
  /var/log/messages.
  
  If /etc/syslog.conf has the following entry:

    *.info;kern.none  /var/log/messages

  then all log messages (except kernel messages) of level info or higher
  will be sent to /var/log/messages.

  If /etc/syslog.conf has the following entry:

    kern.* /dev/console

  then all kernel messages will be sent to the console.

  All messages from the iSCSI driver when loading the iSCSI kernel 
  module will be placed in /var/log/iscsi.log.

  The user can also use dmesg(8) to view the log messages.


------------------------------
DYNAMIC DRIVER RECONFIGURATION
------------------------------

  Configuration changes can be made to the iSCSI driver without having to stop
  it or reboot the host system. To dynamically change the configuration of the
  driver, follow the steps below:

   1. Edit /etc/iscsi.conf with the desired configuration changes.

   2. Enter the following command:

         /etc/init.d/iscsi reload 

      This will cause the iSCSI daemon to re-read /etc/iscsi.conf file and to
      create any new DiscoveryAddress connections it finds. Those discovery
      sessions will then discover targets and create new target connections.

  Note that any configuration changes will not affect existing target sessions.
  For example, removal of a DiscoveryAddress entry from /etc/iscsi.conf
  will not cause the removal of sessions to targets discovered through this 
  DiscoveryAddress, but it will cause the removal of the discovery session 
  corresponding to the deleted DiscoveryAddress.


------------------------
ASYNC EVENT NOTIFICATION
------------------------

  Changes occuring at the iSCSI target need to be communicated to the initiator
  as asynchronous messages after negotiating the key "SendAsyncText". The async
  events will be notified to the initiator in the following scenario.
  These events are sent over the discovery session.

  1. PortalOnline - Indicates that a portal (IP Address and TCP port) has been
     added, so target sessions can be established on this portal.

  2. PortalOffline - Indicates the initiator that a portal (IP Address and TCP
     port) has been removed, hence if the initiator loses connectivity to this
     address and port, it should not be retried.

  3. TargetOnline - Notifies the initiator that a new target may be
     available for use and the initiator can try to establish connection to
     this target.

  4. TargetOffline - Notifies the initiator that a target has become
     unavailable. If the initiator loses target connectivity, it should not
     retry connection if any further connection attempt is denied.

----------------
iSCSI HBA STATUS
----------------

  The directory '/sys/class/scsi_host/' contains all registered SCSI HBA
  entries and corresponding sysfs files to read/write any host specific
  attributes. All iSCSI host entries will be present in any of hostX
  directory, where X can be (0 to 2^32 - 1) number of allowable host ids.

  The proc_name attribute can be used to identify the iSCSI host under
  sysfs.
  # more /sys/class/scsi_host/hostX/proc_name
  iscsi-sfnet

  The following file can be used to request shutdown of an iscsi session.

  shutdown - stop the iSCSI driver.
  # echo "shutdown" > /sys/class/scsi_host/hostX/shutdown


----------------------------
USING MULTIPATH I/O SOFTWARE
----------------------------
  Some iSCSI target devices have multiple Ethernet ports. Those systems may be
  configured to allow iSCSI target access via multiple paths. When the iSCSI
  driver discovers targets through a multi-port device, it also discovers all
  the IP addresses that can be used to reach each of those targets. 
  It establishes a session using each of the IP addresses through which the
  target can be reached. It exports all the available paths to the user.

  Multipath drivers exploit this feature to provide better performance
  (due to load sharing) and high availability (failover of I/O if one of the
  path goes bad).

  It may be necessary to modify the configuration of the driver to allow 
  the multi-pathing software to operate more efficiently. If you are using
  a multipath I/O application, you may need to set the "ConnFailTimeout" 
  parameter of the iSCSI driver to a smaller value so that SCSI commands will
  fail more quickly when an iSCSI network connection drops allowing the
  multipath application to try a different path for access to the storage
  device.

  Device mapper, a multipath software can be obtained from the 
  following URL:
  http://sources.redhat.com/dm/

------------------------------------
MAKING STORAGE CONFIGURATION CHANGES
------------------------------------

  Making changes to your storage configuration, including adding or
  removing targets or LUNs, remapping targets, or modifying target
  access, may change how the devices are presented to the host operating
  system. This may require corresponding changes in the iSCSI driver
  configuration and /etc/fstab.iscsi file.

  It is important to understand the ramifications of SCSI routing