Provided by: iscsitarget_1.4.20.2-5ubuntu3_i386 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.

A. Lehmann, M. Zhang and A. Redli27 July 2005                     IETD.CONF(5)