iscsi.conf.5

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

.\" iSCSI configuration file
.\" Copyright (C) 2002 Cisco Systems, Inc.
.\" 
.\" $Id: iscsi.conf.5,v 1.7 2005/02/18 12:53:32 smithan Exp $
.TH ISCSI.CONF 5
.SH NAME
iscsi.conf \- iSCSI Driver Configuration
.SH SYNOPSIS
.B /etc/iscsi.conf
.SH DESCRIPTION
This manual page describes the format of 
\fU/etc/iscsi.conf\fR file. This file is a simple text file that 'iscsid' uses to locate iSCSI targets and configure various operational parameters.
Comments are marked by lines beginning with '#'.
The conf file can have entries related to following categories:

A) Target Discovery via 'SendTargets' mechanism. 
.br
B) Target Discovery via SLP mechanism.
.br
C) Authentication settings.
.br
D) Digest settings.
.br
E) Connection timeouts.
.br
F) Session timeouts.
.br
G) Error handling timeouts.
.br
H) iSCSI Operational Parameters.
.br
I) TCP settings.
.br
J) Per Target settings
.br 
K) Per Subnet settings.
.br
L) Enable/Disable Targets.
.br
M) Keeping Discovery Session Alive
.SH OPTIONS OF CATEGORY A:
.SS
.B DiscoveryAddress=<address>
IP address or hostname to use for target discovery.  A TCP port
number may be specified by appending a colon followed by the port
number. This entry must start in the first column, and must not 
contain any whitespace.
.SS
.B TargetIpAddr=<address>
A synonym for DiscoveryAddress.  
.SH OPTIONS OF CATEGORY B:
.SS
.B SLPMulticast=all|none|IP1,IP2,...
Specify the usage of SLP discovery mechanism for target discovery using Multicast. Valid options are :
.TP
.B all
Use all network interfaces on the host machine to multicast SLP queries.
.TP
.B none
Do not use SLP multicast.
.TP
.B list of IP address
specify a list of IP addresses on the host machine to be used to multicast 
SLP queries.
.SS
.B SLPUnicast=<address>
Specify the IP address to which SLP queries for discovering targets can be
unicasted.
.SS
.B PollInterval=<time>
Specify the interval between successive SLP queries. An interval of zero means 
the query should be sent only once. If no value is specified, a default time of
300 seconds will be used.
The time value can be specified as either
.B 300s
for seconds
or
.B 5m
for minutes
or
.B 1h
for hours.
.fi
.SH OPTIONS OF CATEGORY C:
.SS
.B IncomingUsername=<user>
Specify the CHAP authentication user name that should be received from
target during authentication of target by initiator.
.SS
.B IncomingPassword=<pass>
Specify the CHAP authentication password that should be received from target
during authentication of target by initiator.
.SS
.B OutgoingUsername=<user>
Specify the CHAP authentication user name that should be sent by initiator 
during authentication of initiator by target.
.SS
.B OutgoingPassword=<pass>
Specify the CHAP authentication password that should be sent by initiator
during authentication of initiator by target.
.SS
.B Username=<user>
Synonym for OutgoingUsername.
.SS
.B Password=<pass>
Synonym for OutgoingPassword.
.SH NOTE:
IncomingPassword has to be different from OutgoingPassword. It is possible to
have initiator authentication alone, both initiator and target authentication
but not target authentication alone.

.SH OPTIONS OF CATEGORY D:
.SS 
.B HeaderDigest=always|never|prefer-on|prefer-off

.SS DataDigest=always|never|prefer-on|prefer-off
Specify how to negotiate the use of CRC32C checks to detect the corruption
of iSCSI PDU header and data. The available options are:
.TP
.B always     
require digests, and fail to login if the target requires no digests.
.TP
.B never      
require no digests, and fail to login if the target requires digests.
.TP
.B prefer-on  
prefer digests, but login with no digests if the target refuses to use
digests.
.TP
.B prefer-off 
prefer no digests, but login with digests if the target insists on using them.
.SH NOTE:
If HeaderDigest and/or DataDigest options are not specified in the conf file
then a default value of 'prefer-off' is taken by the driver.
.SH OPTIONS OF CATEGORY E:
.SS
.B LoginTimeout=<secs>
Specify the time in seconds to wait for a login PDU to be sent or received 
before failing the login on a particular connection. If this entry is not
present in the conf file, a default value of  15 secs is taken by driver.
.SS
.B AuthTimeout=<secs>
Specify the time in seconds to wait for a login PDU carrying Authentication 
information to be sent or received before failing the login on a particular
connection. If this entry is not present in the conf file, a default value of 45 seconds is taken by the driver.

