LFCE 114 🐧 iSCSI Initiator Setup - KandZ

⏱️ Estimated read: 15 min | |

The iSCSI initiator is the client side of the block storage relationship. It discovers targets, authenticates against them, establishes sessions, and presents the resulting LUNs to the local kernel as SCSI block devices. On Linux, this role is filled by the Open-iSCSI project: the iscsid daemon, the iscsiadm management tool, and a set of kernel modules that handle the SCSI command transport .

Quick How-To Guides & Fast FixesNeed a quick fix or step-by-step solution? Browse our fast answers on HowTo.KandZ.me:

Operating Systems CLI →Dev Environment Languages →Web Network Tools →Security Accounts →Security Access Tech →Device Phone Basics →Social Messaging →Digital Files Media →

This chapter covers the complete initiator workflow: installing the initiator utilities, configuring the initiator name, discovering targets with SendTargets, authenticating with CHAP, logging in, verifying the session and LUNs, and making the configuration persistent across reboots. By the end, you will have a remote LUN visible as /dev/sdX and a session that reconnects automatically after a restart.

Key point: Discovery and login are separate operations. Discovery records target portals in a local database; login establishes the actual session. A discovered target is not a connected target, and iscsiadm -m discovery alone does not create a block device.

Why initiator setup has this shape

The discovery database is local state. When you run iscsiadm -m discovery, the tool contacts the target portal, receives a list of target IQNs and portal addresses, and writes that information into /var/lib/iscsi/ . This database persists across reboots and is what iscsiadm -m node operates on. Login uses the database entry, not a fresh network query. This is why you can discover once and log in multiple times, and why a stale database entry can cause login failures after the target’s configuration changes.

CHAP credentials live in two places. The initiator can authenticate to the target during normal session login (node.session.auth.*), and it can authenticate during discovery (discovery.sendtargets.auth.*) . Discovery authentication is optional and only needed if the target requires CHAP for SendTargets. Session authentication is what the target uses to authorize the initiator’s IQN. The two credential sets are independent, and mixing them up is a common source of login failures.

The node startup mode determines persistence. By default, node.startup is manual, which means the session does not reconnect automatically after a reboot . Setting it to automatic makes the iscsi service log in to the target at boot. Without this setting, a manually logged-in session disappears on restart, and any filesystem mounted from the LUN will fail to mount.

The initiator name is the identity. The file /etc/iscsi/initiatorname.iscsi contains the IQN that the initiator presents to every target. If this file is missing or the IQN is malformed, the target will reject the login or present no LUNs because no ACL matches the initiator’s identity .

a. Installing the initiator utilities

The package is iscsi-initiator-utils on RHEL-family systems and open-iscsi on Debian and Ubuntu. Both provide iscsid, iscsiadm, and the service units that manage them.

# RHEL / CentOS / Oracle Linux
sudo dnf install -y iscsi-initiator-utils

# Debian / Ubuntu
sudo apt update
sudo apt install -y open-iscsi

After installation, the iscsid service and the iscsi service are present. iscsid is the daemon that handles the protocol; iscsi is the service that logs in to targets marked for automatic startup. Enable both so they start at boot .

sudo systemctl enable --now iscsid
sudo systemctl enable iscsi

b. Configuring the initiator name

The initiator IQN is stored in /etc/iscsi/initiatorname.iscsi. The package generates one automatically, but in a managed environment you may want a predictable name. The format is the same as for targets: iqn.YYYY-MM.reverse-domain:optional-suffix .

# View the current initiator name
cat /etc/iscsi/initiatorname.iscsi
# Example output: InitiatorName=iqn.1994-05.com.redhat:client01

# To set a custom name, edit the file
sudo tee /etc/iscsi/initiatorname.iscsi <<'EOF'
InitiatorName=iqn.2024-01.com.example:client01
EOF

The IQN in this file is what the target sees when the initiator logs in. If the target’s ACL lists a different IQN, the login will succeed at the protocol level but the initiator will see no LUNs because the ACL does not match .

c. Discovering targets with SendTargets

Discovery sends a SendTargets request to a portal address and receives the list of targets the portal is willing to expose. The output is both displayed and stored in the local database.

