Installation notes for Linux iSCSI driver

 Copyright (C) 2001 Cisco Systems, Inc. (http://www.cisco.com)
 maintained by linux-iscsi@cisco.com

 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.

 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
--------

  Overview
  Before You Begin
  Using
  Mounting Filesystems
  Unmounting Filesystems
  Maintenance
  Removal

--------
OVERVIEW
--------

  The Linux iSCSI driver acts as an iSCSI protocol initiator to
  transport SCSI requests and responses over an IP network between the
  client and an iSCSI-enabled target device such as a Cisco SN 5420
  storage router. The iSCSI protocol is an IETF-defined protocol for
  IP storage. For more information about the iSCSI protocol, refer to
  the IETF standards for IP storage at http://www.ietf.org.

  Architecturally, the iSCSI driver combines with the client
  TCP/IP stack, network drivers, and NICs to provide the same
  functions as a SCSI adapter driver with an HBA. (See Figure 1.)


  FIGURE  1  Linux iSCSI Driver Architecture

    +----------------------+                      +-----------+
    |     iSCSI driver     |                      |           |
    +----------------------+                      |   SCSI    |
    |        TCP/IP        |                      |  adapter  |
    +----------------------+                      |   driver  |
    |   Network drivers    |                      |           |
    +----------------------+                      +-----------+
               |                                        |
         +-----------+                            +-----------+
         |    NIC    |                            |    HBA    |
         +-----------+                            +-----------+
               |                                        |
              _|_                                      _|_
            _(   )_                             Local (___)
          _(  IP   )_                           SCSI  (___)
         (_ network _)                          disk  (___)
           (_     _)                                  (___)
             (_ _)
               |
      +------------------+
      |  iSCSI interface |
      +------------------+
               |
      +------------------+
      |     Storage      |
      +------------------+
      |  ___  ___  ___   |
      | (___)(___)(___)  |
      | (___)(___)(___)  |
      | (___)(___)(___)  |
      | (___)(___)(___)  |
      +------------------+

----------------
BEFORE YOU BEGIN
----------------

  To attach to storage, you must have an iSCSI-capable device
  connected to your network. The iSCSI device may be on the same LAN
  as your Linux host, or the iSCSI traffic may be routed using normal
  IP routing methods. The Linux iSCSI driver currently provides IP
  access to a maximum of eight remote SCSI targets, with each target
  capable of supporting 32 LUNs.

  The iSCSI client drivers, README files, and example configuration files
  are available on the Linux-ISCSI homepage at:

    http://linux-iscsi.sourceforge.com

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

-----
USING
-----

  1. Update /etc/NuScsiTcp.conf to include the IP addresses for your
     iSCSI targets. A sample configuration file might include entries
     like this:

       TargetIpAddr=192.168.10.94
       Target,Lun=0,0

     Please see the included configuration file for a more detailed
     description of the entries.

  2. Manually start iSCSI services to test your configuration. Run:

       service iscsi start

     Once the Linux iSCSI driver is activated, the client will proceed
     with a discovery process for iSCSI storage devices as follows:

     - The iSCSI daemon requests available iSCSI targets from the
       canonical iSCSI target.
     - The client establishes connections to the targets.
     - The client queries targets for device information.
     - The client creates a mapping from SCSI device nodes to iSCSI targets.

     Daemon diagnostic information will be placed in /var/log/iscsi.log. 
     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
       scsi singledevice 0 0 0 1

     Normal disk commands like fdisk, mkfs, and fsck will work on the
     iSCSI devices like a local drive.

     /proc/scsi/iscsi will contain a file (the controller number) that
     contains information about the iSCSI devices.

     To manually stop the iSCSI driver enter:

       service iscsi start

  3. List your iSCSI partitions in /etc/fstab with the _netdev option.

  4. Optionally, change the "/proc/sys/net/core" values to increase
     the TCP window for the iSCSI connection. Normally, the larger the
     window the better the performance. Modify these values prior to
     starting the iSCSI daemon. Modify the /etc/sysctl.conf file,
     for example:

       net.core.wmem_default = 1048576
       net.core.wmem_max = 1048576
       net.core.rmem_default = 1048576
       net.core.rmem_max = 1048576

--------------------
MOUNTING FILESYSTEMS
--------------------

  Because the Linux boot process normally mounts filesystems listed in
  /etc/fstab before the network is configured, you need to add the
  _netdev option to each filesystem on an iSCSI device.
  
  It is recommended to use filesystem UUIDs or labels (see man pages
  for mke2fs, mount, and fstab) to avoid the configuration problems
  associated with device name changes resulting from configuration
  changes.

----------------------
UNMOUNTING FILESYSTEMS
----------------------
	
  It is very important to unmount all filesystems on iSCSI devices
  before the iSCSI driver stops.  If the iSCSI driver stops while 
  iSCSI devices are mounted, buffered writes may not be committed to 
  disk and filesystem corruption may occur.

  For this reason, the system automatically umounts all file
  systems with the _netdev option before the iSCSI driver
  stops and before the network is stopped.
	
  Since Linux will not unmount filesystems that are being used by a
  running process, before iSCSI devices can be unmounted, any
  processes using those devices must be stopped (see fuser(1)).

  To avoid filesystem corruption, the netfs shutdown script will
  automatically kill all processes using _netdev devices in /etc/fstab,
  first by sending them SIGTERM, and then by sending any remaining
  processes SIGKILL. It will then unmount all iSCSI filesystems and
  kill the iSCSI daemon, terminating all connections to iSCSI devices.

-----------
MAINTENANCE
-----------

  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 client. This
  may require corresponding changes in your iSCSI driver configuration
  and /etc/fstab.

  For example, adding a new storage volume may change the order of
  device discovery, thus changing the operating system's numbering
  of existing devices. Applications running on the client may
  require modification to appropriately access the current drives.

  Note: if a client's iSCSI configuration file contains an IP address
  of a canonical iSCSI target that does not exist, or has no targets
  available for the client, the iSCSI driver will not complete a login
  and will not discover targets associated with any iSCSI targets.

  It is recommended to use filesystem UUIDs or labels (see man pages
  for mke2fs, mount, and fstab) to avoid the configuration problems
  associated with changing device names.

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

  1. Unmount any file systems and stop any applications using iSCSI
     devices.

  2. Stop the iSCSI driver.

       service iscsi stop

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

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

  5. Restart the iSCSI driver or, optionally, reboot the client.

       service iscsi start

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


-------
REMOVAL
-------

  Run rpm -e iscsi
