
 Installation notes for iSCSI Driver Version 4.0.1 for Linux

 maintained by linux-iscsi-devel@lists.sourceforge.net

 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 a Cisco SN
  5400 Series 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 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 _)          
           (_     _)               |             (_     _)            
             (_ _)                 |               (_ _)              
               |                   |                 |

      +------------------+         |                 |
      |  SN 5400 Series  |         |                 |
      |  Storage Router  |         |                 |
      +------------------+         |                 |
               |                   |                 |
      +------------------+         |       +------------------+
      |     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 SN 5400 Series 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 driver discovery daemon process looks up each discovered target
      in the /var/lib/iscsi/bindings file. If an entry exists in the file for 
      the target, the corresponding SCSI target ID is assigned to the target. 
      If no entry exists for the target, the smallest available SCSI target ID
      is assigned and an entry is written to the /var/lib/iscsi/bindings file. 
      The driver then sends a login request to the iSCSI target.

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

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

   6. The targets respond with the device information.

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

The iSCSI driver provides following features:

 1. Header and Data Digests
 2. 2-WAY CHAP Authentication
 3. Target Portal Failover
 4. Persistent Target Binding
 5. InitialR2T
 6. Multipathing
 7. Sendtargets and SLP Discovery mechanism
 8. Dynamic Target Configuration
 9. Async Event notification
10. Immediate Data Support
11. Error recovery Level 0
12. iSCSI Network Boot

Following features are planned for future release:

 1. Multiple connections
 2. Error Recovery Level 1
 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 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
    Installation Procedure
    Removal Procedure
    Driver Upgrade Procedure
    Kernel Upgrade Procedure


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

  The iSCSI Driver for Linux requires a host running the Linux operating
  system with a kernel version of 2.6.0 or later. 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.


  There are some issues with the Linux kernel code that can cause
  problems when using SCSI devices (including iSCSI devices). Linux
  kernels released after this date may or may not have fixed these
  problems.

   - All Linux kernels released on or before Feb 4, 2002 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.

     The iSCSI driver attempts to avoid this problem by retrying disk
     commands for many types of failures. The MinDiskCommandTimeout
     defaults to "infinite", which disables the command timeout,
     allowing commands to be retried forever if the storage device is
     unreachable or unresponsive.

   - 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 encounters trasmission problems
     under heavy load and may cause system panic.

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

     1. CONFIG_SCSI
     2. CONFIG_CRYPTO
     3. CONFIG_CRYPTO_MD5

  The iSCSI device node creation requires using udev package version 8.
  The package can be downloaded from the following URL.

          http://kernel.org/pub/linux/utils/kernel/hotplug/udev-008.tar.gz
     
  Hotplug program is a pre-requisite for udev to create iSCSI devices.
  If hotplug package is currently not installed, it can be obtained
  from the linux-hotplug project on sourceforge.

          http://linux-hotplug.sourceforge.net

  Sysfsutils package need to be installed prior to installing iSCSI driver.
  This package provides sysfs library and headers which are used by
  iSCSI driver. The package can be obtained from the linux-diag project on
  sourceforge.
 
          http://linux-diag.sourceforge.net

  The iSCSI Driver Version 4.0 for Linux is compatible with SN 5400 Series
  Storage Routers running software version 3.x or greater. It is not
  compatible with SN 5400 Series Storage Routers running software versions
  1.x or 2.x.


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

  Before you begin, make sure that your Cisco SN 5400 Series Storage Router or
  other 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 detail procedures on
  removing the driver.

  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). 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.tgz
         cd linux-iscsi-4.0

      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 SN 5400 Series
      system 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 SN 5400 Series system
      IP addresses and other required driver parameters. Refer to the Editing
      /etc/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.


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

  1. While logged in as root, unmount all iSCSI devices and 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. Back up one directory level and delete the source code by entering:

        cd ..
        rm -rf linux-iscsi-<ver>