# Discover targets on a specific portal
sudo iscsiadm -m discovery -t sendtargets -p 192.168.10.20

# Example output:
# 192.168.10.20:3260,1 iqn.2024-01.com.example:storage.disk01

The -m discovery mode with -t sendtargets is the standard discovery method for iSCSI . The output line shows the portal address, the TPGT (1 in this case), and the target IQN. If discovery succeeds but returns no targets, the portal is reachable but the target has no portals configured, or the target’s discovery_auth is rejecting the request.

Discovery can be repeated against multiple portals. Each discovered target is stored in /var/lib/iscsi/nodes/ and is available for login.

d. Logging in and verifying the session

Login establishes the session. The target authenticates the initiator if CHAP is configured, assigns a session ID, and makes the LUNs visible to the kernel.

# Log in to a specific target by IQN and portal
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 -l

# Log in to all discovered targets
sudo iscsiadm -m node -l

The -l flag performs the login. The -T flag specifies the target IQN, and -p specifies the portal. If -p is omitted, iscsiadm uses the portal stored from discovery .

After login, the session appears in iscsiadm -m session. The LUNs appear as new SCSI devices. Check dmesg or lsblk for the new device.

# Verify the session
sudo iscsiadm -m session
# Output: tcp: [1] 192.168.10.20:3260,1 iqn.2024-01.com.example:storage.disk01 (non-flash)

# Show detailed session information including LUNs
sudo iscsiadm -m session -P 3

# Check for the new block device
lsblk
# Look for a new sdX device with the size of the LUN

e. Configuring CHAP authentication

If the target requires CHAP, the credentials must be set before login. The configuration can be set per-target in the node database or globally in /etc/iscsi/iscsid.conf. The per-target method is safer because it does not affect other targets.

# Set CHAP credentials for a specific target
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.authmethod -v CHAP

sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.username -v client01

sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.password -v SecurePass123

The authmethod must be set to CHAP for the username and password to be used . The username must match the CHAP user configured in the target’s ACL, and the password must match exactly. For mutual CHAP, add username_in and password_in with the target’s CHAP credentials.

If discovery itself requires CHAP, configure the discovery.sendtargets.auth.* parameters separately.

f. Making the session persistent

A manually logged-in session does not survive a reboot. The node.startup setting controls whether iscsiadm logs in automatically at boot .

# Set automatic login for a specific target
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.startup -v automatic

# Verify the setting
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  -o show | grep startup

With node.startup=automatic, the iscsi service logs in to the target at boot. Ensure the service is enabled:

sudo systemctl enable iscsi
sudo systemctl enable iscsid

The iscsid daemon must be running before iscsi can log in. If the LUN contains a filesystem that must be mounted, add an /etc/fstab entry with the _netdev option so the mount waits for the network and the iSCSI session.

Complete Example Session

# ============================================
# PART 1: INSTALL THE INITIATOR UTILITIES
# ============================================
sudo dnf install -y iscsi-initiator-utils
sudo systemctl enable --now iscsid
sudo systemctl enable iscsi

# ============================================
# PART 2: SET THE INITIATOR NAME
# ============================================
sudo tee /etc/iscsi/initiatorname.iscsi <<'EOF'
InitiatorName=iqn.2024-01.com.example:client01
EOF

# This IQN must match the ACL configured on the target.

# ============================================
# PART 3: DISCOVER TARGETS
# ============================================
sudo iscsiadm -m discovery -t sendtargets -p 192.168.10.20

# Output:
# 192.168.10.20:3260,1 iqn.2024-01.com.example:storage.disk01
#
# The target is now recorded in the local discovery database.

# ============================================
# PART 4: CONFIGURE CHAP CREDENTIALS
# ============================================
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.authmethod -v CHAP

sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.username -v client01

sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.session.auth.password -v SecurePass123

# ============================================
# PART 5: LOG IN TO THE TARGET
# ============================================
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 -l

# Output: Logging in to [iface: default, target: iqn...storage.disk01,
#         portal: 192.168.10.20,3260]
#         Login to [iface: default, target: iqn...storage.disk01,
#         portal: 192.168.10.20,3260] successful.

