TARGETS.CONF(5)

📦
version 1.0.98 · 13 versions
, in alpine 3.24, arch rolling

🎀 targets.conf(5) 🎀

okay so this is the manpage for targets.conf — literally the Linux SCSI Target Configuration File — and bestie, if you're messing with iSCSI targets you're gonna want to get cozy with it. 💅

✨ NAME ✨

targets.conf — Linux SCSI Target Configuration File 🦋

🌸 DESCRIPTION 🌸

So tgt-admin reads /etc/tgt/targets.conf to initialize the tgtd configuration — that's the default, no cap. The layout is giving HTML, honestly: it's a whole hierarchy of nested tags that define your targets and your LUNs. Think of it like a vibe-coded little XML cousin and you're golden. ✨

💖 CONFIGURATION FILE SYNTAX 💖

Global directives configure the options that are global to tgtd's configuration — and they also define your exported targets, via target sections. Two jobs, main character energy. 👑

Target sections hold directives specific to one target device. They define each target's exported LUNs via the backing-store and direct-store directives, plus all the other target-wide options.

LUN directives (you guessed it: backing-store and direct-store) can contain options specific to a single exported logical unit. Tiny but mighty. 🧚

🌈 GLOBAL DIRECTIVES 🌈

Heads up before we go: with the exception of target directives, each of these should occur at most once. So no spamming them, okay? 🫶

  • <target <IQN>> — this kicks off a target definition, the opening tag basically. IQN is an ISCSI Qualified Name, like iqn.2001-04.com.example:storage1. Inside this block you put the target-level directives (documented below, mwah 💋). The whole thing closes with </target>.
  • default-driver <lld> — instead of specifying a driver type for every single target (exhausting), default-driver sets a default low-level driver for all exported targets. It can be overriden on a per-target basis, so it's not a forever commitment. Valid lld values are iscsi or iser. And since iscsi is assumed when this directive isn't present, you only really need this if iser is the default you're after.
  • include <path> — pulls the configuration in from another config file. Wildcards are allowed! So something like include /etc/tgt/xen/*.conf is fully legal. slay. ✨
  • ignore-errors yes — errors from tgtadm get ignored. Default is no.
  • control-port <port> — define a different local socket key for communicating with tgtd. Defaults to 0. Only generally useful when you've got multiple instances of tgtd running.
  • iSNSServerIP <addr> — define the address of the iSNS server, in IPv4 dotted-quad address format. Required when you're using iSNS; otherwise it just sits there ignored. 🙈
  • iSNSAccessControl <value> — set iSNS access control. Valid values are On or Off. Again: required when using iSNS, otherwise ignored.
  • iSNSServerPort <port> — set a different iSNS server port. Default is 3205. Optional when you're using iSNS, otherwise ignored.
  • iSNS On — enables iSNS. The only valid value is On. Default is off.
  • incomingdiscoveryuser <user> <userpassword> — define the iscsi incoming discovery authentication setting. If no value is given, no authentication is performed. (fyi, "no auth" is a whole vibe but maybe not the vibe 🤨)
  • outgoingdiscoveryuser <user> <userpassword> — define the iscsi outgoing discovery authentication setting. If no value is given, no authentication is performed.

🦋 TARGET-LEVEL DIRECTIVES 🦋

Every target can export multiple block devices, aka logical units (LUNs). And for the purposes of LUN numbering: backing-store directives are processed before direct-store directives. Order matters, iykyk. 💅

  • backing-store <path> — defines a logical unit (LUN) exported by the target. The path can be a regular file or a block device.
  • direct-store <path> — defines a direct mapped logical unit (LUN) with the same properties as the physical device — stuff like VENDOR_ID, SERIAL_NUM, etc. It's literally the device, no filter. 🪞
  • driver <lld> — the low-level driver for this target, either iscsi or iser (no quotes, queen). This overrides that default-driver global directive from earlier. Override era.
  • initiator-address <addr> — allows connections only from the specified IP address. Defaults to ALL if you don't specify any initiator-address directive.
  • initiator-name <addr> — allows connections only from the specified initiator name.
  • incominguser <user> <userpassword> — define the iscsi incoming authentication setting. If no incominguser is specified, it's not used. This one can be used multiple times per target, go off. 🔥
  • outgoinguser <user> <userpassword> — define the iscsi outgoing authentication setting. If no outgoinguser is specified, it's not used. Also usable multiple times per target.
  • controller_tid <val> — define the tid of the controller. Default is the next available integer.

💜 LUN-LEVEL DIRECTIVES 💜

Okay so here's the tea: all of these can be listed at the target level (in which case they apply to all LUNs) or inside an individual LUN's definition — that second thing only works if the LUN is defined with the container-style, multi-line definition instead of the single-line format:

<backing-store /dev/sdb1>
  # LUN directives go here
</backing-store>

<direct-store /dev/sdb1>
  # LUN directives go here
</direct-store>
⚠️ real talk: use either single-line or container-style LUN definitions within a target. Mixing the two styles can cause parser errors, and the parser is not in the mood. 😭
  • write-cache <val> — on or off. Default is on.
  • scsi_id <val> — that's it, that's the entry 🫶
  • scsi_sn <val>
  • vendor_id <val>
  • product_id <val>
  • product_rev <val>
  • sense_format <val>
  • removable <val>
  • path <val>
  • mode_page <val>
  • readonly <val>
  • device-type <val>
  • bs-type <val>
  • allow-in-use <val>
  • block-size <val> — specify the block size for this LUN.
  • lbppbe <val> — specify the Logical blocks per physical block exponent. By default TGTD will set the lbppbe to automatically match the underlying filesystem — use this parameter to override that setting.
💀 this is an internal option that should not be set directly. Like, seriously.
  • la_lba <val> — specify the lowest aligned logical block address.
💀 also an internal option that should not be set directly.
  • optimal_xfer_gran <val> — specify the optimal transfer granularity, to be reflected in the Block Limits VPD.
💀 internal option, do not set directly. seeing a pattern?
  • optimal_xfer_len <val> — specify the optimal transfer length, to be reflected in the Block Limits VPD.
💀 internal option, do not set directly.
  • params <vals> — pass additional parameters to tgtadm.

Note that '${tid}' and '${lun}' can be used verbatim to refer to the tid and lun that are being configured. See targets.conf.vtl.L700 for an example. ✨

⭐ CONFIGURATION FILE EXAMPLE ⭐

Example configuration file:

<target iqn.2007-04.com.example:san.monitoring>
  backing-store /dev/san/monitoring

  # if no "incominguser" is specified, it is not used
  incominguser backup secretpass12

  # defaults to ALL if no "initiator-address" is specified
  initiator-address 192.168.1.2
</target>

<target iqn.2007-02.com.example:san.xen1>
  backing-store /dev/san/xen1-disk1 # LUN1
  direct-store /dev/san/xen1-disk2  # LUN2

  initiator-address 192.168.1.2     # Allowed IP
  initiator-address 192.168.5.6     # Allowed IP

  incominguser user1 secretpass12
  incominguser user2 secretpass23

  outgoinguser userA secretpassA
</target>

<target iqn.2007-02.com.example:san.xen2>
  backing-store /dev/san/xen2
</target>

<target iqn.2007-06.com.example:san.vmware1>
  backing-store /dev/san/vmware1
</target>

🍓 FILES 🍓

  • /etc/tgt/targets.conf — configuration file for tgt-admin.
  • /usr/share/doc/tgt/targets.conf.example — example configuration file for tgt-admin.

👑 SEE ALSO 👑

tgtd(8), tgtadm(8), tgtimg(8), tgt-setup-lun(8).

https://github.com/fujita/tgt

🧚 REPORTING BUGS 🧚

Report bugs to <stgt@vger.kernel.org> 💌

and that's the whole page, bestie! 🎀 this one came from [FIXME: source] and it's dated 11/01/2026 — so if you're reading it some other time, hi from the past, hope your LUNs are numbered correctly 💖✨🦋

📦 where this page comes from