Start an iSCSI Boot Session Safely with iscsistart

iscsistart brings up the root filesystem before Linux itself has started, and getting its options wrong can leave a box that will not boot. This walks through inspecting any firmware-supplied boot information, then either using it or supplying target details by hand. The installed command is from open-iscsi package version 2.1.9-3ubuntu5.4 and reports version 2.1.9.

Allow about fifteen minutes for inspection, longer if you are testing a real storage path. You need the open-iscsi package, a shell, network access to the target, and administrative access for anything that configures networking or creates a session. This guide does not format a LUN, mount a filesystem or change a boot loader.

1. Confirm which iscsistart you have

Start with read-only checks. None of these contact a target:

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

Keep the version with your change record: option details and output can differ between open-iscsi builds. Check the installed help before preparing a real command, especially on a machine that was upgraded:

$ iscsistart --help
Usage: iscsistart [OPTION]

2. Inspect firmware boot information

iscsistart is primarily an iSCSI root-boot tool. It can use boot information supplied through iBFT or Open Firmware (OF in the manpage). Ask it to print that information before attempting anything:

$ iscsistart --fwparam_print
Could not get list of targets from firmware.

The exact output is machine-specific. On this host the command returned status 21, meaning there was no usable firmware target list to print. That is a useful result, not a reason to invent target values. A host booted through an iSCSI-aware firmware path should instead show the firmware-provided data.

If your firmware data is present, compare the printed initiator name, target name, portal address, port and target portal group tag against the storage team's record. Do not paste credentials into a ticket or shell history while doing this review.

3. Choose the source of the connection settings

There are two supported shapes of invocation:

• Use firmware data with --fwparam_connect. This asks iscsistart to create a session using iBFT or OF information.
• Supply the values yourself. --initiatorname, --targetname, --tgpt and --address are the required ones; the port is optional and defaults to 3260.

The default configuration file is /etc/iscsi/iscsid.conf. Select another with --config=PATH only if your boot environment deliberately uses a separate file, and read it first to confirm its permissions and contents are appropriate:

$ sudo test -r /etc/iscsi/iscsid.conf && echo 'configuration is readable'
configuration is readable

4. Prepare an explicit target command

When firmware does not provide the path, prepare a command using values from your storage administrator. Replace every uppercase placeholder, including the target portal group tag:

$ sudo iscsistart \
    --initiatorname=iqn.2026-09.example:host01 \
    --targetname=iqn.2026-09.example:storage01 \
    --tgpt=TARGET_PORTAL_GROUP_TAG \
    --address=TARGET_IP_ADDRESS \
    --port=3260

The four required settings, when firmware data is not used, are the initiator name, target name, target portal group tag and IP address. The example deliberately leaves the tag and address incomplete so they cannot be mistaken for real storage details. Verify them before running anything that can create a session.

5. Add authentication only when required

For a target using one-way CHAP, add --username=NAME and --password=PASSWORD. For incoming authentication, use --username_in=NAME and --password_in=PASSWORD. Treat all four values as secrets:

$ sudo iscsistart \
    --initiatorname=INITIATOR_IQN \
    --targetname=TARGET_IQN \
    --tgpt=TARGET_PORTAL_GROUP_TAG \
    --address=TARGET_IP_ADDRESS \
    --port=3260 \
    --username=CHAP_USERNAME \
    --password='CHAP_PASSWORD'

Do not put a real password in a shared terminal transcript, documentation page or persistent shell history. Prefer the configuration mechanism approved for your boot environment, and check who can read that configuration. Short options -u, -w, -U and -W exist too, but the long forms make the direction of each credential clearer.

6. Use firmware data when the machine is configured for iSCSI boot

On a machine with valid iBFT or OF data, bring up the firmware-described network first if the boot design requires it:

$ sudo iscsistart --fwparam_network
$ sudo iscsistart --fwparam_connect

Both of these can alter networking and create a storage session, so run them from the intended boot or recovery context, not casually on a production host. The manpage does not promise a portable success message; treat a zero exit status as the primary signal, then inspect the host's normal iSCSI session and block-device checks.

Do not use iscsistart as a general session manager: its own manpage says it should not be run to manage sessions. Use the normal open-iscsi service and iscsiadm workflow for discovery, inspection and logout once the boot path is established.

7. Diagnose a failed attempt without repeating a login

Go back to the read-only checks first:

$ iscsistart --help
$ iscsistart --fwparam_print
$ ip route get TARGET_IP_ADDRESS

Check that the address is reachable on the intended interface, the target portal is listening on the selected port, and the portal group tag matches the storage record. Then check the initiator and target IQNs character by character. A successful network check does not prove authentication or access control will accept the login.

If the command used --config, repeat the review against that exact file rather than assuming the default /etc/iscsi/iscsid.conf was read. If a session was created but is no longer wanted, do not rerun iscsistart with guessed options: identify the session with iscsiadm and use its documented logout procedure, taking care not to log out a device that is mounted or holding live data.