Installation and Design Notes for iSCSI RHEL 4 U2
*****************************************************************************
Installation and Design Notes for iSCSI RHEL 4 U2
*****************************************************************************
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 http://www.ietf.org.
For more information about the iSCSI protocol, refer to the RFC 3720 at
http://www.ietf.org/rfc/rfc3720.txt
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 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 target accepts the login and sends target identifiers.
4. The iSCSI driver queries the targets for device information.
5. The targets respond with the device information.
6. 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 digest support
2. Two way CHAP authentication
3. R2T flow control support with a target
4. Third party multi-path support
5. Sendtargets discovery mechanisms
6. Dynamic target discovery
7. Async event notifications for portal and target changes
8. Immediate Data Support
9. Error recovery level 0
10. Dynamic driver reconfiguration
11. Auto-mounting for iSCSI filesystems after a reboot
The following features are planned for future releases:
1. IPv6 support
===============================================================================
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
iSCSI HBA Status
Using Multipath I/O Software
Making Storage Configuration Changes
Target and LUN Discovery Limits
Target Authentication
Editing The iscsi.conf File
Tuning iSCSI Timeout Parameters
iSCSI Commands and Utilities
iSCSI sysfs files and module params
Driver File Listing
————————————–
STARTING AND STOPPING THE iSCSI DRIVER
————————————–
To manually start the iSCSI driver enter:
service iscsi start
The iSCSI initialization will report information on each detected
device to the console or in dmesg(8) output. For example:
********************************************************************
Vendor: SEAGATE Model: ST39103FC Rev: 0002
Type: Direct-Access ANSI SCSI revision: 02
Detected scsi disk sda at scsi0, channel 0, id 0, lun 0
SCSI device sda: hdwr sector= 512 bytes.
Sectors= 17783240 [8683 MB] [8.7 GB]
sda: sda1
********************************************************************
To see the iscsi devices currently available on this system, use the
utility:
/sbin/iscsi-ls -l
If there are problems loading the iSCSI kernel module, diagnostic
information will be placed in /var/log/messages.
To manually stop the iSCSI driver enter:
service iscsi stop
You must make sure that anything that has an iscsi device open has
closed the iscsi device before shutting down iscsi. This includes
filesystems, volume managers, and user applications.
If iscsi devices are open when you attempt to stop the driver, the
script will error out instead of removing those devices. This
prevents you from corrupting the data on iscsi devices. In this
case, iscsid will no longer be running – so if you want to continue
using the iscsi devices, it is recommended you issue ‘service iscsi
start’.
Note: It is recommended that on all filesystems mounted on iscsi
devices, either directly or on virtual devices (LVM, MD) that are
made up of iscsi devices, the ‘_netdev’ mount option is used. This
way they will automatically be unmounted by the netfs initscript
(before iscsi is stopped) during normal shutdown, and you can more
easily see which filesystems are in network storage.
—————
REBOOTING LINUX
—————
To safely reboot a Linux system, enter the following command:
reboot
OR
/sbin/shutdown -r now
All iSCSI devices should be unmounted prior to a system shutdown or reboot.
See the Starting And Stopping The Driver section of this document for a more
detailed description of the unmounting process.
————
DEVICE NAMES
————
iSCSI driver uses the default kernel names for iSCSI device. This
is inline with other SCSI devices and transports like FC/SATA.
Since Linux assigns SCSI device nodes dynamically whenever a
SCSI logical unit is detected, the mapping from device nodes
(e.g., /dev/sda or /dev/sdb) to iSCSI targets and logical units may
vary.
Variations in process scheduling and network delay may result in
iSCSI targets being mapped to different SCSI device nodes every time
the driver is started. Because of this variability, configuring
applications or operating system utilities to use the standard
SCSI device nodes to access iSCSI devices may result in SCSI
commands being sent to the wrong target or logical unit.
The above issues justify the need for persistent device naming for
iSCSI devices. If you intend to have persistent names for iSCSI devices,
you can make use of one or more schemes available for 2.6 kernel users.
a) Udev – udev can be used to provide persistent names for all types of
devices. scsi_id program which provides serial number for a given block
device is integrated with udev and can be made use for persistency.
b) UUID & LABEL based mouting – Filesystems and LVM provide facility
to mount devices by UUID or LABEL and hence ensure persistency
across reboots.
————————-
AUTO-MOUNTING FILESYSTEMS
————————-
Filesystems installed on iSCSI devices cannot be automatically mounted at
system reboot due to the fact that the IP network is not yet configured at
mount time. However, the driver provides a method to auto-mount these
filesystems as soon as the iSCSI devices become available (i.e., after the IP
network is configured).
To auto-mount a filesystem installed on an iSCSI device, follow these steps:
1. List the iSCSI partitions to be automatically mounted in
/etc/fstab.
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
entries will mount the two iSCSI devices specified (sda and sdb);
*************************************************************************
#device mount FS mount backup fsck
#to mount point type options frequency pass
LABEL=/ / ext3 defaults 1 1
LABEL=/boot /boot ext3 defaults 1 2
/dev/sda /mnt/t0 ext2 _netdev 0 0
/dev/sdb /mnt/t1 ext2 _netdev 0 0
*************************************************************************
3. Upon a system restart, the netfs init script will mount all filesystems
with the ‘_netdev mount’ option. This init script is run after the
networking and iscsi scripts to ensure the system is ready to mount these
devices.
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. You should not assume mounts of iSCSI devices will occur in
any particular order.
Because of the variability of the mapping between SCSI device nodes
and iSCSI targets, it is always recommended to either mount the iSCSI
device nodes which have persistent device names, mount filesystem UUIDs
or labels (see man pages for mke2fs, mount, and fstab), or use logical
volume management (see Linux LVM) to avoid mounting the wrong device due
to device name changes resulting from iSCSI target configuration changes
or network delays.
————
LOG MESSAGES
————
The iSCSI driver contains components in the kernel and user level.
The log messages from these components are sent to syslog. Based on the
syslogd configuration on the Linux host, the messages will be sent to the
appropriate destination. For example, if /etc/syslog.conf has the following
entry:
*.info /var/log/messages
then all log messages of level ‘info’ or higher will be sent to
/var/log/messages.
If /etc/syslog.conf has the following entry:
*.info;kern.none /var/log/messages
then all log messages (except kernel messages) of level info or higher
will be sent to /var/log/messages.
If /etc/syslog.conf has the following entry:
kern.* /dev/console
then all kernel messages will be sent to the console.
All messages from the iSCSI driver when loading the iSCSI kernel
module will be placed in /var/log/messages.
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.
To remove these sessions execute the following for each of these sessions:
– Set ConnFailTimeout, ResetTimeout and AbortTimeout on the session to a low
value, like 5 seconds through sysfs by executing the following commands:
echo 5 > /sys/class/scsi_host/host<host_no>/connfail_timeout
echo 5 > /sys/class/scsi_host/host<host_no>/reset_timeout
echo 5 > /sys/class/scsi_host/host<host_no>/abort_timeout
– Stop IOs to all the devices discovered through the session.
– If these devices have been mounted, unmount them.
– Shutdown the session through sysfs by executing the following command:
echo > /sys/class/scsi_host/host<host_no>/shutdown
where <host_no> is the Host Number of the session that has to be removed.
————————
ASYNC EVENT NOTIFICATION
————————
Changes occuring at the iSCSI target need to be communicated to the initiator
as asynchronous messages after negotiating the key “SendAsyncText”. The async
events will be notified to the initiator in the following scenario.
These events are sent over the discovery session.
1. PortalOnline – Indicates that a portal (IP Address and TCP port) has been
added, so target sessions can be established on this portal.
2. PortalOffline – Indicates the initiator that a portal (IP Address and TCP
port) has been removed, hence if the initiator loses connectivity to this
address and port, it should not be retried.
3. TargetOnline – Notifies the initiator that a new target may be
available for use and the initiator can try to establish connection to
this target.
4. TargetOffline – Notifies the initiator that a target has become
unavailable. If the initiator loses target connectivity, it should not
retry connection if any further connection attempt is denied.
—————-
iSCSI HBA STATUS
—————-
The directory ‘/sys/class/scsi_host/’ contains all registered SCSI HBA
entries and corresponding sysfs files to read/write any host specific
attributes. All iSCSI host entries will be present in any of hostX
directory, where X can be (0 to 2^32 – 1) number of allowable host ids.
The proc_name attribute can be used to identify the iSCSI host under
sysfs.
# more /sys/class/scsi_host/hostX/proc_name
iscsi-sfnet
The following file can be used to request shutdown of an iscsi session.
shutdown – stop the iSCSI driver.
# echo “shutdown” > /sys/class/scsi_host/hostX/shutdown
—————————-
USING MULTIPATH I/O SOFTWARE
—————————-
Some iSCSI target devices have multiple Ethernet ports. Those systems may be
configured to allow iSCSI target access via multiple paths. When the iSCSI
driver discovers targets through a multi-port device, it also discovers all
the IP addresses that can be used to reach each of those targets.
It establishes a session using each of the IP addresses through which the
target can be reached. It exports all the available paths to the user.
Multipath drivers exploit this feature to provide better performance
(due to load sharing) and high availability (failover of I/O if one of the
path goes bad).
It may be necessary to modify the configuration of the driver to allow
the multi-pathing software to operate more efficiently. If you are using
a multipath I/O application, you may need to set the “ConnFailTimeout”
parameter of the iSCSI driver to a smaller value so that SCSI commands will
fail more quickly when an iSCSI network connection drops allowing the
multipath application to try a different path to for access to the storage
device.
A safe timeout configuration for dm-multipath would be the following:
ConnFailTimeout=90
LoginTimeout=30
ActiveTimeout=5
PingTimeout=15
These settings would put a upper bound of 90 seconds for when upper layers,
like the scsi layer or multipath layer, would be notified of a problem. In
most cases when there is a network problem the ActiveTimeout and PingTimeout
would force a error within 20 seconds.
Depending on the network, target, number of iscsi users, etc, user may need
to increase the timeouts to prevent flooding the system with errors.
Device mapper, a multipath software can be obtained from the
following URL:
http://sources.redhat.com/dm/
————————————
MAKING STORAGE CONFIGURATION CHANGES
————————————
Making changes to your storage configuration, including adding or
removing targets or LUNs, remapping targets, or modifying target
access, may change how the devices are presented to the host operating
system. This may require corresponding changes in the iSCSI driver
configuration and /etc/fstab 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:
service 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 and application configurations as
appropriate.
5. Restart the iSCSI driver by entering:
service iscsi start
Failure to appropriately update the iSCSI configuration using
the above procedure may result in a situation that prevents
the host from accessing iSCSI storage resources.
——————————-
TARGET AND LUN DISCOVERY LIMITS
——————————-
The bus ID and target ID are always zero in the new one hba per transport
model since every target will have one hba instance. The host ID is unique
for every target and changes across reboots. Totally 0 to 2^23 -1 hosts can
be allocated on a linux system. The lun ID is assigned by the iSCSI target,
the iSCSI intiator driver currently supports 256 LUNs per target.
If a LUN ID > 256 it will be ignored by the driver and will not be
configured in the system.
———————
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.
LoginTimeout Time interval to wait for the login 120 sec
phase to complete before failing a
connection attempt. Includes initial
connection and login (+authentication).
IdleTimeout Time interval to wait for on a 60 sec
connection before sending a ping when
there are no active tasks in the
session.
ActiveTimeout Time interval to wait for on a 5 sec
connection before sending a ping when
there are active tasks in the session.
PingTimeout Time interval to wait for a ping 5 sec
response after a ping is sent before
failing a connection.
ConnFailTimeout Time interval to wait before failing 0 sec
SCSI commands back to an application
for unsuccessful commands.
AbortTimeout Time interval to wait for a abort 10 sec
command to complete before declaring
the abort command failed.
ResetTimeout Time interval to wait for a reset 30 sec
command to complete before declaring
the reset command failed.
Enabled Enable/Disable a target or list of yes
targets.
InitialR2T Enabling/disabling of R2T flow control no
with the target.
ImmediateData Enabling/disabling the sending of yes
unsolicited data burst with the iSCSI
command PDU.
MaxRecvDataSegment Maximum number of bytes that the 128K
Length initiator can receive in an iSCSI PDU.
FirstBurstLength Maximum number of bytes of unsolicited 256K
data the initiator is allowed to send.
MaxBurstLength Maximum number of bytes for the SCSI 16M
payload negotiated by initiator.
TCPWindowSize Maximum number of bytes that can be 256K
sent over a TCP connection by the
initiator before receiving an
acknowledgement from the target.
Continuous Enabling/disabling the discovery yes
session to be kept alive. If
Continuous = “yes” and a “Reject(0x3f)”
message is received from the target in
response to the ping (NOP_OUT) message
sent by the initiator, the Continuous
parameter will be set to “no” and no
further ping messages will be sent by
the initiator.
SendAsyncText Enable/disable sending “X” keys related to yes
Async events; Cisco target only.
A detailed description for each of these parameters is included in both the
man page and the included sample iscsi.conf file. Please consult these sources
for examples and more detailed programming instructions.
——————————-
TUNING iSCSI TIMEOUT PARAMETERS
——————————-
– ConnFailTimeout (Default = 0)
Set this value to fail commands when there is network problem. Default
value of 0 means that commands will not be failed. You might want to
change ConnFailTimeout under following scenario:
If the network is down for sufficiently long time, the application
doing I/Os to iSCSI device will seem to hang. At this point, you
might want to fail the I/Os by setting ConnFailTimeout to a reasonably
low value. This will fail the I/Os to the application and the
application will resume.
*****************************************************************************
NOTE: The above timeout can usually be changed dynamically by following the
instructions under Dynamic Driver Reconfiguration section. The above
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 “<Timeout>” > /sys/class/scsi_host/hostX/connfail_timeout
X – host number of iSCSI HBA.
Specify timeout to change the value across all existing sessions.
ConnFailTimeout is set to 30 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 this value by setting
CONNFAILTIMEOUT 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.
– “iscsi-rescan” rescans iSCSI targets for newly added LUNs.
Please refer to the man page for more information.
– “iscsi-kill-session” stops session attached to specific host or all
sessions if a host is not specified. See sysfs below to match a
host to a session to a target port. If IO is in progress, it will
be failed.
————-
MODULE PARAMS
————-
max_initial_login_retries – Max number of times to retry logging into a target
for the first time before giving up. The default is 3. Set to -1 for no limit.
can_queue – Max number of commands per session that can be queued. The default
is 512.
cmds_per_lun – Max number of commands per device that can be queued to the
device. Default is 32. Cannot be lower than 1 and cannot be higher than
the can_queue.
max_sectors – Max number of sectors per requests.
max_sg – Max number of scatter list entries per request.
—————
SYSFS INTERFACE
—————
This section describes the iscsi-sfnet, scsi_transport_iscsi, iscsi_host
and some useful SCSI Mid Layer sysfs files.
ISCSI SCSI HOST SYSFS DIRECTORY
——————————-
iSCSI scsi host sysfs files can found in the /sys/class/scsi_host/hostX
(X is the host number) directory. Note, that the iscsi-sfnet driver
allocates a scsi host per session, but in the past it allocated a single
scsi host for all sessions. To now match a host with its iSCSI session you
must follow the /sys/class/scsi_host/hostX /device link:
#cd /sys/class/scsi_host/host1/device
# ls
power target1:0:0
Then use the target identifier to find the session in the
/sys/class/iscsi_transport directory:
#cd /sys/class/iscsi_transport
#ls
target1:0:0
#cd target1:0:0
FILES
—–
active_timeout – Time interval to wait for on a connection before sending
a ping when there are active tasks in the session.
idle_timeout – Time interval to wait for on a connection before sending
a ping when there are no active tasks in the session.
login_timeout – Time interval to wait for the login phase to complete
before failing a connection attempt. Includes initial connection and
login (+authentication).
connfail_timeout – Time interval to wait after a session drop before
failing new SCSI commands back to an application for unsuccessful commands.
ping_timeout – Time interval to wait for a ping response after a ping is
sent before failing a connection.
abort_timeout – Time interval to wait for a abort command to complete
before declaring the abort command failed.
reset_timeout – Time interval to wait for a reset command to complete
before declaring the reset command failed.
session_established – Set to one if a session is established (in FFP)
and zero if not.
session_established_time – jiffies value when session is established.
shutdown – Write “1” to the file to cause the session to be dropped and
removed from the existing list of sessions that the driver is managing.
The session will not be dropped until IO that has been internally queued
by the driver has completed. New requests will be failed.
drop_session – Write “1” to the file to force a session to be logged out
and relogged in. IO that is currently being processed by the driver will
be failed with the decision of whether or not to retry the IO left up to
SCSI mid-layer. This is only useful for testing.
session_drop_time – jiffies value when the session was dropped.
host_busy – Number of commands being processed by the scsi host.
scan – Write “B T L” to this file (where ‘B’ is the bus/channel number,
‘T’ is the target/id number, and ‘L’ is the logical unit number) to scan
a specific logical unit. A wildcard value of ‘-‘ can be used for any
variable to force the driver to scan all valid values.
cmd_per_lun – The initial max number of commands the driver can process
per lu. This is defined in iscsi-sfnet.h as ISCSI_CMDS_PER_LUN. For devices
that support tags this value can be increased to a max of
ISCSI_MAX_CMDS_PER_LUN (defined in iscsi-sfnet.h) through the scsi device
queue_depth sysfs file described below.
sg_tablesize – This determines the degree to which the host is capable of
scatter-gather.
window_closed – Count of how many times the command window for this
session has closed.
proc_name – Name to identify the iSCSI driver. This value is “iscsi-sfnet”.
device – Symlink to scsi host driver model device directory. From the scsi
host device directory you can find the host’s targets, devices,
iscsi_hosts and iscsi_transports.
ISCSI HOST SYSFS DIRECTORY
————————–
The iSCSI host files can be found under /sys/class/iscsi_host/hostX
(where X is the host number). These are files contain information or
control settings that are specific to the iSCSI RFC.
FILES
—–
initiator_alias – The iSCSI initiator alias.
initiator_name – The iSCSI initiator name.
device – Symlink to scsi host driver model device directory.
ISCSI TRANSPORT SYSFS DIRECTORY
——————————-
The iSCSI transport/session files can be found under
/sys/class/iscsi_transport/targetH:B:T where ‘H’ is the host no, ‘B’ is
the bus/channel number and ‘T’ is the target/id number. The files found
in this directory expose iSCSI RFC information for a particular session.
FILES
—–
data_digest – Reading this file returns the type of cyclic integrity
checksum that was negotiated for. The driver does not support data digests
so this value is always “None”.
header_digest – Reading this file returns the type of cyclic integrity
checksum that was negotiated for. The possible values are “CRC32C” or “None”.
immediate_data – Reading this file returns “Yes” if support for immediate
data was negotiated for, and “N” if no
initial_r2t – Reading this file returns “Yes” if InitialR2T=Yes was
negotiated and “No” if not.
max_burst_len – Reading this file returns the MaxBurstLength value
negotiated for.
max_recv_data_segment_len – Reading this file returns the
MaxRecvDataSegmentLength value negotiated for.
max_xmit_data_segment_len – Reading this file returns the
MaxRecvDataSegmentLength for the target negotiated for.
first_burst_len – Reading this file returns the FirstBurstLength value
negotiated for.
target_name – iSCSI target name.
target_alias – iSCSI target alias.
tpgt – Target portal group tag.
ip_address – IP address of portal.
port – Port number.
tsih – Target Session Identifying Handle
isid – Initiator part of the Session Identifer.
device – Symlink to scsi target driver model device directory.
ISCSI SCSI DEVICE DIRECTORY
—————————
The iSCSI scsi device files can be found under
/sys/class/scsi_device/H:B:T:L where ‘H’ is the host no, ‘B’ is the
bus/channel number, ‘T’ is the target/id number and ‘L’ is the LUN. This
section does not describe all the scsi device files, only the one that
iscsi_sfnet driver specific or interesting for managing the driver.
FILES
—–
queue_depth – Sets or returns the queue depth size of the device. If
tagged command queueing is supported this value can be adjusted to a value
between 1 and 128. Setting the value too high can result in memory
allocation and deadlock problems.
delete – Write “1” to the file to delete the device.
state – Read the file to get the current device state. Write a new state
value to change the device state. Valid values are:
– created
– running
– cancel
– deleted
– quiesce
– offline
– blocked
——————-
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/iscsid
/sbin/iscsi-device
/sbin/iscsi-iname
/sbin/iscsi-ls
/sbin/iscsi-rescan
/man/man5/iscsi.conf.5
/man/man1/iscsi-ls.1
/man/man1/iscsi-rescan.1
/man/man8/iscsid.8
/lib/modules/<uname -r>/misc/iscsi_sfnet.ko
/lib/modules/<uname -r>/misc/scsi_transport_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.