# ============================================
# PART 6: VERIFY THE SESSION
# ============================================
sudo iscsiadm -m session
# tcp: [1] 192.168.10.20:3260,1 iqn...storage.disk01 (non-flash)

sudo iscsiadm -m session -P 3 | grep -A5 "Attached SCSI"
# Shows the SCSI disk, e.g. Host Number: 3, State: running
# Attached SCSI devices:
# Host Number: 3  State: running
# scsi3 Channel 00 Id 0 Lun: 0
#     Attached scsi disk sdb  State: running

# ============================================
# PART 7: CONFIRM THE BLOCK DEVICE
# ============================================
lsblk
# sdb should appear with the size of the exported LUN

# Check dmesg for the SCSI attach message
dmesg | grep -i "sd 3:0:0:0"
# sd 3:0:0:0: [sdb] Attached SCSI disk

# ============================================
# PART 8: SET AUTOMATIC LOGIN
# ============================================
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  --op=update -n node.startup -v automatic

# The session will reconnect at boot via the iscsi service.

# ============================================
# PART 9: VERIFY PERSISTENCE SETTINGS
# ============================================
sudo systemctl is-enabled iscsi
sudo systemctl is-enabled iscsid

sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 \
  -o show | grep startup
# node.startup = automatic

# ============================================
# PART 10: LOG OUT AND CLEAN UP (OPTIONAL)
# ============================================
# Log out from the target
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 -u

# Remove the node entry entirely
sudo iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 -o delete

The ten parts covered installation, initiator naming, discovery, CHAP configuration, login, session verification, device confirmation, automatic startup, persistence validation, and cleanup.

Quick Reference

The iscsiadm modes

Mode	Command	Purpose
Discovery	`iscsiadm -m discovery -t sendtargets -p IP`	Find targets on a portal
Node	`iscsiadm -m node`	Manage discovered target entries
Session	`iscsiadm -m session`	View active sessions
Iface	`iscsiadm -m iface`	Manage network interfaces

Login and logout

Command	Effect
`iscsiadm -m node -T IQN -p IP -l`	Log in to a specific target
`iscsiadm -m node -l`	Log in to all discovered targets
`iscsiadm -m node -T IQN -p IP -u`	Log out from a specific target
`iscsiadm -m session`	List active sessions

CHAP parameters

Parameter	Purpose
`node.session.auth.authmethod`	Set to `CHAP` to enable
`node.session.auth.username`	CHAP username for the initiator
`node.session.auth.password`	CHAP password for the initiator
`node.session.auth.username_in`	Target’s CHAP username (mutual)
`node.session.auth.password_in`	Target’s CHAP password (mutual)
`discovery.sendtargets.auth.*`	CHAP for discovery only

Persistence settings

Parameter	Value	Effect
`node.startup`	`manual`	No automatic login (default)
`node.startup`	`automatic`	Login at boot via `iscsi` service
`systemctl enable iscsi`	—	Enables automatic login service
`systemctl enable iscsid`	—	Enables the protocol daemon

Key files

File	Purpose
`/etc/iscsi/initiatorname.iscsi`	Initiator IQN
`/etc/iscsi/iscsid.conf`	Global defaults
`/var/lib/iscsi/nodes/`	Discovered target database
`/var/lib/iscsi/send_targets/`	Discovery records

Best Practices

✅ Do This:

# Set node.startup=automatic for any LUN that must persist
iscsiadm -m node -T IQN -p IP --op=update -n node.startup -v automatic # ✅

# Configure CHAP per-target, not globally
# This avoids breaking other targets if credentials differ
iscsiadm -m node -T IQN -p IP --op=update -n node.session.auth.authmethod -v CHAP # ✅

# Verify the session with -P 3 to confirm LUNs are attached
iscsiadm -m session -P 3                                               # ✅

# Use _netdev in /etc/fstab for filesystems on iSCSI LUNs
# /dev/sdb1 /data xfs defaults,_netdev 0 0                             # ✅

# Match the initiator IQN to the target's ACL exactly
cat /etc/iscsi/initiatorname.iscsi                                     # ✅

