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 20
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 supported.
[DefaultTime2Retain <value>]
Currently not supported.
[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.
A. Lehmann, M. Zhang and A. Redli27 July 2005