The below mentioned timeouts, IdleTimeout and ActiveTimeout determine when a
ping has to be sent so as to determine the status of the connection. 'ping' will
be sent only if there is no inbound traffic from target even after the timeout.
.SS
.B IdleTimeout=<secs>
Specify the time in secs. This timeout will be used if there are no active tasks
in the session. If this entry is not present in the conf file, a default value
of 60 seconds is taken by the driver.
.SS
.B ActiveTimeout=<secs>
Specify the time in secs. This timeout will be used if there are active tasks
in the session. If this entry is not present in the conf file, a default value
of 5 seconds is taken by the driver.
.SS
.B PingTimeout=<secs>
Specify the time in seconds to wait for a ping response before declaring
the session as dead and attempting a re-establishment. If this entry is not 
present in the conf file, a default value of 5 seconds is taken by the driver.
.SH OPTIONS OF CATEGORY F:
The session timeout settings in iSCSI driver are tuned to maintain data
integrity under non ideal conditions. This value can be tuned based on
the type of situation. Refer README for description of timeout
settings and recommended timeout settings under different situations.  
.SS
.B ConnFailTimeout=<secs>
Specify the time in seconds to wait for a session re-establishment. If
a session is not re-established in 'ConnFailTimeout' seconds then I/Os on
the session will be failed immediately without honoring the timeout associated
with the SCSI command. By default the timeout value is 0 which means no
timeout.
.SH OPTIONS OF CATEGORY G:
.SS
.B AbortTimeout=<secs>
Specify the time in seconds to wait for an abort to complete before declaring
the abort as failed. If an entry is not specified in the conf file, then
a  default value of 10 seconds is taken by driver.
.SS
.B ResetTimeout=<secs>
Specify the time in seconds to wait for a reset to complete before declaring
the reset as failed. If an entry is not specified in the conf file, then a
default value of 30 seconds is taken by driver.
.SH OPTIONS OF CATEGORY H:
The default values of these settings  have already been tuned for optimal
performance in iSCSI driver. Hence these should not be normally modified.
.SS
.B InitialR2T=yes|no
Specify the initiator's preference for InitialR2T text key. Valid options are:
.TP
.B yes
initiator must wait for an R2T before transmitting data.
.TP
.B no
initiator has an implied Initial R2T for 'FirstBurstLength' at offset 0.
If not specified in conf file, a default value of 'no' is assumed.
.SS
.SS
.B ImmediateData=yes|no
Specify the initiator's preference for ImmediateData text key. Valid options are:
.TP
.B yes
initiator sends unsolicited data with the iSCSI command PDU. If not 
specified in conf file, a default value of 'yes' is assumed.
.TP
.B no
initiator does not send unsolicited data with the iSCSI command PDU
.SS
.B MaxRecvDataSegmentLength=<bytes>
Specify the maximum no of bytes, initiator can receive in the data segment of
an iSCSI PDU. The value specified must be in the range <512 to (2^24 -1)>. If not specified in the conf file, a default value of 128 kb is assumed.
.SS
.B FirstBurstLength=<bytes>
Specify the number of bytes of unsolicited data, the initiator can send. The 
value specified must be in the range <512 to (2^24 - 1)>. If not specified in the conf file, a default value of 256 kb is assumed.
.SS
.B MaxBurstLength=<bytes>
Specify the maximum SCSI payload that the initiator can receive/send in a
Data-In or a solicited Data-Out iSCSI sequence. The value specified must be 
in the range <512 to (2^24-1)>. If not specified in the conf file,  a default value of (16 * 1024 * 1024) - 1024 is taken.
.SH OPTIONS OF CATEGORY I:
.SS
.B TCPWindowSize=<number>
Specify the TCP Window size to be set for the TCP socket used for iSCSI 
connection. If not specified in the conf file, a default value of 256 kb
is taken.
.SH NOTE:
- Configuration entries of category C to category I and category L,M can be global across all target connections.
.br 
- Entries of category D to H and category L can be specified for a particular target.
.br
- Entries of category E,G,I can be specified per subnet.
.br
- Entries of category C,E and M can be specified per DiscoveryAddress.
.br
- Entries of category C can be specifed per SLP entry(SLPMulticast or SLPUnicast).
.br
- The parameters are global if they appear before any DiscoveryAddress or TargetName or Subnet or SLP entries. The global entries need to start at column 1. 
.br
- Entries of category C under DiscoveryAddress are applicable to all targets discovered on this address. 
.br
- Entries of category E and M under DiscoveryAddress are applicable only to the DiscoverySession.
.br
- Entries that appear below a 'TargetName' entry apply for that particular target.
.br
- If they appear below a 'Subnet' entry then they apply for sessions using that portals that fall into the subnet. 
.br
- Entries of category C under SLP entries are applicable for targets discovered
through SLP on the interfaces mentioned.
.br
- Settings which are specific to a 'DiscoveryAddress' or 'TargetName' or 'Subnet' or 'SLP' entry should NOT start at column 1 i.e., they have to be indented by atlease one whitespace character.
.br
.br
The formats for TargetName and subnet entries are given below.
.SH OPTIONS OF CATEGORY J:
.SS
.B TargetName=<name>
<name> is iSCSI Target name in iqn or eui format.
Target specific settings should be entered below the respective TargetName entry. These target-specific settings will be applicable for all iSCSI sessions to the target. 
.SH OPTIONS OF CATEGORY K:
.SS
.B Subnet=<subnet address>
Subnet settings apply to sessions to a network portal in one of the specified
subnets, or whose address matches one of the specified addresses. 
Subnet takes the "address" and "netmask" values in the format specified below.
Subnet=10.4.100.0/24
.SS
.B Address=<a.b.c.d>
Address is a shorthand to Subnet values with a netmask of 32.
Example:
Address=10.4.100.0

