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
IncomingUser jim othersecret
OutgoingUser james yetanothersecret
Lun 0 Path=/dev/sdc,Type=fileio
Lun 1 Blocks=10000,BlockSize=4096,Type=nullio
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.
Here is an example:
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.