TABLE OF CONTENTS

• Prerequisites
• Configure Initiator Name (IQN)
• Discovery - Find Available Targets
• Review Discovered Targets
• Configure Authentication (CHAP)
• Enable Automatic Login (Persistence)
• Login (Connect) to Target
• Verify Connection
• Identify the New Device
• Make Filesystem Persistent
• Management Commands
• Configuration Files
• Troubleshooting
• Performance Tuning
• Complete Example Workflow

Prerequisites

Install iSCSI initiator utilities on your Linux system:

# RHEL/CentOS/Rocky/Fedora
sudo yum install iscsi-initiator-utils

# Debian/Ubuntu
sudo apt-get install open-iscsi

# Start and enable the iSCSI service
sudo systemctl start iscsid
sudo systemctl enable iscsid

1. Configure Initiator Name (IQN)

Each iSCSI initiator must have a unique identifier called an IQN (iSCSI Qualified Name).

# View your initiator IQN
cat /etc/iscsi/initiatorname.iscsi

# Default format: iqn.YYYY-MM.reverse.domain:unique-name
# Example: iqn.2024-01.com.example:initiator01

2. Discovery - Find Available Targets

Discover available iSCSI targets on your storage server:

# Discover targets on iSCSI portal/server
sudo iscsiadm -m discovery -t sendtargets -p <TARGET_IP>:3260

# Example
sudo iscsiadm -m discovery -t sendtargets -p 192.168.1.100:3260

Expected output format:

192.168.1.100:3260,1 iqn.2024-01.com.storage:lun1

3. Review Discovered Targets

# List all discovered targets (nodes)
sudo iscsiadm -m node

# Show detailed info for specific target
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260

# Example
sudo iscsiadm -m node -T iqn.2024-01.com.storage:lun1 -p 192.168.1.100:3260

4. Configure Authentication (if required - CHAP)

If your iSCSI target requires authentication, configure CHAP credentials:

# Set CHAP authentication method
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.auth.authmethod -v CHAP

# Set CHAP username
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.auth.username -v <USERNAME>

# Set CHAP password
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.auth.password -v <PASSWORD>

For mutual CHAP (bidirectional authentication):

# Set initiator username for mutual CHAP
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.auth.username_in -v <INITIATOR_USERNAME>

# Set initiator password for mutual CHAP
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.auth.password_in -v <INITIATOR_PASSWORD>

5. Enable Automatic Login (Persistence)

Configure the target to automatically connect at system boot:

# Set node to automatically login at boot
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.startup -v automatic

# Verify the setting
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 | grep node.startup

6. Login (Connect) to Target

Establish the connection to the iSCSI target:

# Login to specific target
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 --login

# Login to ALL discovered targets configured for automatic login
sudo iscsiadm -m node --loginall=automatic

# Example
sudo iscsiadm -m node -T iqn.2024-01.com.storage:lun1 -p 192.168.1.100:3260 --login

7. Verify Connection

Check that the iSCSI session is active and the device is available:

# Show active iSCSI sessions
sudo iscsiadm -m session

# Detailed session information
sudo iscsiadm -m session -P 3

# Check kernel messages for iSCSI activity
dmesg | grep -i iscsi

# List new block devices
lsblk

# Show iSCSI-specific device paths
ls -l /dev/disk/by-path/ | grep iscsi

# Check multipath configuration (if using multipathing)
sudo multipath -ll

8. Identify the New Device

Find the device name assigned to your iSCSI LUN:

# List SCSI devices
lsblk -S
lsscsi

# Show detailed device information
sudo fdisk -l /dev/sdX

# Display device by iSCSI path
ls -l /dev/disk/by-path/ | grep iscsi

The new device will typically appear as /dev/sdb, /dev/sdc, etc.

9. Make Filesystem Persistent (Optional)

Create a filesystem and configure automatic mounting:

# Create ext4 filesystem on the device
sudo mkfs.ext4 /dev/sdX

# Create mount point
sudo mkdir -p /mnt/iscsi