------------------------
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
    Target Portal Failover
    iSCSI HBA Status
    Using Multipath I/O Software
    Making Storage Configuration Changes
    Target and LUN Discovery Limits
    Persistent Target Binding
    Service Location Protocol (SLP)
    Target Authentication
    Editing The iscsi.conf File
    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
  ********************************************************************

  The directory "/sys/class/scsi_host/iscsi/"  will contain
  a file 'print_info' that displays information about the iSCSI devices.

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

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

  To provide a more reliable namespace, the iSCSI driver uses the 'udev'
  package to create persistent device naming for iSCSI devices.

  The iSCSI devices will be found under /udev directory in the format
  iscsib<bus_id>t<target_id>l<lun_id>disk.

  E.g:- /udev/iscsib0t0l0disk
        /udev/iscsib0t0l0part1
        /udev/iscsib0t0l0part2

  In the above example,

  bus_id -> 0
  target_id -> 0
  lun_id -> 0

  part1, part2 represent the iSCSI device partitions currently available for
  the device. 


-------------------------
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 (iscsib0t0l0disk and
      iscsib0t0l2part1):

      *************************************************************************
      #device                   mount      FS      mount      backup      fsck 
      #to mount                 point      type    options    frequency    pass
      /udev/iscsib0t0l0disk     /mnt/t0    ext2    defaults      0          0
      /udev/iscsib0t0l2part1    /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 created under /udev, 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 or this portal
  can be used for future failover.

  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.


----------------------
TARGET PORTAL FAILOVER
----------------------

  Some SN 5400 Series Storage Routers have multiple Gigabit 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 SN 5400
  Series system, it also discovers all the IP addresses that can be used to
  reach each of those targets. 

  When an existing target connection fails, the iSCSI driver will attempt to
  connect to that target using the next available IP address. You can also
  choose a preferred portal to which the iSCSI driver should attempt to connect
  to when the iSCSI driver is started or whenever automatic portal failover
  occurs. This is significant in a situation when you want the connection
  to the targets to be made through a faster network portal (for example, when
  the I/Os are going through a Gigabit Ethernet interface and you do not
  prefer the connection to failover to a slower network interface).

  The preference for portal failover can be specified through the 
  "PreferredPortal" or "PreferredSubnet" parameter in /etc/iscsi.conf.
  If this preference is set, then on any subsequent failover the driver will
  first try to failover to the preferred portal or preferred subnet whichever
  is specified in the conf file. If both preferred portal and preferred subnet
  entries are present in the conf file then the preferred portal takes
  precedence. If the preferred portal or preferred subnet is unreachable,
  then the driver will continuously rotate through the list of available 
  portals until it finds one that is active.

  The Portal Failover feature is turned on by default and the whole process of
  failover occurs automatically. You can chose to turn off portal failover
  by disabling the portal failover parameter in /etc/iscsi.conf.

  If a target advertises more than one network portal, you can manually
  switch portals by writing to the HBA's file under the path
  "/sys/class/scsi_host/iscsi/" called 'failover'.

  For example, if a target advertises two network portals:

      10.77.13.248:3260 and 192.168.250.248:3260.

  If the device is configured with targetId as 0, busId as 0, HBA's host
  number is 3 and you want to switch the target from 
  10.77.13.248 to 192.169.250.248, use the following command:

      echo "0 0 192.168.250.248" >
              /sys/class/scsi_host/iscsi/failover

  Where the syntax is:

      echo "<busId> <targetId> <IP address>" >
      /sys/class/scsi_host/iscsi/failover

  The host system must have multiple network interfaces to effectively
  utilize this failover feature.


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

  The directory '/sys/class/scsi_host/iscsi/' contains sysfs files
  to read/write any iSCSI attributes.

  The following files can be used to send any input to iSCSI driver.
 
  log - can be used to enable/disable log messages.
  failover - can be used to perform portal failover.
  shutdown - can be invoked to stop the iSCSI driver.

  Many other attributes can be selected by turning on the debug option
  "ATTR_DEBUG" while building the iSCSI driver.

  The sysfs file below will display the iSCSI driver information.

  print_info - displays the iSCSI device/connection details.

  It will show the driver's version number, followed by a list all
  iSCSI targets and LUNs the driver has found and can use.

  Each line will show the iSCSI bus number, target id number, and
  logical unit number, as well as the IP address, TCP port, and
  iSCSI TargetName.  If an iSCSI session exists, but no LUNs have
  yet been found for a target, the LUN number field will contain a
  question mark.  If a TCP connection is not currently established,
  the IP address and port number will both appear as question marks.


