Generate and Check an iSCSI Initiator Name with iscsi-iname

Every iSCSI initiator needs a unique IQN, and iscsi-iname generates one on demand without touching your configuration file. You will generate a name, check the result, and see when a custom prefix actually matters. Allow about five minutes for a first check, or longer if you are replacing a name used by active sessions.

This guide covers the open-iscsi package installed on this machine, version 2.1.9-3ubuntu5.4. The local manual page is older than the installed program, so the version and help output below take precedence where they differ.

1. Confirm the installed command

Run this as your normal user. No daemon restart, network login or root privilege is needed just to generate a name:

$ command -v iscsi-iname
/usr/sbin/iscsi-iname
$ dpkg-query -W -f='${Package} ${Version}\n' open-iscsi
open-iscsi 2.1.9-3ubuntu5.4
$ iscsi-iname --help
Usage: iscsi-iname [OPTIONS]
Where OPTIONS are from:
    -p/--prefix <prefix>          -- set IQN prefix [iqn.2016-04.com.open-iscsi]
    -g/--generate-iname-prefix    -- generate the InitiatorName= prefix
where <prefix> has max length of 210

2. Generate the default name

With no options, iscsi-iname uses the installed default prefix and adds a generated suffix:

$ iscsi-iname
iqn.2016-04.com.open-iscsi:2e914a7b1afb

The suffix will differ between invocations. Capture it into a shell variable when you need to inspect it without repeatedly generating new values:

$ initiator_name=$(iscsi-iname)
$ printf '%s\n' "$initiator_name"
iqn.2016-04.com.open-iscsi:e80a3c79ac2
$ case "$initiator_name" in iqn.*) echo 'looks like an IQN';; *) echo 'unexpected format'; exit 1;; esac
looks like an IQN

The case check is only a quick local sanity check. It does not prove a storage target accepts the name, or that it is unique across every host in your environment.

3. Supply an organisation-specific prefix

Use -p or its long form --prefix when the naming policy for your environment requires a particular prefix. The value is a prefix, not the complete initiator name: the program still appends its own generated suffix.

$ iscsi-iname --prefix 'iqn.2026-09.example.org:host42'
iqn.2026-09.example.org:host42:21fca8449
$ iscsi-iname -p 'iqn.2026-09.example.org:host42'
iqn.2026-09.example.org:host42:36c0e2f7fe67

Quote the prefix even when it currently contains no shell metacharacters. That makes a later change safer and keeps the argument as one value. Do not paste a whole InitiatorName= line after --prefix; the option expects only the prefix text.

The installed command accepts a prefix of at most 210 characters. A longer value fails outright instead of producing a truncated name:

$ iscsi-iname --prefix "$TOO_LONG_PREFIX"
error: prefix too long
Usage: iscsi-iname [OPTIONS]
$ printf 'exit status: %s\n' "$?"
exit status: 1

Use a short, documented prefix and check the generated output before it goes anywhere near a configuration file.

4. Produce a ready-to-copy configuration line

This installed version also supports -g and --generate-iname-prefix, which prints the setting name as well as the generated value:

$ iscsi-iname --generate-iname-prefix
InitiatorName=iqn.2016-04.com.open-iscsi:abaea597fc1

The local iscsi-iname(8) page does not document this option, which is exactly why checking the installed help matters. Treat the output as data to review, not a command to execute. A typical configuration file contains a line in this form:

InitiatorName=iqn.2026-09.example.org:host42:21fca8449

Before changing /etc/iscsi/initiatorname.iscsi, inspect the existing file and confirm whether sessions or automation depend on its current value:

$ sudo sed -n '1,20p' /etc/iscsi/initiatorname.iscsi
InitiatorName=iqn.2016-04.com.open-iscsi:old-host-name

5. Check distinct results and handle failures

Each invocation should produce a new name. Compare two values without printing any private configuration:

$ first=$(iscsi-iname)
$ second=$(iscsi-iname)
$ test "$first" != "$second" && echo 'distinct values generated'
distinct values generated

• Command missing. Install or repair the distribution's open-iscsi package through your normal package-management process.
• Custom prefix rejected. Check its length and remove accidental whitespace, or an entire configuration-line prefix pasted by mistake.
• Generated name refused by a target. Investigate the target's access policy, initiator ACL and the name recorded in your iSCSI configuration. Running the generator again does not repair an ACL mismatch.

Keep the generated value stable once it has been assigned to a host. Generating a fresh value for every boot or script run can make the host look like a new initiator and break target permissions. Use the command to create or verify an intentional value, then store that value through your distribution's normal configuration workflow.