iscsi.conf(5)

NAME

iscsi.conf - iSCSI Driver Configuration

SYNOPSIS

/etc/iscsi.conf

DESCRIPTION

This manual page describes the format of /etc/iscsi.conf
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.
B) Target Discovery via SLP mechanism.
C) Authentication settings.
D) Digest settings.
E) Preferred network path.
F) Portal Failover.
G) Multipath settings.
H) Connection timeouts.
I) Session timeouts.
J) Error handling timeouts.
K) iSCSI Operational Parameters.
L) TCP settings.
M) Per Target settings
N) Per Subnet settings.
O) LUN settings.
P) Keeping Discovery Session Alive

OPTIONS OF CATEGORY A:

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.

TargetIpAddr=<address>

A synonym for DiscoveryAddress.

OPTIONS OF CATEGORY B:

SLPMulticast=all|none|IP1,IP2,...

Specify the usage of SLP discovery mechanism for target
discovery using Multicast. Valid options are :

all Use all network interfaces on the host machine to

multicast SLP queries.

none Do not use SLP multicast.

list of IP address

specify a list of IP addresses on the host machine
to be used to multicast SLP queries.

SLPUnicast=<address>

Specify the IP address to which SLP queries for discover
ing targets can be unicasted.

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
300s for seconds or 5m for minutes or 1h for hours.

OPTIONS OF CATEGORY C:

IncomingUsername=<user>

Specify the CHAP authentication user name that should be
received from target during authentication of target by
initiator.

IncomingPassword=<pass>

Specify the CHAP authentication password that should be
received from target during authentication of target by
initiator.

OutgoingUsername=<user>

Specify the CHAP authentication user name that should be
sent by initiator during authentication of initiator by
target.

OutgoingPassword=<pass>

Specify the CHAP authentication password that should be
sent by initiator during authentication of initiator by
target.

Username=<user>

Synonym for OutgoingUsername.

Password=<pass>

Synonym for OutgoingPassword.

NOTE:

IncomingPassword has to be different from OutgoingPass
word. It is possible to have initiator authentication
alone, both initiator and target authentication but not
target authentication alone.

OPTIONS OF CATEGORY D:

HeaderDigest=always|never|prefer-on|prefer-off 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:

always require digests, and fail to login if the target

requires no digests.

never require no digests, and fail to login if the target

requires digests.

prefer-on

prefer digests, but login with no digests if the
target refuses to use digests.

prefer-off

prefer no digests, but login with digests if the
target insists on using them.

NOTE:

If HeaderDigest and/or DataDigest options are not speci
fied in the conf file then a default value of 'prefer-off'
is taken by the driver.

OPTIONS OF CATEGORY E:

PreferredSubnet=<a.b.c.d/bits>

Specify the preferred subnet to use for connection. This
will be the preferred subnet when automatic failover hap
pens. See the section on 'PortalFailover'. The subnet address can be specified in the following format:
Subnet=10.4.100.0/24

PreferredPortal=<address>

Specify preferred portal to use for connection. This will
be the preferred portal when automatic failover happens.
See the section on 'PortalFailover'. The specified 'address' could be a hostname or an IP address.

NOTE:

If both PreferredSubnet and PreferredPortal are specified
then PreferredPortal will be given preference.

OPTIONS OF CATEGORY F:

PortalFailover=yes|no

Specify how to use multiple network paths to same target.
Valid options are:

yes iSCSI driver will try to connect to the target

through alternate IP addresses automatically when
ever connection to the target is lost.

no iSCSI driver will not try portal failover feature

automatically. The user may then use the iscsifailover utility to reconnect to the target through an alternate IP address.

If PortalFailover entry is not present in the conf file
then a default value of 'yes' is taken by the driver.

OPTIONS OF CATEGORY G:

Multipath=no|portal|portalgroup

Specify the use of having multiple network paths to the
same target. Valid values are

no there is no multipathing. Establish at most one

session to the target and use all portals for
failover, if failover is not disabled.

portal establish a session to the target using each of the

n/w portals to the target, and bind each session to
a different host SCSI address. No portal failover
is possible since each session has only one portal.

portalgroup

establish a session to one portal from each portal
group that reaches the target and bind each session
to a different host SCSI address. If a portal group
has more than one portal, portal failover can occur
between that group's portals if failover is not
disabled.

OPTIONS OF CATEGORY H:

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.

AuthTimeout=<secs>

Specify the time in seconds to wait for a login PDU carry
ing 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.

IdleTimeout=<secs>

Specify the time in seconds a connection may remain idle.
Once the idle time of a session exceeds this setting the
connection status is checked with a ping. If this entry is
not present in the conf file, a default value of 60 sec
onds is taken by the driver.

PingTimeout=<secs>

Specify the time in seconds to wait for a ping response
before declaring the session as dead and attempting a reestablishment. If this entry is not present in the conf
file, a default value of 5 seconds is taken by the driver.

OPTIONS OF CATEGORY I:
ConnFailTimeout=<secs>

Specify the time in seconds to wait for a session reestablishment. If a session is not re-established in 'Con
nFailTimeout' 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.

MinDiskCommandTimeout=<secs>

Specify the minimum time in seconds to wait before failing
commands to a target device. If this entry is not present
in the conf file, a default value of -1 is taken by the
driver, which disables the command timeout, allowing com
mands to be retried forever.

MaxDiskCommandTimeout=<secs>