# Mount the filesystem
sudo mount /dev/sdX /mnt/iscsi

# Get the UUID of the device
sudo blkid /dev/sdX

# Add to /etc/fstab for automatic mounting at boot
# Note: Use UUID for reliability, and _netdev to wait for network
echo "UUID=<your-uuid> /mnt/iscsi ext4 _netdev 0 0" | sudo tee -a /etc/fstab

Management Commands

Show Status

# Display active iSCSI sessions with basic info
sudo iscsiadm -m session -P 1

# Show all configured nodes (targets)
sudo iscsiadm -m node --op show

Logout (Disconnect)

# Logout from specific target
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 --logout

# Logout from all active sessions
sudo iscsiadm -m node --logoutall=all

Delete/Remove Target Configuration

# Remove specific target from configuration
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 --op delete

# Remove all target configurations
sudo iscsiadm -m node --op delete

Rescan for LUN Changes

# Rescan all active sessions for new/changed LUNs
sudo iscsiadm -m session --rescan

# Rescan specific session by session ID
sudo iscsiadm -m session -r <SID> --rescan

Configuration Files

Troubleshooting

Check Service Status

# Check if iSCSI daemon is running
sudo systemctl status iscsid
sudo systemctl status iscsi

View Logs

# Follow iSCSI daemon logs in real-time
sudo journalctl -u iscsid -f

# View system messages for iSCSI events
sudo tail -f /var/log/messages | grep iscsi

Test Network Connectivity

# Test basic connectivity to target
ping <TARGET_IP>

# Test if port 3260 is accessible
telnet <TARGET_IP> 3260
# or
nc -zv <TARGET_IP> 3260

Check Firewall Rules

# Firewalld (RHEL/CentOS/Fedora)
sudo firewall-cmd --list-all

# iptables
sudo iptables -L -n | grep 3260

Generate Debug Information

# Capture detailed session information for support
sudo iscsiadm -m session -P 3 > /tmp/iscsi-debug.txt

Performance Tuning (Optional)

Optimize iSCSI performance for high-throughput workloads:

# Increase queue depth (more outstanding I/O operations)
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.cmds_max -v 256

sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.queue_depth -v 128

# Adjust timeout values
sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.session.timeo.replacement_timeout -v 120

sudo iscsiadm -m node -T <TARGET_IQN> -p <TARGET_IP>:3260 \
  --op=update -n node.conn[0].timeo.noop_out_timeout -v 5

Complete Example Workflow

Here's a complete step-by-step example for connecting to an iSCSI target:

# Step 1: Discover available targets
sudo iscsiadm -m discovery -t st -p 192.168.1.100:3260

# Step 2: Configure automatic login on boot
sudo iscsiadm -m node -T iqn.2024-01.com.storage:lun1 -p 192.168.1.100:3260 \
  --op=update -n node.startup -v automatic

# Step 3: Login to the target
sudo iscsiadm -m node -T iqn.2024-01.com.storage:lun1 -p 192.168.1.100:3260 --login

# Step 4: Verify the connection
sudo iscsiadm -m session
lsblk

# Step 5: Create filesystem and mount (assuming device is /dev/sdb)
sudo mkfs.ext4 /dev/sdb
sudo mkdir -p /mnt/iscsi
sudo mount /dev/sdb /mnt/iscsi

# Step 6: Add to fstab for persistent mounting
UUID=$(sudo blkid -s UUID -o value /dev/sdb)
echo "UUID=$UUID /mnt/iscsi ext4 _netdev 0 0" | sudo tee -a /etc/fstab

# Step 7: Verify everything is working
df -h /mnt/iscsi

Key Points to Remember

• Port 3260 is the standard iSCSI port
• Use node.startup = automatic for persistent connections across reboots
• Always use the _netdev option in /etc/fstab for network-mounted filesystems
• Authentication (CHAP) is optional but recommended for security
• Target IQN format: iqn.YYYY-MM.reverse.domain:identifier
• Always verify connections with iscsiadm -m session before attempting to use devices