# Enable both iscsid and iscsi services
systemctl enable iscsid && systemctl enable iscsi                       # ✅

❌ Don’t Do This:

# Assume discovery is the same as login
# Discovery only records the target; no session exists
iscsiadm -m discovery -t sendtargets -p IP                             # ❌ (no -l)

# Leave node.startup=manual for production LUNs
# The session and any mounts will fail after reboot
# (default manual setting)                                              # ❌

# Set CHAP credentials in iscsid.conf globally for one target
# This applies to all targets and breaks ones with different credentials
# node.session.auth.username = client01 (in global config)              # ❌

# Mount a device path like /dev/sdb1 in fstab
# Device names change across reboots; use UUID or LVM
# /dev/sdb1 /data xfs defaults 0 0                                      # ❌

# Skip the ACL check on the target side
# Login succeeds but no LUNs appear if IQN mismatch
# (no ACL for initiator IQN)                                            # ❌

# Forget to enable the iscsi service after setting automatic startup
# The setting has no effect if the service does not run at boot
# systemctl disable iscsi                                               # ❌

Common Pitfalls

Pitfall	Why It Happens	Fix
Login succeeds but no LUNs appear	Target ACL does not include the initiator IQN	Check `/etc/iscsi/initiatorname.iscsi` against target ACL
Login fails with authentication error	CHAP credentials wrong, or `authmethod` not set to `CHAP`	Set `node.session.auth.authmethod=CHAP` and verify username/password
Session disappears after reboot	`node.startup=manual`	Set `node.startup=automatic` and enable `iscsi` service
`iscsiadm -m session` shows no sessions	Login was not performed, or session was logged out	Run `iscsiadm -m node -l`
Filesystem mount fails at boot	`_netdev` missing from `/etc/fstab`	Add `_netdev` option to the mount entry
Discovery returns no targets	Target has no portal configured, or discovery CHAP required	Check target portals; configure `discovery.sendtargets.auth.*`

Real-World Examples

1. Discover targets on a portal

iscsiadm -m discovery -t sendtargets -p 192.168.10.20

2. Log in to a specific target

iscsiadm -m node -T iqn.2024-01.com.example:storage.disk01 -p 192.168.10.20 -l

3. Log in to all discovered targets

iscsiadm -m node -l

4. Show active sessions

iscsiadm -m session

5. Show session details with LUNs

iscsiadm -m session -P 3

6. Set CHAP authentication method

iscsiadm -m node -T IQN -p IP --op=update -n node.session.auth.authmethod -v CHAP

7. Set CHAP credentials

iscsiadm -m node -T IQN -p IP --op=update -n node.session.auth.username -v client01
iscsiadm -m node -T IQN -p IP --op=update -n node.session.auth.password -v SecurePass123

8. Set automatic startup

iscsiadm -m node -T IQN -p IP --op=update -n node.startup -v automatic

9. Log out from a target

iscsiadm -m node -T IQN -p IP -u

10. Verify the block device

lsblk && dmesg | grep "Attached SCSI disk"

Visual

The initiator workflow

┌─────────────────────────────────────────────────────────────┐
│  INITIATOR WORKFLOW                                          │
│                                                              │
│  1. Set IQN (/etc/iscsi/initiatorname.iscsi)                │
│       │                                                      │
│       ▼                                                      │
│  2. Discover ── SendTargets ──► Target portal               │
│       │                            │                         │
│       │◄── Target IQN + portal ────┘                         │
│       │                                                      │
│       ▼                                                      │
│  3. Configure CHAP (if required)                             │
│       │                                                      │
│       ▼                                                      │
│  4. Login ── CHAP challenge ──► Target                       │
│       │◄── Session established ─┘                            │
│       │                                                      │
│       ▼                                                      │
│  5. Kernel sees /dev/sdX                                     │
│       │                                                      │
│       ▼                                                      │
│  6. Format, mount, or add to LVM                             │
└─────────────────────────────────────────────────────────────┘

Discovery vs login