----------------------------
USING MULTIPATH I/O SOFTWARE
----------------------------

  If a third-party multipath I/O software application is being used in
  conjunction with the iSCSI driver (e.g., HP Secure Path), 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 to for access to the
  storage device. Also, you may need to set the "MaxDiskCommandTimeout"
  to a smaller value (e.g., 5 or 10 seconds), so that SCSI commands to
  unreachable or unresponsive devices will fail more quickly and the
  multipath software will know to try a different path to the storage device. 

  Multipath support in the iSCSI driver can be turned on by setting
  Multipath=<"yes" or "portal" or "portalgroup"> in /etc/iscsi.conf.
  If Multipath=<"yes" or "portal">, then the discovered targets that
  are configured to allow access via multiple paths will have a separate
  iSCSI session created for each path (i.e., iSCSI portal). The target
  portal failover feature should not be used if Multipath=<"yes" or "portal">
  since multiple sessions will be established with all available paths. 


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

  It is important to understand the ramifications of SCSI routing
  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 assigned by the iSCSI initiator driver
  whereas the lun ID is assigned by the iSCSI target. The driver provides
  access to a maximum of 256 bus IDs with each bus supporting 256 targets
  and each target capable of supporting 256 LUNs. Any discovered iSCSI
  device will be allocated the next available target ID on bus 0.
  If a target ID > 256 on bus 0, then a next available target ID on bus 1
  will be allocated. If a bus ID > 256 and LUN ID > 256 it will be ignored
  by the driver and will not be configured in the system.


-------------------------
PERSISTENT TARGET BINDING
-------------------------

  This feature ensures that the same iSCSI bus and target id number are used 
  for every iSCSI session to a particular iSCSI TargetName, and a Linux SCSI
  target always maps to the same physical storage device from one reboot to 
  the next.

  This feature ensures that the SCSI numbers in the device creation described
  above will always map to the same iSCSI target.

  Note that because of the way Linux dynamically allocates SCSI device nodes 
  as SCSI devices are found, the driver does not and cannot ensure that any
  particular SCSI device node (e.g., /dev/sda) will always map to the same 
  iSCSI TargetName. The udev mechanism described in the section on Device
  Names are intended to provide a persistent device mapping for use by
  applications and fstab files, and should be used instead of direct
  references to particular SCSI device nodes.  

  The file /var/lib/iscsi/bindings is used by the iSCSI daemon to store
  bindings of iSCSI target names to SCSI target ID's. If the file doesn't exist,
  it will be created when the driver is started. If an entry exists for a 
  discovered target, the Linux target ID from the entry is assigned to the 
  target. If no entry exists for a discovered target, an entry is written to 
  the file. Each line of the file contains the following fields:

      BusId  TargetId  TargetName

  An example file would be:

  ***************************************************************************
        0       0       iqn.1987-05.com.cisco:00.583ef6c43e5f.disk0
        0       1       iqn.1987-05.com.cisco:00.dfea668e3d80.disk1
        0       2       iqn.1987-05.com.cisco:00.e8da23d93472.disk2
  ***************************************************************************

  Note that the /var/lib/iscsi/bindings file will permanently contain entries
  for all iSCSI targets ever logged into from this host. If a target is
  no longer available to a host you can manually edit the file and remove
  entries so the obsolete target no longer consumes a SCSI target ID.
  If you know the iSCSI target name of a target in advance, and you want
  it to be assigned a particular SCSI target ID, you can add an entry
  manually. You should stop the iSCSI driver before editing the
  /var/lib/iscsi/bindings file. Be careful to keep an entire entry on a single
  line, with only whitespace characters between the three fields. Do not
  use a target ID number that already exists in the file.

  *****************************************************************************
  NOTE: iSCSI driver versions prior to 3.3 used the file /var/iscsi/bindings
        or /etc/iscsi.bindings instead of /var/lib/iscsi/bindings. The first
        time you start the new driver version, it will change the location and
        the name of the bindings file to /var/lib/iscsi/bindings
  *****************************************************************************


-------------------------------
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. Consult the appropriate SN 5400 Software
  Configuration Guide for information about configuring SLP on an SN 5400
  Series system. 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
  *****************************************************************************


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

  The CHAP authentication mechanism provides for two way authentication between
  the target and the initiator. The authentication feature on the SN 5400
  system has to be enabled to make use of this feature. The username and
  password for both initiator side and target side authentication needs to be
  listed in /etc/iscsi.conf. The username and password can be specified as
  global values or can be made specific to the 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
      eg:  TargetName = iqn.1987-05.com.cisco:00.0d1d898e8d66.t0
    - TargetIPAddress = Target name with format a.b.c.d/n
    - Subnet = Network portal IP address with format a.b.c.d/n or a.b.c.d&hex
    - Address = Network portal IP address with format a.b.c.d/32

  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.

    - Username = CHAP username used for initiator authentication by the target.
    - OutgoingUsername = < same as above >
    - Password = CHAP password used for initiator authentication by the target.
    - OutgoingPassword = < same as above >
    - IncomingUsername = CHAP username for target authentication by the initiato
r.
    - IncomingPassword = CHAP password for target authentication by the initiato
r.
    - HeaderDigest = Type of header digest support the initiator is requesting
                     of the target.
    - DataDigest = Type of data digest support the initiator is requesting of
                   the target.
    - PortalFailover = Enabling/disabling of target portal failover feature.
    - PreferredSubnet = IP address of the subnet that should be used for a
                        portal failover.
    - PreferredPortal = IP address of the portal that should be used for a
                        portal failover.
    - Multipath = Enabling/disabling of multipathing feature.
    - 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 queries sent out.
    - LoginTimeout = Time interval to wait for a response to a login request to
                     be received from a target before failing a connection
                     attempt.
    - AuthTimeout = Time interval to wait for a response to a login request
                    containing authentication information to be received from a
                    target before failing a connection attempt.
    - IdleTimeout = Time interval to wait on a connection with no traffic before
                    sending out a ping.
    - PingTimeout = Time interval to wait for a ping response after a ping is
                    sent before failing a connection.
    - ConnFailTimeout = Time interval to wait before failing SCSI commands back
                        to an application for unsuccessful commands.
    - AbortTimeout = Time interval to wait for a abort command to complete
                     before declaring the abort command failed.
    - ResetTimeout = Time interval to wait for a reset command to complete
                     before declaring the reset command failed.
    - LUNs = A Lun number or range of luns to be configured per TargetName
             entry or for the list of all desired targets.
    - MinDiskCommandTimeout = Minimum time to wait before failing commands to
                              a target disk device.
    - MaxDiskCommandTimeout = Maximum time to wait before failing commands to
                              a target disk device.
    - InitialR2T = Enabling/disabling of R2T flow control with the target.
    - ImmediateData = Enabling/disabling the sending of unsolicited data burst
                      with the iSCSI command PDU.

    - MaxRecvDataSegmentLength = Maximum number of bytes that the initiator can
                                 receive in an iSCSI PDU.
    - FirstBurstLength = Maximum number of bytes of unsolicited data the
                         initiator is allowed to send.
    - MaxBurstLength = Maximum number of bytes for the SCSI payload negotiated
                       by initiator.
    - TCPWindowSize = Maximum number of bytes that can be sent over a TCP
                      connection by the initiator before receiving an
                      acknowledgement from the target.
    - Continuous = Enabling/disabling the discovery session to be kept alive.
    - SendAsyncText = Enable/disable sending Async event messages from the
      target.
  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.


