Generate and Check an iSCSI Initiator Name with iscsi-iname

You will generate an iSCSI initiator name, check the result, and understand when to use a custom prefix. The command prints a value and does not edit your iSCSI configuration by itself. 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 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

Checkpoint: if command -v finds a different copy, or the package query reports another release, use that binary's help output as the authority for its available options.

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 that 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 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. This 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 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 putting it into a configuration file.

4. Produce a ready-to-copy configuration line

This installed version also supports -g and --generate-iname-prefix. It 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 why checking the installed help matters. Treat the output as data to review, not as 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

This is the first command in the guide that normally needs elevated privileges. Changing an initiator name can make a target treat the machine as a different initiator, which can affect access controls and existing sessions. Do not replace a live value just to make it look tidier. If you must change it, save a root-owned backup first, make the smallest edit possible, and follow your site's procedure for reconnecting sessions.

Recovery is to restore the backup, then follow the same service or session procedure your distribution uses. The generator itself has no undo operation because it does not persist anything.

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

If the command is missing, install or repair the distribution's open-iscsi package through your normal package-management process. If a custom prefix is rejected, check its length and remove accidental whitespace or an entire configuration-line prefix. If a generated name is 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 appear to be a new initiator and can break target permissions. Use the command to create or verify an intentional value, then store that value through your distribution's normal configuration workflow.