iSCSI on XCP-ng - CLI Quick Start Guide

Linux
Audience
Public
Product
FlashBlade
FlashArray
Technology Integrations
Linux
Source Type
Documentation
Note:

For detailed explanations, alternative configurations, and troubleshooting: See XCP-ng Storage Documentation

Important:

Vendor Documentation Priority: This guide is for reference only. Always consult official vendor documentation for your distribution. Test thoroughly in a lab environment before production use.

Prerequisites:

  • XCP-ng 8.3 or newer

  • iSCSI storage array with portal IPs and target IQN

  • Dedicated storage network interfaces (recommended: separate NICs/VLANs)

  • Root access to all pool hosts

Note:

New to iSCSI? See the Storage Terminology Glossary.

Warning:

If using multiple interfaces on the same subnet, configure ARP settings. See ARP Configuration.

  1. Configure Storage Network Interfaces: Configure dedicated network interfaces for iSCSI traffic using Xen Orchestra or xe CLI. Replace <PIF_UUID> with your physical interface UUID and configure appropriate IP addressing. 
    # List available PIFs
xe pif-list

# Configure static IP on storage interface (example)
xe pif-reconfigure-ip uuid=<PIF_UUID> mode=static IP=<HOST_IP> netmask=<NETMASK>

# Verify interface configuration
xe pif-list params=uuid,device,IP,netmask
    Tip:

    Use xe pif-list to identify your storage interfaces. Dedicated NICs for iSCSI traffic provide better performance and isolation.

  2. Verify iSCSI and Multipath Tools: XCP-ng includes iSCSI and multipath tools by default. Verify they are available: 
    # Verify iscsi-initiator-utils is installed
rpm -qa | grep iscsi-initiator-utils

# Verify multipath tools
rpm -qa | grep device-mapper-multipath

# Enable and start services
systemctl enable --now iscsid multipathd
  3. Configure Multipath (If Required): If your storage equipment is not already in the default multipath configuration, add custom settings: 
    # Check if your storage is already configured
cat /etc/multipath.xenserver/multipath.conf | grep -i "<VENDOR>"

# If not present, create custom configuration
cat >> /etc/multipath/conf.d/custom.conf << 'EOF'
devices {
    device {
        vendor           "<VENDOR>"
        product          "<PRODUCT>"
        path_selector    "service-time 0"
        path_grouping_policy group_by_prio
        prio             alua
        hardware_handler "1 alua"
        failback         immediate
        rr_weight        uniform
        no_path_retry    0
    }
}
EOF

# Restart multipathd to apply
systemctl restart multipathd
    Important:

    Configuration in /etc/multipath/conf.d/custom.conf persists across updates. Never modify /etc/multipath.xenserver/multipath.conf directly.

  4. Enable multipathing at the pool level via Xen Orchestra or xe CLI: 
    # Via xe CLI - enable on pool
xe host-param-set uuid=<HOST_UUID> other-config:multipathing=true
xe host-param-set uuid=<HOST_UUID> other-config:multipathhandle=dmp
    Tip:

    In Xen Orchestra, go to Pool > Advanced tab and enable Multipathing for all XCP-ng hosts.

  5. Create iSCSI Storage Repository using Xen Orchestra (recommended) or xe CLI:

    Via Xen Orchestra (Recommended)

    1. Go to New > Storage.

    2. Select iSCSI as storage type.

    3. Enter portal IPs, target IQN, and authentication details.

    4. Select the LUN to use.

    5. Click Create.

    Via xe CLI 

    # Discover targets
iscsiadm -m discovery -t sendtargets -p <PORTAL_IP_1>:3260
iscsiadm -m discovery -t sendtargets -p <PORTAL_IP_2>:3260

# Create iSCSI SR (lvmoiscsi driver)
xe sr-create name-label="iSCSI Storage" type=lvmoiscsi shared=true \
    device-config:target=<PORTAL_IP_1>,<PORTAL_IP_2> \
    device-config:targetIQN=<TARGET_IQN> \
    device-config:SCSIid=<SCSI_ID>
    Note:

    The SCSIid can be found using iscsiadm -m session -P 3 after a manual login, or via your storage array's management interface.

  6. Verify Configuration: 
    # Verify iSCSI sessions
iscsiadm -m session

# Verify multipath devices
multipath -ll

# Verify SR status in XCP-ng
xe sr-list type=lvmoiscsi
xe pbd-list sr-uuid=<SR_UUID>
    Note:

    Quick Reference

    Command Description
    sudo iscsiadm -m session List active iSCSI sessions
    sudo iscsiadm -m discovery -t sendtargets -p <IP>:3260 Discover targets
    sudo iscsiadm -m node -T <IQN> -p <IP>:3260 --login Login to target
    sudo iscsiadm -m node -T <IQN> -p <IP>:3260 --logout Logout from target
    sudo multipath -ll Show multipath devices

For production deployments, consult the official XCP-ng documentation:

Additional Resources: