iscsi readme
-----------------------------------------------------------------------------
*****************************************************************************
Installation and Design Notes for iSCSI Driver Version for Linux
*****************************************************************************
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version. Please see the "GPL License" section
for more information on this.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
See the file COPYING included with this distribution for more
details.
===============================================================================
CONTENTS
===============================================================================
Product Overview
Product Features
Before Installing The Driver
Installing And Removing The Driver
Configuring And Using The Driver
GPL License
===============================================================================
PRODUCT OVERVIEW
===============================================================================
The iSCSI Driver provides a host with the ability to access storage
through an IP network. The driver uses the iSCSI protocol to transport SCSI
requests and responses over an IP network between the host and an iSCSI target
device. The iSCSI protocol is an IETF-defined protocol for IP storage. For
more information about the IETF standards, refer to .
For more information about the iSCSI protocol, refer to the RFC 3720 at
Architecturally, the iSCSI driver combines with the host's TCP/IP stack,
network drivers, and Network Interface Card (NIC) to provide the same
functions as a SCSI or a Fibre Channel (FC) adapter driver with a Host Bus
Adapter (HBA) (see Figure 1).
Figure 1 - iSCSI Driver Architecture
iSCSI Access To Storage | SCSI or FC Access to Storage
====================================================================
|
Host applications | Host applications
|
=======|===========|===============================|================
| | | |
| +------------+ | |
| | SCSI | | |
| | driver | | |
| +------------+ | +-----------+
| | iSCSI | | | |
| | driver | | | SCSI |
+---------+------------+ | | or FC |
| TCP/IP | | | adapter |
+----------------------+ | | driver |
| Network drivers | | | |
+----------------------+ | +-----------+
| | |
=============|=====================================|================
| | |
+-----------+ | +-----------+
| NIC | | | HBA |
+-----------+ | +-----------+
| | |
=============|=====================================|================
_|_ | _|_
_( )_ | _( )_
_( IP )_ | _( FC )_
(_ network _) | (_ or SCSI _)
(_ _) | (_ _)
(_ _) | (_ _)
| | |
+------------------+ | |
| Storage Router | | |
| or Gateway | | |
+------------------+ | |
| | |
+------------------+ | +------------------+
| Storage | | | Storage |
+------------------+ | +------------------+
| (___)(___)(___) | | | (___)(___)(___) |
| (___)(___)(___) | | | (___)(___)(___) |
| (___)(___)(___) | | | (___)(___)(___) |
| (___)(___)(___) | | | (___)(___)(___) |
+------------------+ | +------------------+
|
====================================================================
The iSCSI driver provides a transport for SCSI requests and responses to
storage devices via an IP network instead of using a direct attached SCSI bus
channel or an FC connection. The Storage Router, in turn, transports these
SCSI requests and responses received via the IP network between it and the
storage devices attached to it.
Once the iSCSI driver is installed, the host will proceed with a
discovery process for storage devices as follows:
1. The iSCSI driver requests available targets through SLP or SendTargets
discovery mechanism as configured in the /etc/iscsi.conf configuration
file.
2. Each iSCSI target sends available iSCSI target names to the iSCSI driver.
3. The iSCSI 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
===============================================================================
A list of the major features supported by the iSCSI driver are shown below.
A more detailed description of each these features is described in later
sections of this document and with the associated man pages.
1. Header and data digest support
2. Two way CHAP authentication
3. Target portal failover feature (i.e., basic multi-pathing support
provided by the driver)
4. Persistent target binding between re-boots
5. R2T flow control support with a target
6. Third party multi-path support
7. Sendtargets and SLP discovery mechanisms
8. Dynamic target discovery
9. Async event notifications for portal and target changes
10. Immediate Data Support
11. Error recovery level 0
12. iSCSI network boot support
13. Dynamic driver reconfiguration
14. Auto-mounting for iSCSI filesystems after a reboot
No new major features are currently planned to be added to the 3.x driver.
All new feature development work is being done on the 4.x iSCSI driver.
===============================================================================
BEFORE INSTALLING THE DRIVER
===============================================================================
The iSCSI driver, README file, and example configuration files are
available on the Linux-iSCSI project homepage at:
In addition, at the website you can get information about the availability
of new drivers, updated drivers, driver compatibility, and other relevant
information.
===============================================================================
INSTALLING AND REMOVING THE DRIVER
===============================================================================
This section describes the procedures for installing and removing the
iSCSI Driver covering the following topics:
System Requirements
Tested Hardware and Software
Installation Procedure
Removal Procedure
Driver Upgrade Procedure
-------------------
SYSTEM REQUIREMENTS
-------------------
The 3.x iSCSI Driver for Linux requires a host running the Linux operating
system with a kernel version of 2.4.20 or later. Versions older than 2.4.20
contain a variety of bugs that are described later in this section.
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.
Kernels released after the release date of this driver may not work
with this driver, depending on what if any changes have been made to
the kernel's SCSI mid-layer code.
There are several 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.
- Linux kernels have a known bug in the buffer and page cache design.
When any writes to a buffered block device fail, it is possible
for the unwritten data to be discarded from the caches, even though
the data was never written to disk. Any future reads will get the
prior contents of the disk, and it is possible for applications to
get no errors reported.
This occurs because block I/O write failures from the buffer
cache simply mark the buffer invalid when the write fails. This
leaves the buffer marked clean and invalid, and it may be
discarded from the cache at any time. Any future read either
finds no existing buffer or finds the invalid buffer, so the
read will fetch old data from disk and place it in the cache.
If the fsync(2) function initiated the write, an error may be
returned. If memory pressure on the cache initiated the write,
the unwritten buffer may be discarded before fsync(2) is ever
called, and in that case fsync will be unaware of the data loss,
and will incorrectly report success.
There is currently no reliable way for an application to ensure
that data written to buffered block devices has actually been
written to disk. Buffered data may be lost whenever a buffered
block I/O device fails a write.
The iSCSI driver attempts to avoid this problem by retrying disk
commands for many types of failures. The DiskCommandTimeout defaults
to "infinite", which disables the command timeout, allowing commands
to be retried forever if the storage device is unreachable or
unresponsive.
- The Redhat Advanced Server 2.1 kernels released as of January 29,
2003 have a kernel bug that can cause umount to oops. See bugs
<>
and <>
for more details. Please contact Redhat and request a kernel
update if you encounter this problem.
- All Linux kernels up to and including 2.4.20 have a bug in the
SCSI device initialization code. If kernel memory is low, the
initialization code can fail to allocate command blocks needed
for proper operation, but will do nothing to prevent I/O from
being queued to the non-functional device. If a process queues
an I/O request to a SCSI device that has no command blocks
allocated, that process will block forever in the kernel, never
exiting and ignoring all signals sent to it while blocked.
If the LUN probes initiated by the iSCSI driver are blocked
forever by this problem, it will not be possible to stop or
unload the iSCSI driver, since the driver code will still
be in use. In addition, any other LUN probes initiated by
the iSCSI driver will also block, since any other probes will
block waiting for the probe currently in progress to finish.
When the failure to allocate command blocks occurs, the kernel
will log a message similar to the following:
***************************************************************
kernel: scsi_build_commandblocks: want=12, space for=0 blocks
In some cases, the following message will also be logged:
kernel: scan_scsis: DANGER, no command blocks
***************************************************************
- Linux kernels 2.2.16 through 2.2.20 and 2.4.0 through 2.4.18 are known
to have a problem in the SCSI error recovery process. In some cases, a
successful device reset may be ignored and the SCSI layer will continue
on to the later stages of the error recovery process.
The problem occurs when multiple SCSI commands for a particular device
are queued in the low-level SCSI driver when a device reset occurs. Even
if the low-level driver correctly reports that all the commands for
the device have been completed by the reset, Linux will assume only
one command has been completed and continue the error recovery
process. (If only one command has timed out or failed, Linux will
correctly terminate the error recovery process following
the device reset.)
This action is undesirable because the later stages of error recovery
may send other types of resets, which can affect other SCSI
initiators using the same target or other targets on the same
bus. It is also undesirable because there are more serious bugs
in the later stages of the Linux SCSI error recovery process.
The Linux iSCSI driver now attempts to avoid this problem by
replacing the usual error recovery handler for SCSI commands
that timeout or fail.
- Linux kernels 2.2.16 through 2.2.20 and 2.4.0 through 2.4.2 may take
SCSI devices offline after Linux issues a reset as part of the
error recovery process. Taking a device offline causes all I/O to the
device to fail until the HBA driver is reloaded.
After the error recovery process does a reset, it sends a SCSI
Test Unit Ready command to check if the SCSI target is operational
again. If this command returns SCSI sense data, instead of correctly
retrying the command, Linux will treat it as a fatal error, and
immediately take the SCSI device offline.
The Test Unit Ready will almost always be returned with sense data
because most targets return a deferred error in the sense data of the
first command received after a reset. This is a way of telling
the initiator that a reset has occurred. Therefore, the affected
Linux kernel versions almost always take a SCSI device offline
after a reset occurs.
This bug is fixed in Linux kernels 2.4.3 and later.
The Linux iSCSI driver now attempts to avoid this problem by
replacing the usual error recovery handler for SCSI commands
that timeout or fail.
- Linux kernels 2.2.16 through 2.2.21 and 2.4.0 through 2.4.20 appear to
have problems when SCSI commands to disk devices are completed
with a check condition/unit attention containing deferred sense
data. This can result in applications receiving I/O errors,
short reads or short writes.
The Linux SCSI code may deal with the error by giving up reading
or writing the first buffer head of a command, and retrying the
remainder of the I/O.
The Linux iSCSI driver attempts to avoid this problem by
translating deferred sense data to current sense data for commands
sent to disk devices.
- Linux kernels 2.2.16 through 2.2.21 and 2.4.0 through 2.4.20 may crash
on a NULL pointer if a SCSI device is taken offline while one of the
Linux kernel's I/O daemons (e.g. kpiod, kflushd, etc.) is trying to do
I/O to the SCSI device. The exact cause of this problem is still being
investigated.
Note that some of the other bugs in the Linux kernel's error recovery
handling may result in a SCSI device being taken offline, thus
triggering this bug and resulting in a Linux kernel crash.
- Linux kernels 2.2.16 through 2.2.21 running on uniprocessors may
hang if a SCSI disk device node is opened while the Linux SCSI
device structure for that node is still being initialized.
This occurs because the sd driver which controls SCSI disks
will loop forever waiting for a device busy flag to be cleared
at a certain point in the open routine for the disk device.
Since this particular loop will never yield control of the
processor, the process initializing the SCSI disk device is
not allowed to run, and the initialization process can never
clear the device busy flag which the sd driver is constantly
checking.
A similar problem exists in the SCSI generic driver in some
2.4 kernel versions. The sg driver may crash on a bad
pointer if a /dev/sg* device is opened while it is being
initialized.
- All Linux 2.4 kernels may trigger TCP retransmits from
the iSCSI target system even though no packets were lost,
mis-ordered or duplicated by the connecting network.
Setting the sysctl variable net.ipv4.tcp_low_latency (if it
exists) to 1 may reduce or eliminate the TCP retransmits.
- RealTek ethernet controller RTL-8029 may encounter transmission
problems under heavy load which may cause a system panic.
----------------------------
TESTED HARDWARE AND SOFTWARE
----------------------------
The 3.6.0 version of iSCSI driver has been tested successfully using the
software and equipment listed below. The driver should also work with other
software and hardware configurations not listed below, assuming they are
consistent with the System Requirements described earlier in this document.
The test programs used were a variety of commercial applications and custom
scripts that generated various types of traffic loads including raw and
filesystem I/O, with and without errors being injected.
1. Distributions:
- Redhat 9 (kernel 2.4.20-8)
- Redhat Advanced Server 2.1 (kernel 2.4.9-e.3)
- Redhat Enterprise Linux 3 (kernel 2.4.21-9)
- SuSE Linux Enterprise Server 8 (2.4.20)
- SuSE Linux 8.2 (2.4.20)
2. Servers:
- Datanet Eclipse Server - 1 CPU
- IBM Netfinity 8656 - 1 CPU
- Compaq Evo Workstation - 1 CPU
- Eclipse Server - 2 CPUs
- Compaq Proliant DL360 - 2 CPUs
- Datanet Eclipse Server - 4 CPUs
3. Filesystems:
- ext2
- ext3
----------------------
INSTALLATION PROCEDURE
----------------------
Before you begin, make sure that your 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-.tgz file to a working directory (e.g.,
/usr/src/iscsi) where is the driver version (e.g., 3.6.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-3.6.0.tgz
cd linux-iscsi-3.6.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 iSCSI target
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 IP addresses and other required
driver parameters. Refer to "Editing The 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.
*******************************************************************************
NOTE: Before you begin, make sure that your 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 detailed procedures on removing the driver.
*******************************************************************************
-----------------
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-
------------------------
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
Bus-Nic Binding
Using Multipath I/O Software
Making Storage Configuration Changes
Target and LUN Discovery Limits
Dynamic Target And LUN Discovery
Persistent Target Binding
Service Location Protocol (SLP)
Target Authentication
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
********************************************************************
The directory /proc/scsi/iscsi will contain a file (the controller
number) that contains 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 the you manually
stop all applications using the filesystem on iSCSI devices before stopping
the driver. Filesystems not listed in /etc/fstab.iscsi will not be unmounted
by the script and should be manually unmounted prior to a system shutdown.
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
------------
Linux assigns SCSI device nodes (e.g., /dev/sda or /dev/sdb) to SCSI
logical units in the order that devices are discovered. There are two
potential issues that may arise related to device node assignment.
The first is that the mapping from the device node to the iSCSI
logical unit may vary each time the driver is started, because of
variations in process scheduling and network delay, and because of
hardware reconfiguration. The second is that the device node
represents a path to a SCSI logical unit (where a path is defined as a
SCSI host adapter, bus number, target ID and LUN). If there are
multiple paths to a SCSI logical unit, then the logical unit will be
reachable through multiple device nodes.
If Linux applications or utilities are configured to issue I/O to the
SCSI device node, and a reconfiguration or reboot causes the device
node to be reassigned, then I/O may go to the wrong device. Also, if
there are multiple paths to the device, then an application may
unintentionally view a single device as multiple independent devices.
Because of these issues, applications or operating system utilities
should not be configured to access the SCSI device nodes directly.
Instead, one of the following alternatives should be used:
- mount by filesystem UUIDs or labels (see man pages for mke2fs,
tune2fs, mount, and fstab)
- use logical volume management (see man lvm),
- use software RAID (see man md),
- use devlabel (see man devlabel)
The first three solutions write information to the disk and use that
information to locate the disk, so the Linux device node assignment is
irrelevant. Software RAID additionally provides the capability to join
multiple paths to a device into single virtual device, with automatic
failover when paths fail.
The devlabel solution relies on the world-wide unique identifier
(WWID) that is provided by most SCSI storage devices. Devlabel allows
the user to associate a label with the WWID of a device. This
association is persistent, because it is stored in a devlabel
configuration file on the root filesystem. When the system boots, or
when the devlabel "reload" command is used, devlabel reads the WWID of
the available disks. If a disk's WWID is in the devlabel file, then
it creates a symlink from the user-specified label to the current
Linux device node.
The devlabel symlink provides a persistent name that should be used by
applications or operating system utilities instead of the Linux device
node. Devlabel is also able to automatically detect multiple paths to
a device, and apply path-specific device labels, so that the paths
will not be mistaken for separate devices.
Earlier versions of the iSCSI driver automatically provided symbolic
links to the Linux device nodes. These names were of the form
/dev/iscsi/bus0/target0/lun0/disk. This feature has been removed from
the driver because the Linux 2.4 kernel does not provide the ability
to do this in a way that is portable and maintainable. If this type of
device naming is desired, it must be set up manually using devlabel.
Automatic creation of persistent device naming is expected to be
restored in the iSCSI driver in the 2.6 kernel, where a more complete
hot plugging infrastructure is available.
-------------------------
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.
------------
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 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.
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 special file in /proc/scsi/iscsi/.
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 "target 0 0 address 192.168.250.248" > /proc/scsi/iscsi/3
Where the syntax is:
echo "target address " >
/proc/scsi/iscsi/
A host system with multiple network interfaces can most effectively utilize
the failover feature for performing portal failover across subnets.
----------------
iSCSI HBA STATUS
----------------
The directory /proc/scsi/iscsi will contain a special file that can be
used to get status from your iSCSI HBA. The name of the file will
be the iSCSI HBA's host number, which is assigned to the driver
by Linux.
When the file is read, 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.
---------------
BUS-NIC BINDING
---------------
If a host has multiple network interface cards, then each of the
NIC can be bound to a SCSI bus of the iSCSI HBA. This feature is
useful for third party multipath software so that it can make use
of a faster bus/NIC to send I/Os through or can fail over I/Os to
another bus if one of the NIC goes down.
----------------------------
USING MULTIPATH I/O SOFTWARE
----------------------------
If a third-party multipath I/O software application is being used in
conjunction with the iSCSI driver, 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 "DiskCommandTimeout" 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 one of the
following configuration settings in iscsi.conf :
TYPE 1)
HostIPsforMP=IP1,IP2,... where IP1,IP2 are the IP addresses of the NICs on
the host to be used for multipathing. The number of sessions to each target
is equal to the number of IPs mentioned in the above setting. A session
through each of the NICs is established for every target.
TYPE 2)
Multipath=<"yes" or "portal" or "portalgroup">
If Multipath=<"yes" or "portal">, then a session through each of the target
portals is established. The target portal failover feature should not be
used if Multipath= <"yes" or "portal"> since multiple sessions will be
established with all available paths(portals).
If Multipath="portalgroup", then a session through each of the portal groups
is established.
*******************************************************************************
NOTE: TYPE (1) is always global. TYPE (2) can either be global or per target.
Configurations of TYPE (1) and TYPE (2) are mutually exclusive.When both
of them are configured TYPE (1) will override.
*******************************************************************************
------------------------------------
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
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.
--------------------------------
DYNAMIC TARGET AND LUN DISCOVERY
--------------------------------
When using iSCSI targets that support long-lived iSCSI discovery sessions,
the driver will keep a discovery session open waiting for change
notifications from the target. When a notification is received, the driver
will rediscover targets, add any new targets, and activate LUNs on all
targets.
If a new LUN is dynamically added to an existing target on a SCSI routing
instance with which the driver has established a connection, then the driver
does not automatically activate the new LUN. The user can manually activate
the new LUN by executing the following command:
echo "scsi add-single-device " >
/proc/scsi/scsi
where;
HBA#: is the controller number present under /proc/scsi/iscsi/
bus-id: is the bus number present on controller .
target-id: is the target ID present on ,.
LUN: new LUN added dynamically to the target.
-------------------------
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 symlinks 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 symlinks 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.
If 'HostIPsForMP' is set, then the iSCSI daemon uses the file
'/var/lib/iscsi/target_bindings' else it uses the file
/var/lib/iscsi/bindings' to store bindings of iSCSI target names to SCSI
target IDs. 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 '/var/lib/iscsi/bindings' contains the following fields:
BusId TargetId TargetName
A sample file would look like:
***************************************************************************
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
***************************************************************************
Each line of the file '/var/lib/iscsi/target_bindings' contains the following
fields:
TargetId TargetName
A sample file would look like:
****************************************************************************
0 iqn.1987-05.com.cisco:00.a2e50b57f5f5.t0
1 iqn.1987-05.com.cisco:00.9a558e9f2c9a.t1
****************************************************************************
Note that the above two files 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 appropriate file
('/var/lib/iscsi/target_bindings' if HostIPsforMP is set, else
'/var/lib/iscsi/bindings') 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 bindings file. Be careful to keep an entire entry on a single
line, with only whitespace characters between the 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=" entries /etc/iscsi.conf specify the driver to
unicast a SLP query to discover iSCSI targets using TCP/IP to the
specified (assuming this IP Address corresponds to that of a
SLP Service Agent(SA) or a SLP Directory Agent(DA)).
- "SLPMulticast= "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 .
*****************************************************************************
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:
_
installation_and_configuration_guides_list.html
2. PXELINUX which is a derivative of SYSLINUX available from:
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:
---------------------
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.
PortalFailover Enabling/disabling of target portal yes
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.
HostIPsforMP List of local IP addresses of local NICS -
to be used for Multipath of Type 1
Multipath Enabling/disabling of multipathing no
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 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.
LUNs A LUN or range of LUNs to be specified -
per TargetName entry or list of all
desired targets.
Enabled Enable/Disable a target or list of yes
targets discovered.
DiskCommandTimeout Time to wait before failing 0 sec
commands to a target disk device.
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
-------------------------------
- DiskCommandTimeout (Default = 0)
Set this value to change command timeout. Default value of 0 means that
the command timeout specified by the SCSI Layer is ignored and the
commands are retried indefinitely. Normally, command timeout for disk
devices is set to 30 seconds by SCSI layer.
As mentioned under the System Requirements section, the iSCSI driver
will retry failed disk commands indefinitely. You might want to
change DiskCommandTimeout under following scenarios:
1) Multi-pathing - In multi-path scenario, DiskCommandTimeout can be
set to a smaller value, say between 5 & 10 seconds so that SCSI
commands to unresponsive devices will fail more quickly and the
multi-path software will try a different path to the storage device.
2) Device offline - If the device is unresponsive or unreachable there
is a possibility that the commands to the device will be retried
indefinitely and the system may enter a locked up state. If there
is a remote possibility of bringing back that device online and
system availability is a concern, you might want to set this parameter.
- 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. In case you have also set DiskCommandTimeout
then the one with lower value will take precedence to fail the I/Os,
if there is a network failure.
*****************************************************************************
NOTE: The above timeout can usually be changed dynamically by following the
instructions under Dynamic Driver Reconfiguration section. The above
procedure fails to propogate the changes when network connection is
down. Use the following command to change ConnFailTimeout value when
the network connection is down.
echo "connfailtimeout " >
/proc/scsi/iscsi/
and can be valid Bus and Target identifiers in case
you want the change for a particular session. Specify BusId to be '-'
to change the value of all sessions with a particular TargetId.
Specify TargetId to be '-' to change the value of all sessions with a
particular BusId. Specify both the ids to be '-' to change the value
across all existing sessions.
ConnFailTimeout and DiskCommandTimeout are set to 30 and 5 respectively
in rc.iscsi during stop of the driver. This is done so as to prevent
a hang that can be caused because of unresponsive targets. You can
change these values by setting CONNFAILTIMEOUT and DISKCOMMANDTIMEOUT
respectively in the rc.iscsi file.
*****************************************************************************
----------------------------
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-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//kernel/misc/iscsi_sfnet.o
===============================================================================
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.
