Generate a safe iSCSI initiator name with iscsi-gen-initiatorname

You will create or deliberately replace the Open-iSCSI initiator name file, then check the result without guessing which name source was used. Allow about ten minutes. You need the open-iscsi tools, a root shell for the generator, and a maintenance window if an iSCSI service is already using the file.

This guide follows the installed iscsi-gen-initiatorname(8) manual. On this machine the package is open-iscsi 2.1.9-3ubuntu5.4. The package currently provides the manual page and iscsi-iname, but not an executable named iscsi-gen-initiatorname; check that on your host before planning an automated run.

1. Check the package and command

Start with read-only checks. A missing command is a packaging or installation problem, not a reason to copy a name into the configuration file by hand.

$ dpkg-query -W -f='${Package} ${Version}\n' open-iscsi
open-iscsi 2.1.9-3ubuntu5.4
$ command -v iscsi-gen-initiatorname
$ command -v iscsi-iname
/usr/sbin/iscsi-iname

Your version and paths may differ. If the first command -v produces no path, stop at this checkpoint and obtain a package or build that actually contains the generator. The manpage alone cannot create the file.

2. Inspect the existing state

The generator writes /etc/iscsi/initiatorname.iscsi. The manual says not to edit this file manually. Before changing it, record whether it exists and make a root-owned backup if it contains a name you may need to restore.

$ sudo ls -l /etc/iscsi/initiatorname.iscsi
$ sudo grep '^InitiatorName=' /etc/iscsi/initiatorname.iscsi
InitiatorName=iqn.1996-04.de.suse:01:host-example

The displayed IQN is an example. Keep the exact value from your host, and do not publish it if it identifies an internal system. If the file does not exist, ls reports an error; that is a valid starting state. If the file is readable but its directory is not writable by root, resolve the filesystem or mount problem before running the generator.

3. Understand where the name comes from

iscsi-gen-initiatorname does not always invent a random name. Its documented order is:

1. the kernel command line parameter rd.initiatorname;
2. the iBFT data exposed through sysfs; or
3. a new value generated by iscsi-iname.

This order matters on provisioned or diskless systems. A value supplied by firmware or the boot environment can be intentional. The generator also refuses to continue when both the kernel command line and iBFT provide different initiator names. Fix the source of that disagreement rather than forcing a file into existence.

$ cat /proc/cmdline
BOOT_IMAGE=/vmlinuz root=UUID=EXAMPLE rd.initiatorname=iqn.1996-04.example:01:boot-host
$ find /sys -type f -name initiatorname -print 2>/dev/null

The first command is read-only. The second may print nothing when there is no iBFT data, and its output is hardware and boot-path dependent. Do not treat an empty result as a failure by itself.

4. Create the file without forcing a replacement

When the executable exists and the destination is absent, run it as root with no options:

$ sudo iscsi-gen-initiatorname
$ sudo test -s /etc/iscsi/initiatorname.iscsi && echo 'initiator name file is non-empty'
initiator name file is non-empty
$ sudo grep '^InitiatorName=' /etc/iscsi/initiatorname.iscsi

A successful run creates the documented file. The command does not need a manually supplied IQN when the kernel command line or iBFT already supplies one. If neither source applies, it delegates generation to iscsi-iname.

Run the command only once for a new file. A second ordinary run should fail rather than overwrite the existing name. That refusal protects the identity that existing targets and records may expect.

5. Use a prefix only for a newly generated IQN

Use -p when you need a different prefix for the IQN that the tool itself generates:

$ sudo iscsi-gen-initiatorname -p iqn.2026-09.example.org:01
$ sudo grep '^InitiatorName=' /etc/iscsi/initiatorname.iscsi
InitiatorName=iqn.2026-09.example.org:01:...generated-by-iscsi-iname...

The suffix is generated by the tool, so do not rely on an exact value in a script. The option changes the prefix for generated output; it is not a way to override a conflicting kernel command-line or iBFT name. If the file already exists, the normal no-overwrite rule still applies.

Choose an organisation-controlled prefix that follows your iSCSI naming policy. Keep the resulting name stable for the life of the host unless your storage administrator has planned an identity change.

6. Force an overwrite only with a recovery plan

Before using it, save the current file and capture the reason for the change:

$ sudo cp --preserve=all /etc/iscsi/initiatorname.iscsi /etc/iscsi/initiatorname.iscsi.before-force
$ sudo iscsi-gen-initiatorname -f -p iqn.2026-09.example.org:01
$ sudo grep '^InitiatorName=' /etc/iscsi/initiatorname.iscsi

If the replacement is wrong and services have not yet been restarted, restore the backup using the same ownership and mode, then verify it:

$ sudo cp --preserve=all /etc/iscsi/initiatorname.iscsi.before-force /etc/iscsi/initiatorname.iscsi
$ sudo grep '^InitiatorName=' /etc/iscsi/initiatorname.iscsi

Restoring the file does not undo a name already presented to a target or a service already restarted. Follow your site's iSCSI logout, login, and service-restart procedure before making the change live. Do not delete the backup until the host has completed its planned connectivity checks.

7. Diagnose a refusal

Use the error and the state at the earlier checkpoints to choose the next action:

• An existing file without -f is an expected refusal. Confirm the current name and decide whether replacement is genuinely required.
• Different kernel and iBFT names indicate inconsistent boot or firmware configuration. Make them agree before retrying.
• A read-only file or unwritable directory is a filesystem or mount issue. Check mount, ownership, and permissions as root; do not edit around the tool's safety check.
• A missing executable means the installed package does not match the manual page. Check package contents and obtain the correct Open-iSCSI build through your normal software channel.

The generator requires root. Ordinary inspection commands such as cat /proc/cmdline and command -v do not. Keep the boundary visible in scripts instead of running an entire shell as root.