Specify the maximum time in seconds to wait before failing
commands to a target device. If multipath is enabled, the
MaxDiskCommandTimeout can be set to a smaller value, say 5
or 10 seconds. The default value is 0.

OPTIONS OF CATEGORY J:

AbortTimeout=<secs>

Specify the time in seconds to wait for an abort to com
plete 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.

ResetTimeout=<secs>

Specify the time in seconds to wait for a reset to com
plete 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.

OPTIONS OF CATEGORY K:

InitialR2T=yes|no

Specify the initiator's preference for InitialR2T text
key. Valid options are:

yes initiator must wait for an R2T before transmitting

data.

no initiator has an implied Initial R2T for 'First

BurstLength' at offset 0. If not specified in conf
file, a default value of 'no' is assumed.

ImmediateData=yes|no

Specify the initiator's preference for ImmediateData text
key. Valid options are:

yes initiator sends unsolicited data with the iSCSI

command PDU

no initiator does not send unsolicited data with the

iSCSI command PDU

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.

FirstBurstLength=<bytes>

Specify the number of bytes of unsolicited data, the ini
tiator 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.

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.

OPTIONS OF CATEGORY L:

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.

NOTE:

Configuration entries of category C to category L and cat
egory N can be global across all target connections.
Entries of category D to K and category N can be specified
for a particular target. Entries of category H,J,L can be
specified per subnet. Entries of category C,H and P can be
specified per DiscoveryAddress.Entries of category C can
be specifed per SLP entry(SLPMulticast or SLPUnicast).
The parameters are global if they appear before any Dis
coveryAddress or TargetName or Subnet or SLP entries. The
global entries need to start at column 1.
Entries of category C under DiscoveryAddress are applica
ble to all targets discovered on this address. Entries of
category H and P under DiscoveryAddress are applicable
only to the DiscoverySession.
Entries that appear below a 'TargetName' entry apply for
that particular target.
If they appear below a 'Subnet' entry then they apply for
sessions using that portals that fall into the subnet.
Entries of category C under SLP entries are applicable for
targets discovered through SLP on the interfaces men
tioned.

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.
The formats for TargetName and subnet entries are given
below.

OPTIONS OF CATEGORY M:

TargetName=<name>

<name> is iSCSI Target name in iqn or eui format. Target
specific settings should be entered below the respective
TargetName entry. If Multipath is enabled, then these tar
get-specific settings will be applicable for all iSCSI
sessions to this target.

OPTIONS OF CATEGORY N:

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. Sub
net=10.4.100.0/24

Address=<a.b.c.d>

Address is a shorthand to Subnet values with a netmask of
32. Example: Address=10.4.100.0

OPTIONS OF CATEGORY O:

LUN=<lun_number>

If it is a local entry, then the lun "lun_number" will be
configured for the particular TargetName. If it is a
global entry, then the lun "lun_number" will be configured
for all the targets whose TargetNames are mentioned in
the configuration file. Example: LUN=2

LUNs=<lun_range|lun_list> Range of luns to be configured can be specified using a
hyphen. If the lower end of the range is less than 0, then
it will be adjusted to 0. Similarly, if the higher end of
the range is greater than 255, it will be adjusted to 255.
A comma separated list of luns can also be specified.
Examples: LUNs=3-62 LUNs=47,124,200

As mentioned above, if this is a local entry, then the
luns will be configured for a particular TargetName, else
if this is a global entry, the luns will be configured for
all the targets whose TargetNames are mentioned in the
configuration file.

NOTE: If no TargetName entry is present in the configura
tion file, then the lun(s) will be configured for all the
available iSCSI targets.

OPTIONS OF CATEGORY P:

Continuous=yes|no

Specify whether discovery session should be kept alive or
not after doing the discovery. Valid options are:

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 Idletime
out then it sends NOP-OUT and expects NOP-IN
response from target within PingTimeout(5 seconds,
default). If target does not respond within Ping
Timeout then initiator assumes the connection has
been inadvertently broken, drops the current dis
covery session and attempts to establish a new dis
covery session.

no iSCSI initiator closes the connection and will not
attempt to establish a new one.

SendAsyncText=yes|no
Specify whether async event notification needs to be sent
by the target. Valid options are:

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.

no Async events are not sent when this option is spec
ified.

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 para
graph explains the scope of these settings and precedence
for conflicting entries.

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 sim
plicity 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:

OutgoingUserName=alice
OutgoingPassword=wonderland1342
LoginTimeout=20
DiscoveryAddress=192.168.250.230

OutgoingUserName=bob
OutgoingPassword=nyet1234

LoginTimeout=15
DiscoveryAddress=192.168.250.240

In the above example, OutgoingUserName will be "bob" and
OutgoingPassword will be "nyet1234" for all targets dis
covered 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 'Login
Timeout=' appeared.

If there is a conflict between 'local' entries under 'Tar
getName' and entries under 'Subnet' then local entries
under 'Subnet' entry will be considered.

Consider the example below:
LoginTimeout=25
Subnet=192.168.250.0/24
LoginTimeout=20

TargetName= iqn.1987-05.com.cisco:00.01c82dc85b33.fc8disk1
LoginTimeout=30

In the above case lets assume that Target '
iqn.1987-05.com.cisco:00.01c82dc85b33.fc8disk1' is reach
able through 192.168.250.230. The 'LoginTimeout' to be
used in this case will be 20 seconds.

FILES

/etc/iscsi.conf

iSCSI Target and LUN configuration

SEE ALSO

iscsid(8)

ISCSI.CONF(5)