----------------------------
iSCSI COMMANDS AND UTILITIES
----------------------------

  This section gives a description of all the commands and utilities available
  with the iSCSI driver.

  - "iscsi-ls" lists information about the iSCSI devices available to the
    driver. Please refer to the man page for more information.


-------------------
DRIVER FILE LISTING
-------------------

  The following files are present on the system after the successful
  installation of iSCSI driver:

     /etc/init.d/iscsi
     /etc/iscsi.conf
     /etc/initiatorname.iscsi
     /sbin/iscsi-mountall
     /sbin/iscsid
     /sbin/iscsi-device
     /sbin/iscsi-iname
     /sbin/iscsi-ls
     /sbin/iscsi-id
     /sbin/iscsi-umountall
     /man/man5/iscsi.conf.5
     /man/man5/iscsi.bindings.5
     /man/man1/iscsi-ls.1
     /man/man8/iscsid.8
     /var/lib/iscsi/bindings
     /lib/modules/<uname -r>/misc/iscsi.ko


===============================================================================
GPL LICENSE
===============================================================================
GNU GENERAL PUBLIC LICENSE
Version 2, June 1991 

Copyright (C) 1989, 1991 Free Software Foundation, Inc.  
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble
The licenses for most software are designed to take away your freedom to
share and change it. By contrast, the GNU General Public License is intended
to guarantee your freedom to share and change free software--to make sure
the software is free for all its users. This General Public License applies
to most of the Free Software Foundation's software and to any other program
whose authors commit to using it. (Some other Free Software Foundation
software is covered by the GNU Library General Public License instead.) You
can apply it to your programs, too. 

When we speak of free software, we are referring to freedom, not price. Our
General Public Licenses are designed to make sure that you have the freedom
to distribute copies of free software (and charge for this service if you
wish), that you receive source code or can get it if you want it, that you
can change the software or use pieces of it in new free programs; and that
you know you can do these things. 

To protect your rights, we need to make restrictions that forbid anyone to
deny you these rights or to ask you to surrender the rights. These
restrictions translate to certain responsibilities for you if you distribute
copies of the software, or if you modify it. 

For example, if you distribute copies of such a program, whether gratis or
for a fee, you must give the recipients all the rights that you have. You
must make sure that they, too, receive or can get the source code. And you
must show them these terms so they know their rights. 

We protect your rights with two steps: (1) copyright the software, and (2)
offer you this license which gives you legal permission to copy, distribute
and/or modify the software. 

Also, for each author's protection and ours, we want to make certain that
everyone understands that there is no warranty for this free software. If
the software is modified by someone else and passed on, we want its
recipients to know that what they have is not the original, so that any
problems introduced by others will not reflect on the original authors'
reputations. 

Finally, any free program is threatened constantly by software patents. We
wish to avoid the danger that redistributors of a free program will
individually obtain patent licenses, in effect making the program
proprietary. To prevent this, we have made it clear that any patent must be
licensed for everyone's free use or not licensed at all. 

The precise terms and conditions for copying, distribution and modification
follow. 

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License applies to any program or other work which contains a notice
placed by the copyright holder saying it may be distributed under the terms
of this General Public License. The "Program", below, refers to any such
program or work, and a "work based on the Program" means either the Program
or any derivative work under copyright law: that is to say, a work containing
the Program or a portion of it, either verbatim or with modifications and/or
translated into another language. (Hereinafter, translation is included
without limitation in the term "modification".) Each licensee is addressed
as "you". 

Activities other than copying, distribution and modification are not covered
by this License; they are outside its scope. The act of running the Program
is not restricted, and the output from the Program is covered only if its
contents constitute a work based on the Program (independent of having been
made by running the Program). Whether that is true depends on what the
Program does. 

1. You may copy and distribute verbatim copies of the Program's source code
as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
disclaimer of warranty; keep intact all the notices that refer to this
License and to the absence of any warranty; and give any other recipients
of the Program a copy of this License along with the Program. 

