Discover and Safely Manage iSCSI Sessions with iscsiadm

You will finish with a repeatable workflow for discovering an iSCSI target, inspecting the node record that discovery creates, logging in, checking the live session, and logging out again. The examples match iscsiadm 2.1.9 from open-iscsi package version 2.1.9-3ubuntu5.4.

Allow about fifteen minutes for an already prepared host and reachable test target. You need root access, a running iSCSI service, network access to the target portal, and a target administrator's address and credentials if CHAP is enabled. Storage operations can expose or change data, so use a test LUN or a maintenance window. Do not format a newly visible block device until you have identified it independently.

1. Check the local tool and service

Start with read-only checks. These do not need elevated privileges unless your local package policy restricts them:

$ iscsiadm -V
iscsiadm version 2.1.9
$ dpkg-query -W -f='${Package} ${Version}\n' open-iscsi
open-iscsi 2.1.9-3ubuntu5.4
$ systemctl is-active iscsid
active

The exact package revision and service output vary. If iscsid is not active, start it through your distribution's normal service manager before continuing. Many node and discovery operations require the daemon. The command reads its main configuration and initiator identity from /etc/iscsi/iscsid.conf and /etc/iscsi/initiatorname.iscsi. Check those files before troubleshooting a network connection.

2. Inspect existing records and sessions

Before creating anything, see what is already configured. These commands are ordinary read-only inspections:

$ sudo iscsiadm -m node
$ sudo iscsiadm -m session
$ sudo iscsiadm -m iface

No output from a mode is useful: it means that no matching node, session or configured interface was found. In open-iscsi terminology, a node is a target portal record, not an iSCSI initiator or target in the terminology of the protocol specification. The node database is kept under /etc/iscsi/nodes/; discovery records are under /etc/iscsi/send_targets/.

For more detail, use tree output when it helps identify a record:

$ sudo iscsiadm -m session -P 1

The session identifier shown there is useful for session-specific operations, but it is not persistent. It can change when sessions are recreated or when their setup order changes.

3. Discover targets at a portal

Replace PORTAL_IP with the address supplied by the storage administrator. SendTargets is the usual discovery type, and port 3260 is the default when no port is given:

$ sudo iscsiadm -m discoverydb -t sendtargets -p PORTAL_IP:3260 -D

This contacts the target and creates or updates discovery and node database records. It is a privileged, state-changing operation. The output normally contains one or more target names and portals, for example:

PORTAL_IP:3260,1 iqn.2026-01.example:storage.test

The target name and portal in your output are authoritative. Do not copy the example IQN into a login command. If the target uses a non-default discovery method, the manual also documents iSNS and firmware modes, but this workflow is specifically for SendTargets.

$ sudo iscsiadm -m node

If discovery fails, check routing and firewall access to the portal, then check the daemon logs. A successful discovery command only proves that records were created or returned; it does not prove that a session is logged in.

4. Log in to one discovered node

Use the exact target name and portal from the discovery output. Keep the values quoted so shell metacharacters cannot alter the command:

$ sudo iscsiadm -m node \
    -T 'TARGET_IQN_FROM_DISCOVERY' \
    -p 'PORTAL_IP:3260' \
    --login

A successful login normally returns without an error. The operation may create a new SCSI device, so stop here if you have not confirmed which host-side device should appear. If the target requires CHAP, configure credentials using the node record's documented fields and protect the secret. Avoid --show or -S during routine inspection: it tells iscsiadm not to mask values such as the CHAP secret.

Do not use --loginall=all as a shortcut on an unfamiliar host. It can log in to every eligible node and attach several devices. Start with one known record, then document the intended startup policy before enabling automatic logins.

5. Verify the live session and device identity

Check that a session exists, then inspect its tree output:

$ sudo iscsiadm -m session
$ sudo iscsiadm -m session -P 1

The first command should list the portal, session number and target name. The second provides the session's connections and attached SCSI targets. Exact formatting depends on the kernel and transport. If the list is empty, the login did not establish a live session even if a node record exists.

Use the operating system's read-only device tools to map the newly visible disk before mounting or changing it. For example:

$ lsblk -o NAME,MODEL,SERIAL,SIZE,FSTYPE,MOUNTPOINTS

Compare the result with the storage administrator's expected size and identity. Never run mkfs, partitioning tools or a mount command merely because a new device appeared. Those commands can destroy existing data or expose the wrong LUN.

If a session is connected but paths or devices look stale, iscsiadm can rescan a session with -m session -r SESSION_ID -R. The session ID is the value reported by iscsiadm, and the operation can change the kernel's view of devices. Confirm the ID and expected impact first.

6. Log out and recover cleanly

Unmount filesystems and stop applications using the LUN before logging out. Logging out while a device is in use can interrupt I/O. Then use the same target and portal tuple:

$ sudo iscsiadm -m node \
    -T 'TARGET_IQN_FROM_DISCOVERY' \
    -p 'PORTAL_IP:3260' \
    --logout

Verify that the session has gone:

$ sudo iscsiadm -m session
iscsiadm: No active sessions.

The exact no-session wording can differ, so the important check is that the command returns no active session. The node record remains, which makes a later login possible. If you want to remove the record as well, inspect the exact tuple first and use the delete operation deliberately:

$ sudo iscsiadm -m node \
    -T 'TARGET_IQN_FROM_DISCOVERY' \
    -p 'PORTAL_IP:3260' \
    --op delete

Deletion is irreversible from iscsiadm's point of view, although discovery can recreate a record later. Do not delete a running node: the manual warns that iscsiadm will stop the session and then remove its record. For a simple recovery, leave the node record in place and log in again after fixing the underlying network, authentication or target-side problem.

7. Avoid the emergency stop option

iscsiadm -k 0 immediately stops iscsid operations and shuts down the daemon. It does not log out sessions and can prevent error recovery. The installed manual describes this operation as experimental and equivalent to killing iscsid. Do not use it as a routine fix for a failed login. Prefer checking the portal, daemon state, node parameters and target-side logs, then restart the service only through your normal operational procedure if that is required.