.SH OPTIONS OF CATEGORY L:
.SS
.B Enabled=yes|no
The above parameter can be used to globally enable or disable targets
or to selectively enable them under per Targetname option. Valid options are:
.TP
.B yes
TargetNames mentioned after this line will be enabled by default
.TP
.B no
TargetNames mentioned after this line will be disabled by default

.SH OPTIONS OF CATEGORY M:
.SS
.B Continuous=yes|no
Specify whether discovery session should be kept alive or not
after doing the discovery. Valid options are:
.TP
.B yes
iSCSI initiator waits for IdleTimeout(60 seconds, default) to get a NOP-IN from target. If initiator gets a NOP-IN from target during IdleTimeout then initiator replies with NOP-OUT. But if initiator does not get a NOP-IN from target during Idletimeout then it sends NOP-OUT and expects NOP-IN response from target within PingTimeout(5 seconds, default). If target does not respond within PingTimeout then initiator assumes the connection has been inadvertently broken, drops the current discovery session and attempts to establish a new discovery session.
.TP
.B no
iSCSI initiator closes the connection and will not attempt to establish a new one.
.SS
.B SendAsyncText=yes|no
Specify whether async event notification needs to be sent by the target.
Valid options are:
.TP
.B yes
Target sends vendor specific async messages when target configuration changes.
The events can be target becoming available or unavailable, portal being
added or removed.
.TP
.B no
Async events are not sent when this option is specified.
If SendAsyncText entry is not present in the conf file then a default value
of 'yes' is taken by the driver.

.SH SCOPE OF SETTINGS

As mentioned above,configuration entries  can be specified as either global values or per DiscoveryAddress or per target or per subnet or per SLP entry. The following paragraph explains the scope of these settings and precedence for conflicting entries.
.P
If entries begin at column 1 of the conf file then they will be the global.
If entries need to be made specific to DiscoveryAddress or target or subnet or SLP entry they have to appear after the corresponding 'DiscoveryAddress' or 'TargetName' or 'Subnet' entry and should NOT begin at first column (i.e., they have to be indented). For simplicity we refer to them as local entries. If there is a conflict of entries between global and local, then local ones will be used.
Consider the example below:
.P
OutgoingUserName=alice
.br
OutgoingPassword=wonderland1342
.br
LoginTimeout=20
.br
DiscoveryAddress=192.168.250.230
.br
	OutgoingUserName=bob
.br
	OutgoingPassword=nyet1234
.br
LoginTimeout=15
.br
DiscoveryAddress=192.168.250.240
.P
In the above example, OutgoingUserName will be "bob" and OutgoingPassword will be "nyet1234" for all targets discovered under 192.168.250.230. (Local values 
override global ones). LoginTimeout used will be 20.

In case of DiscoveryAddress 192.168.250.240,  "alice" and "wonderland1342" are 
the username and passwords used for authentication, however the logintimeout 
used is 15. 'LoginTimeout=20' had scope till another global 'LoginTimeout=' 
appeared.
.P
If there is a conflict between 'local' entries under 'TargetName'  and entries under 'Subnet' then local entries under 'Subnet' entry will be considered. 

.br
Consider the example below:
.br
LoginTimeout=25
.br
Subnet=192.168.250.0/24
.br
	LoginTimeout=20
.br
TargetName= iqn.1987-05.com.cisco:00.01c82dc85b33.fc8disk1
.br
	LoginTimeout=30
.br
.P
In the above case lets assume that Target ' iqn.1987-05.com.cisco:00.01c82dc85b33.fc8disk1' is reachable through 192.168.250.230. The 'LoginTimeout' to be used in this case will be 20 seconds.
.fi
.SH FILES
.TP
\fC/etc/iscsi.conf\fR
.br
.SH "SEE ALSO"
.BR iscsid (8)