Provided by: iscsitarget_1.4.20.3+svn499-0ubuntu2.6_amd64 
NAME
/etc/ietd.conf - configuration for iSCSI Enterprise Target Daemon
SYNOPSIS
/etc/ietd.conf
DESCRIPTION
/etc/ietd.conf contains configuration information for the ietd (8) command. This is the
place, where you configure your iSCSI targets and daemon defaults.
Only lines starting with `#' are ignored. Putting '#' in the middle of a line is
disallowed. A line may be extended across multiple lines by making the last character a
backslash.
The "Yes" and "No" for parameter values are case sensitive. The parameter names are case
insensitive.
The file consists of a global part and zero or more "Target" stanzas. Everything until the
first target definition belongs to the global configuration.
Here is an example:
IncomingUser joe secret
OutgoingUser jack secret2
Target iqn.2001-04.com.example:storage.disk2.sys1.xyz
IncomingUser jim othersecret
OutgoingUser james yetanothersecret
Lun 0 Path=/dev/sdc,Type=fileio
Lun 1 Blocks=10000,BlockSize=4096,Type=nullio
Alias Test
HeaderDigest None
DataDigest None
MaxConnections 1
MaxSessions 0
InitialR2T Yes
ImmediateData No
MaxRecvDataSegmentLength 8192
MaxXmitDataSegmentLength 8192
MaxBurstLength 262144
FirstBurstLength 65536
DefaultTime2Wait 2
DefaultTime2Retain 0
MaxOutstandingR2T 8
NOPInterval 0
NOPTimeout 0
DataPDUInOrder Yes
DataSequenceInOrder Yes
ErrorRecoveryLevel 0
Stanzas start with the word "Target" and the target name. This name must be a globally
unique name, as defined by the iSCSI standard : the "iSCSI Qualified Name". The daemon
brings the targets up in the order listed.
GLOBAL OPTIONS
Global Options are case sensitive.
[IncomingUser <username> <password>]
The <username> and <password> used during discovery sessions to authenticate iSCSI
initiators. Several of those can be specified for discovery. If no IncomingUser is
specified, any initiator is allowed to open a discovery session.
HINT: RFC 3720 requires <password> to be 12 characters long. This is enforced e.g.
by MS Initiator.
[OutgoingUser <username> <password>]
The <username> and <password> used during discovery sessions to authenticate the
target to initiators. Only one outgoing <username>/<password> combination may be
specified.
HINT: RFC 3720 requires <password> to be 12 characters long. This is enforced e.g.
by MS Initiator.
Target iqn.<yyyy-mm>.<tld.domain.some.host>[:<identifier>]
A target definition and the target name. The targets name (the iSCSI Qualified Name
) must be a globally unique name (as defined by the iSCSI standard) and has to
start with iqn followed by a single dot. The EUI-64 form is not supported.
<yyyy-mm> is the date (year and month) at which the domain is valid. This has to be
followed by a single dot and the reversed domain name. The optional <identifier> -
which is freely selectable - has to be separated by a single colon. For further
details please check the iSCSI spec.
Here is an example:
Target iqn.2004-07.com.example.host:storage.disk2.sys1.xyz
TARGET OPTIONS
Target options are also case sensitive.
[IncomingUser <username> <password>]
The <username> and <password> used to authenticate the iSCSI initiators to this
target. It may be different from the username and password in section GLOBAL
OPTIONS, which is used for discovery. If you omit the IncomingUser Option,
connections are allowed without authentication. A <password> has to be provided, if
there is a <username> given. Specifying several different IncomingUser accounts is
supported.
[OutgoingUser <username> <password>]
The <username> and <password> used to authenticate this iSCSI target to initiators.
Only one OutgoingUser per target is supported. It may be different from the
username and password in section GLOBAL OPTIONS, which is used for discovery. A
<password> has to be provided, if there is a <username> given.
Lun <lun> Type=(fileio|blockio),Path=<device>[,ScsiId=<scsi_id>][,ScsiSN=<scsi_sn>][,IOMode=(wb|ro|wt)][,BlockSize=<size>]
Lun <lun> Type=nullio[,Blocks=<count>][,BlockSize=<size>]
Parameters after <lun> should not contain any blank space characters except the
first blank space after <lun> is needed.
The value of <lun> can be from 0 to 16384. The first <lun> defined MUST be 0.
In fileio mode (default), it defines a mapping between a "Logical Unit Number"
<lun> and a given device <device> , which can be any block device (including
regular block devices like hdX and sdX and virtual block devices like LVM and
Software RAID devices) or regular files.
In blockio mode, it defines a mapping between a "Logical Unit Number" <lun> and a
given block device <device>. This mode will perform direct block i/o with the
device, bypassing page-cache for all operations. This allows for efficient handling
of non-aligned sector transfers (virtualized environments) and large block
transfers (media servers). This mode works ideally with high-end storage HBAs and
for applications that either do not need caching between application and disk or
need the large block throughput.
A ScsiId can be specified to assign a unique SCSI ID (VPD 0x83) to an iSCSI volume.
This is used by initiator hosts to uniquely identify a SCSI volume. This is
necessary with multipath-aware hosts accessing the same <device> through multiple
iSCSI sessions. The <scsi_id> must not exceed 16 characters.
Also a ScsiSN can be specified to assign a unique serial number (VPD 0x80) to an
iSCSI volume. This is used by certain initiator hosts (e.g. VMware ESX) to uniquely
identify a SCSI volume. This is essential when used in conjunction with VMware ESX
hosts accessing the same <device> through multiple iSCSI sessions. The <scsi_sn>
must not exceed 16 characters.
By default LUNs are writable, employing write-through caching. By setting IOMode to
"ro" a LUN can be set to read only mode. Setting IOMode to "wb" will enable write-
back caching of a LUN. Setting IOMode to "wt" is only symbolic as that is the
default behavior.
NOTE: IOMode "wb" is ignored when employing blockio as it performs no caching.
WARNING: IOMode=wb could lead to serious data loss from an unexpected system
failure (power loss, system crash). Use at your own risk!
You can specify a logical BlockSize for an iSCSI volume. This <size> must be one of
(512, 1024, 2048, 4096). If BlockSize isn't specified the default is 512 bytes for
fileio, and the logical block size of the lower level device for blockio (which
typically is 512 bytes).
NOTE: For blockio, you CANNOT specify a BlockSize less than the lower level
device's logical block size which is the minimum size the device can handle. An
error will be reported and the LUN will fail to attach if you try. You CAN use
fileio though to export a LUN with a BlockSize less than the lower level device's
logical block size.
WARNING: Once your data is written at a given BlockSize you cannot change this
BlockSize without risking corruption of your existing data.
In nullio mode, it defines a mapping between a "Logical Unit Number" <lun> and an
unnamed virtual device with a specified number of Blocks of BlockSize bytes. If
Blocks is not specified then it will default to 64GB's worth given the curent
BlockSize which defaults to 512 bytes. This is ONLY useful for performance
measurement purposes. All writes to this virtual device will be discarded and all
reads will return random data.
WARNING: By sending random kernel memory over the IP network you can potentially
expose sensitive information.
[Alias <aliasname>]
This assigns an optional <aliasname> to the target.
[HeaderDigest <CRC32C|None>]
Optional. If set to "CRC32C" and the initiator is configured accordingly, the
integrity of an iSCSI PDU's header segments will be protected by a CRC32C checksum.
The default is "None". Note that header digests are not supported during discovery
sessions.
[DataDigest <CRC32C|None>]
Optional. If set to "CRC32C" and the initiator is configured accordingly, the
integrity of an iSCSI PDU's data segment will be protected by a CRC32C checksum.
The default is "None". Note that data digests are not supported during discovery
sessions.
[MaxConnections <value>]
Optional. The number of connections within a session. Has to be set to "1" (in
words: one), which is also the default since MC/S is not supported.
[MaxSessions <value>]
Optional. The maximum number of sessions for this target. If this is set to 0 (wich
is the default) there is no explicit session limit.
[InitialR2T <Yes|No>]
Optional. If set to "Yes" (default), the initiator has to wait for the target to
solicit SCSI data before sending it. Setting it to "No" allows the initiator to
send a burst of FirstBurstLength bytes unsolicited right after and/or (depending on
the setting of ImmediateData ) together with the command. Thus setting it to "No"
may improve performance.
[ImmediateData <Yes|No>]
Optional. This allows the initiator to append unsolicited data to a command. To
achieve better performance, this should be set to "Yes". The default is "No".
[MaxRecvDataSegmentLength <value>]
Optional. Sets the maximum data segment length that can be received. The <value>
should be set to multiples of PAGE_SIZE. Currently the maximum supported value is
64 * PAGE_SIZE, e.g. 262144 if PAGE_SIZE is 4kB. Configuring too large values may
lead to problems allocating sufficient memory, which in turn may lead to SCSI
commands timing out at the initiator host. The default value is 8192.
[MaxXmitDataSegmentLength <value>]
Optional. Sets the maximum data segment length that can be sent. The <value>
actually used is the minimum of MaxXmitDataSegmentLength and the
MaxRecvDataSegmentLength announced by the initiator. The <value> should be set to
multiples of PAGE_SIZE. Currently the maximum supported value is 64 * PAGE_SIZE,
e.g. 262144 if PAGE_SIZE is 4kB. Configuring too large values may lead to problems
allocating sufficient memory, which in turn may lead to SCSI commands timing out at
the initiator host. The default value is 8192.
[MaxBurstLength <value>]
Optional. Sets the maximum amount of either unsolicited or solicited data the
initiator may send in a single burst. Any amount of data exceeding this value must
be explicitly solicited by the target. The <value> should be set to multiples of
PAGE_SIZE. Configuring too large values may lead to problems allocating sufficient
memory, which in turn may lead to SCSI commands timing out at the initiator host.
The default value is 262144.
[FirstBurstLength <value>]
Optional. Sets the amount of unsolicited data the initiator may transmit in the
first burst of a transfer either with and/or right after the command, depending on
the settings of InitialR2T and ImmediateData <value> should be set to multiples of
PAGE_SIZE. Configuring too large values may lead to problems allocating sufficient
memory, which in turn may lead to SCSI commands timing out at the initiator host.
The default value is 65536.
[DefaultTime2Wait <value>]
Currently not implemented, but can be used to set how long initiators wait before
logging back in after a connection is logged out or dropped.
[DefaultTime2Retain <value>]
Currently we only support 0 which means sessions are not retained after the last
connection is logged out or dropped.
[MaxOutstandingR2T <value>]
Optional. Controls the maximum number of data transfers the target may request at
once, each of up to MaxBurstLength bytes. The default is 1.
[DataPDUInOrder <Yes|No>]
Optional. Has to be set to "Yes" - which is also the default.
[DataSequenceInOrder <Yes|No>]
Optional. Has to be set to "Yes" - which is also the default.
[ErrorRecoveryLevel <value>]
Optional. Has to be set to "0" (in words: zero), which is also the default.
[NOPInterval <value>]
Optional. If value is non-zero, the initiator will be "ping"ed during phases of
inactivity (i.e. no data transfers) every value seconds to verify the connection is
still alive. If the initiator fails to respond within NOPTimeout seconds, the
connection will be closed.
[NOPTimeout <value>]
Optional. If a non-zero NOPInterval is used to periodically "ping" the initiator
during phases of inactivity (i.e. no data transfers), the initiator must respond
within value seconds, otherwise the connection will be closed. If value is set to
zero or if it exceeds NOPInterval , it will be set to NOPInterval.
[Wthreads <value>]
Optional. The iSCSI target employs several threads to perform the actual block I/O
to the device. Depending on your hardware and your (expected) workload, the number
of these threads may be carefully adjusted. The default value of 8 should be
sufficient for most purposes.
[QueuedCommands <value>]
Optional. This parameter defines a window of commands an initiator may send and
that will be buffered by the target. Depending on your hardware and your (expected)
workload, the value may be carefully adjusted. The default value of 32 should be
sufficient for most purposes.
KNOWN BUGS/LIMITATIONS
Currently (as of 0.4.11) not all iSCSI target parameters are used. Header and data digests
are not supported during discovery sessions.
SEE ALSO
ietd (8)
You should have a look at
RFC 3720 for all the glory details.