ISCSI.CONF

Section: Devices and Network Interfaces (4)
Index Return to Main Contents

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) Authentication settings.
C) Digest settings.
D) Preferred network path.
E) Portal Failover.
F) Multipath settings.
G) Connection timeouts.
H) Error handling timeouts.
I) iSCSI Operational Parameters.
J) TCP settings.
K) Per Target settings
L) Per Subnet settings.
M) LUN settings.
N) 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:

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 OutgoingPassword. It is possible to have initiator authentication alone, both initiator and target authentication but not target authentication alone.

OPTIONS OF CATEGORY C:

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 specified in the conf file then a default value of 'never' is taken by the driver.

OPTIONS OF CATEGORY D:

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

Specify the preferred subnet to use for connection. This will be the preferred subnet when automatic failover happens. 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 E:

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 whenever connection to the target is lost.
no: iSCSI driver will not try portal failover feature automatically. The user may then use the iscsi-failover 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 F:

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

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

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 seconds 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 re-establishment. If this entry is not present in the conf file, a default value of 5 seconds is taken by the driver.

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.

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 commands 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 H:

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.

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.

OPTIONS OF CATEGORY I:

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 'FirstBurstLength' at offset 0. If not specified in conf file, a default value of 'no' is assumed.

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

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

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 J and category M can be global across all target connections. Entries of category C to J and category M can be specified for a particular target. Entries of category G,H,J can be specified per subnet. Entries of category B,G and N can be specified per DiscoveryAddress.
The parameters are global if they appear before any DiscoveryAddress or TargetName or Subnet entries. The global entries need to start at column 1.
Entries of category B under DiscoveryAddress are applicable to all targets discovered on this address. Entries of category G and N 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.

Settings which are specific to a 'DiscoveryAddress' or 'TargetName' or 'Subnet' 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 K:

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 target-specific settings will be applicable for all iSCSI sessions to this target.

OPTIONS OF CATEGORY L:

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

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

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 configuration file, then the lun(s) will be configured for all the available iSCSI targets.

OPTIONS OF CATEGORY N:

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 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.
no: iSCSI initiator closes the connection and will not attempt to establish a new one.

SCOPE OF SETTINGS

As mentioned above,configuration entries can be specified as either global values or per DiscoveryAddress or per target or per subnet. The following paragraph 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 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: 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 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. If there is a conflict between 'local' entries under 'TargetName' 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 reachable through 192.168.250.230. The 'LoginTimeout' to be used in this case will be 20 seconds.