┌─────────────────────────────────────────────────────────────┐
│  DISCOVERY VS LOGIN                                          │
│                                                              │
│  DISCOVERY                                                   │
│    iscsiadm -m discovery -t sendtargets -p IP                │
│    ├─ Contacts portal on TCP 3260                            │
│    ├─ Receives target IQN list                               │
│    └─ Stores in /var/lib/iscsi/nodes/                        │
│    Result: database entry, no session, no device             │
│                                                              │
│  LOGIN                                                       │
│    iscsiadm -m node -T IQN -p IP -l                          │
│    ├─ Reads database entry                                   │
│    ├─ Authenticates (CHAP if configured)                     │
│    ├─ Establishes TCP session                                │
│    └─ Kernel attaches SCSI device                            │
│    Result: active session, /dev/sdX visible                  │
└─────────────────────────────────────────────────────────────┘

CHAP credential locations

┌─────────────────────────────────────────────────────────────┐
│  CHAP CREDENTIAL LOCATIONS                                   │
│                                                              │
│  Session authentication (normal login):                      │
│    node.session.auth.authmethod = CHAP                       │
│    node.session.auth.username = client01                     │
│    node.session.auth.password = SecurePass123               │
│    → Target validates the initiator's IQN                    │
│                                                              │
│  Discovery authentication (SendTargets):                     │
│    discovery.sendtargets.auth.authmethod = CHAP              │
│    discovery.sendtargets.auth.username = client01           │
│    discovery.sendtargets.auth.password = SecurePass123      │
│    → Portal validates before returning target list           │
│                                                              │
│  These are independent. Discovery CHAP does not              │
│  authenticate the session login, and vice versa.             │
└─────────────────────────────────────────────────────────────┘

Session persistence flow

┌─────────────────────────────────────────────────────────────┐
│  PERSISTENCE                                                 │
│                                                              │
│  node.startup = manual (default)                             │
│    ├─ Login is one-time                                      │
│    ├─ Reboot → no session                                    │
│    └─ Mounted filesystem fails                               │
│                                                              │
│  node.startup = automatic                                    │
│    ├─ iscsi service enabled at boot                          │
│    ├─ iscsid starts                                          │
│    ├─ iscsi reads node database                              │
│    ├─ Logs in to targets marked automatic                    │
│    └─ Session restored, /dev/sdX reappears                   │
│                                                              │
│  Both iscsid and iscsi services must be enabled.             │
└─────────────────────────────────────────────────────────────┘

Summary

Item	Value
Package (RHEL)	`iscsi-initiator-utils`
Package (Debian)	`open-iscsi`
Initiator IQN file	`/etc/iscsi/initiatorname.iscsi`
Discovery command	`iscsiadm -m discovery -t sendtargets -p IP`
Login command	`iscsiadm -m node -T IQN -p IP -l`
Session verification	`iscsiadm -m session -P 3`
CHAP method parameter	`node.session.auth.authmethod = CHAP`
CHAP username	`node.session.auth.username`
CHAP password	`node.session.auth.password`
Persistence parameter	`node.startup = automatic`
Required services	`iscsid`, `iscsi`

Key takeaways:

Discovery and login are separate steps. Discovery populates a local database; login creates a session and attaches a block device. Running discovery alone produces no /dev/sdX.
The initiator IQN is the identity. It must match the target’s ACL exactly, or login succeeds but no LUNs appear.
CHAP credentials are set per-target, not globally. Setting them in the node database avoids breaking other targets with different credentials.
node.startup=automatic is required for persistence. Without it, the session does not reconnect after a reboot, and any mount from the LUN fails.
Both iscsid and iscsi services must be enabled. iscsid handles the protocol; iscsi performs the automatic logins at boot.
Filesystems on iSCSI LUNs need _netdev in /etc/fstab. This tells the mount system to wait for the network and the session before attempting to mount.

Remember: iSCSI initiator setup is a sequence of identity, discovery, authentication, and session establishment. The most common failure is a login that succeeds but produces no visible LUN, which almost always means the initiator IQN does not match the target’s ACL. Check the IQN first, then the CHAP credentials, then whether node.startup is set for persistence. A manually logged-in session is a temporary session; if the LUN holds data that must survive a reboot, the automatic startup setting and the _netdev mount option are not optional.

Was this helpful?

Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!