You may charge a fee for the physical act of transferring a copy, and you
may at your option offer warranty protection in exchange for a fee. 

2. You may modify your copy or copies of the Program or any portion of it, 
thus forming a work based on the Program, and copy and distribute such
modifications or work under the terms of Section 1 above, provided that you
also meet all of these conditions: 


a) You must cause the modified files to carry prominent notices stating that
you changed the files and the date of any change. 

b) You must cause any work that you distribute or publish, that in whole or
in part contains or is derived from the Program or any part thereof, to be
licensed as a whole at no charge to all third parties under the terms of
this License. 

c) If the modified program normally reads commands interactively when run,
you must cause it, when started running for such interactive use in the most
ordinary way, to print or display an announcement including an appropriate
copyright notice and a notice that there is no warranty (or else, saying that
you provide a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this License.
(Exception: if the Program itself is interactive but does not normally print
such an announcement, your work based on the Program is not required to print
an announcement.) 
These requirements apply to the modified work as a whole. If identifiable
sections of that work are not derived from the Program, and can be reasonably
considered independent and separate works in themselves, then this License,
and its terms, do not apply to those sections when you distribute them as
separate works. But when you distribute the same sections as part of a whole
which is a work based on the Program, the distribution of the whole must be
on the terms of this License, whose permissions for other licensees extend to
the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your
rights to work written entirely by you; rather, the intent is to exercise the
right to control the distribution of derivative or collective works based on
the Program. 

In addition, mere aggregation of another work not based on the Program with
the Program (or with a work based on the Program) on a volume of a storage
or distribution medium does not bring the other work under the scope of this
License. 

3. You may copy and distribute the Program (or a work based on it, under
Section 2) in object code or executable form under the terms of Sections 1
and 2 above provided that you also do one of the following: 

a) Accompany it with the complete corresponding machine-readable source code,
which must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange; or, 

b) Accompany it with a written offer, valid for at least three years, to give
any third party, for a charge no more than yourram except as expressly
provided under this License. Any attempt otherwise to copy, modify,
sublicense or distribute the Program is void, and will automatically
terminate your rights under this License. However, parties who have received
copies, or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance. 

5. You are not required to accept this License, since you have not signed it.
However, nothing else grants you permission to modify or distribute the
Program or its derivative works. These actions are prohibited by law if you
do not accept this License. Therefore, by modifying or distributing the
Program (or any work based on the Program), you indicate your acceptance of
this License to do so, and all its terms and conditions for copying,
distributing or modifying the Program or works based on it. 

6. Each time you redistribute the Program (or any work based on the Program),
the recipient automatically receives a license from the originaices. Many
people have made generous contributions to the wide range of software
distributed through that system in reliance on consistent application of
that system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot impose
that choice. 

This section is intended to make thoroughly clear what is believed to be a
consequence of the rest of this License. 

8. If the distribution and/or use of the Program is restricted in certain
countries either by patents or by copyrighted interfaces, the original
copyright holder who places the Program under this License may add an
explicit geographical distribution limitation excluding those countries, so
that distribution is permitted only in or among countries not thus excluded.
In such case, this License incorporates the limitation as if written in the
body of this License. 

9. The Free Software Foundation may publish revised and/or new versions of
the General Public License from time to tgenerally. 

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE
STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE
PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,
YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE
OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR
DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR
A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH
HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 


END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest possible
use to the public, the best way to achieve this is to make it free software
which everyone can redistribute and change under these terms. 

To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the "copyright"
line and a pointer to where the full notice is found. 

one line to give the program's name and an idea of what it does.
Copyright (C) yyyy  name of author

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.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Also add information on how to contact you by electronic and paper mail. 

If the program is interactive, make it output a short notice like this when
it starts in an interactive mode: 

Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, the commands you use may be
called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program. 

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here is a sample; alter the names: 

Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs. If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library. If this is what you want to do, use the GNU Library General Public
License instead of this License. 
