iSCSI Initiator Setup

This guide covers configuring open-iscsi initiators on PiVirt hypervisor nodes to automatically discover, authenticate, and connect to remote iSCSI SAN targets.

Prerequisites

# Install open-iscsi
apt-get install -y open-iscsi

# Load kernel modules
modprobe iscsi_tcp
modprobe iscsi_ibft

# Start iscsid service
systemctl enable --now iscsid

Discover Targets

SendTargets Discovery

# Discover targets on portal
iscsiadm -m discovery -t sendtargets -p 10.0.1.10:3260

# Output example:
# 10.0.1.10:3260,1 iqn.2024-01.hu.pilab:iscsiman.target-01

Using pvcli

# Discover targets
pvcli storage initiator discover --portal 10.0.1.10:3260

Login to Target

Manual Login

# Login to target
iscsiadm -m node -T iqn.2024-01.hu.pilab:iscsiman.target-01 -p 10.0.1.10:3260 -l

# Output:
# Logging in to [iface: default, target: iqn.2024-01.hu.pilab:iscsiman.target-01, portal: 10.0.1.10,3260]
# Login to [iface: default, target: iqn.2024-01.hu.pilab:iscsiman.target-01, portal: 10.0.1.10,3260] successful.

Using pvcli

# Login to target
pvcli storage initiator login \
  --target iqn.2024-01.hu.pilab:iscsiman.target-01 \
  --portal 10.0.1.10:3260

Configure CHAP Authentication

Configure CHAP

# Edit iscsid.conf
cat > /etc/iscsi/iscsid.conf <<EOF
# CHAP authentication
node.session.auth.authmethod = CHAP
node.session.auth.username = iscsi-user
node.session.auth.password = iscsi-password

# Discovery CHAP (if required)
discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = iscsi-user
discovery.sendtargets.auth.password = iscsi-password
EOF

# Restart iscsid
systemctl restart iscsid

Using pvcli

# Configure CHAP
pvcli storage initiator configure \
  --target iqn.2024-01.hu.pilab:iscsiman.target-01 \
  --chap-user iscsi-user \
  --chap-password iscsi-password

Configure Auto-Login

Enable Auto-Login

# Set node startup to automatic
iscsiadm -m node -T iqn.2024-01.hu.pilab:iscsiman.target-01 -p 10.0.1.10:3260 --op update -n node.startup -v automatic

# Verify
iscsiadm -m node -T iqn.2024-01.hu.pilab:iscsiman.target-01 -p 10.0.1.10:3260 | grep startup

Verify Connection

Check Sessions

# List active sessions
iscsiadm -m session -P 3

# Output example:
# Target: iqn.2024-01.hu.pilab:iscsiman.target-01
#     Current Portal: 10.0.1.10:3260,1
#     Persistent Portal: 10.0.1.10:3260,1
#             **********
#             Interface:
#             **********
#             Iface Name: default
#             Iface Transport: tcp
#             Iface Initiatorname: iqn.1993-08.org.debian:01:abcdef123456
#             **********
#             Portal:
#             **********
#             Portal: 10.0.1.10:3260
#             Portal Group: 1
#             **********
#             Target:
#             **********
#             Target: iqn.2024-01.hu.pilab:iscsiman.target-01
#             LUN: 0
#             LUN: 1

Check Block Devices

# List iSCSI devices
lsblk | grep sd

# Check device details
lsblk -d -o name,model,serial,wwn /dev/sdb

Logout from Target

Manual Logout

# Logout from target
iscsiadm -m node -T iqn.2024-01.hu.pilab:iscsiman.target-01 -p 10.0.1.10:3260 -u

Using pvcli

# Logout from target
pvcli storage initiator logout \
  --target iqn.2024-01.hu.pilab:iscsiman.target-01

Rescan for New LUNs

Rescan Sessions

# Rescan all sessions
iscsiadm -m session --rescan

Using pvcli

# Rescan sessions
pvcli storage initiator rescan

Configure Multipath

Install multipath-tools

apt-get install -y multipath-tools

Configure multipath

# Create multipath configuration
cat > /etc/multipath.conf <<EOF
defaults {
    user_friendly_names yes
    find_multipaths smart
    path_checker tur
    path_grouping_policy group_by_prio
    prio alua
    failback immediate
}

devices {
    device {
        vendor "LIO-ORG"
        product "*"
        path_checker tur
        hardware_handler "1 alua"
    }
}
EOF

# Restart multipathd
systemctl restart multipathd

Verify Multipath

# Check multipath devices
multipath -ll

# Output example:
# mpatha (360050764008181c60000000000000001) dm-0 LIO-ORG,iscsiman.target-01
# size=100G features='0' hwhandler='1 alua' wp=rw
# |-+- policy='service-time 0' prio=50 status=active
# | `- 6:0:0:0 sdb 8:16 active ready running
# `-+- policy='service-time 0' prio=10 status=enabled
#   `- 7:0:0:0 sdc 8:32 active ready running

Monitoring

Check Session Status

# Check session status
iscsiadm -m session -P 1

# Check connection status
iscsiadm -m session -P 3 | grep -A5 "Portal"

Check Performance

# Check I/O stats
iostat -x /dev/sdb 1

# Check throughput
fio --name=iscsi-test --ioengine=libaio --iodepth=16 \
  --rw=randread --bs=4k --direct=1 --size=1G \
  --filename=/dev/sdb

Troubleshooting

Login Failed

# Check iscsid status
systemctl status iscsid

# Check CHAP credentials
cat /etc/iscsi/iscsid.conf | grep -i chap

# Check target accessibility
nc -zv 10.0.1.10 3260

Connection Lost

# Check network connectivity
ping 10.0.1.10

# Check iscsid logs
journalctl -u iscsid -f

# Reconnect
iscsiadm -m node -T iqn.2024-01.hu.pilab:iscsiman.target-01 -p 10.0.1.10:3260 -l

Multipath Issues

# Check multipath status
multipath -ll

# Check multipathd logs
journalctl -u multipathd -f

# Restart multipathd
systemctl restart multipathd

Related

• Storage Guide
• iSCSI Target Setup
• Multipath Configuration