Provided by: iscsitarget_1.4.20.3+svn499-0ubuntu2.6_amd64 bug

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.