Ubuntu Manpage: /etc/ietd.conf - configuration for iSCSI Enterprise Target Daemon

Provided by: iscsitarget_1.4.20.3+svn502-2ubuntu4.5_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