ESXi iSCSI Storage Configuration Guide

Overview

This guide provides step-by-step instructions for configuring ESXi hosts to connect to Synology NAS iSCSI storage with CHAP authentication. All commands have been tested on ESXi 8.0.3.

Environment Details

  • Synology NAS: DS918+ (IP: 192.168.10.5)
  • iSCSI Target: iqn.2025-01.net.markalston:vmwcluster
  • Authentication: CHAP (one-way)
  • Username: vmwcluster
  • Password: rad10head1565

Storage Configuration

iSCSI Target Settings:

  • Header Digest: Disabled (unnecessary in controlled lab environment)
  • Data Digest: Disabled (Btrfs already provides checksums)
  • Multiple Sessions: Disabled (VMFS is not cluster-aware)

Configured LUNs:

  1. NUC-High-Performance: 4TB (RAID 0, thick provisioned)
  2. Development-Testing: 1TB (RAID 1, thin provisioned)
  3. Archive-Storage: 900GB (RAID 1, thin provisioned)

Prerequisites

Network Configuration

Ensure VMkernel interfaces are configured on each ESXi host:

  • vmk0: Management Network (VLAN 10)
  • vmk7: Storage Network (VLAN 30) - Optional for dedicated storage traffic

Synology iSCSI Target

Verify the following on your Synology NAS:

  1. iSCSI Target service is enabled
  2. Target vmwcluster-target is created with CHAP authentication
  3. All three LUNs are mapped to the target
  4. Target is accessible from ESXi management network

Step-by-Step Configuration

Step 1: Enable iSCSI Software Adapter 

# SSH to ESXi host
ssh root@<ESXi_HOST_IP>

# Enable software iSCSI adapter
esxcli iscsi software set --enabled=true

# Verify adapter is enabled and get adapter name
esxcli iscsi adapter list

Expected Output:

Adapter  Driver     State   UID            Description
-------  ---------  ------  -------------  -----------
vmhba64  iscsi_vmk  online  iscsi.vmhba64  iSCSI Software Adapter

Step 2: Configure Network Portals 

# Bind iSCSI adapter to management network (vmk0)
esxcli iscsi networkportal add -A vmhba64 -n vmk0

# Optional: Bind to dedicated storage network (vmk7)
# esxcli iscsi networkportal add -A vmhba64 -n vmk7

# Verify network portal configuration
esxcli iscsi networkportal list

Expected Output:

vmhba64
   Adapter: vmhba64
   Vmknic: vmk0
   IPv4: 192.168.10.X
   Vlan ID: 0
   Link Up: true

Step 3: Configure iSCSI Discovery 

# Add Synology NAS as discovery target
esxcli iscsi adapter discovery sendtarget add -A vmhba64 -a 192.168.10.5:3260

# Verify discovery target is added
esxcli iscsi adapter discovery sendtarget list -A vmhba64

Step 4: Configure CHAP Authentication 

# Set CHAP authentication (one-way, required)
esxcli iscsi adapter auth chap set -A vmhba64 -d uni -l required -N vmwcluster -S rad10head1565

# Verify CHAP configuration
esxcli iscsi adapter auth chap get -A vmhba64

Command Parameters:

  • -d uni: Unidirectional CHAP (one-way authentication)
  • -l required: CHAP authentication is required
  • -N vmwcluster: CHAP username
  • -S rad10head1565: CHAP password

Step 5: Discover iSCSI Targets and LUNs 

# Trigger target discovery
esxcli iscsi adapter discovery rediscover -A vmhba64

# Verify targets are discovered
esxcli iscsi adapter target portal list -A vmhba64

# Rescan storage adapter to discover LUNs
esxcli storage core adapter rescan -A vmhba64

# List discovered iSCSI devices
esxcli storage core device list | grep -E "(naa\.|SYNOLOGY)"

Expected Targets:

Adapter  Target                                   IP            Port  Tpgt
-------  ---------------------------------------- ------------  ----  ----
vmhba64  iqn.2025-01.net.markalston:vmwcluster  192.168.10.5  3260  1

Expected LUNs:

naa.6001405c6045e3cdae12d4bb7d9913d3  # 4TB - NUC-High-Performance
naa.60014055ae90980dc514d40c4d8a75d2  # 1TB - Development-Testing
naa.60014050fe87884dccc3d485bdbe1bd0  # 900GB - Archive-Storage

Step 6: Verify iSCSI Session 

# Check active iSCSI sessions
esxcli iscsi session list

# Verify session details
esxcli iscsi session connection list

Expected Session:

vmhba64,iqn.2025-01.net.markalston:vmwcluster,00023d000001
   Adapter: vmhba64
   Target: iqn.2025-01.net.markalston:vmwcluster
   AuthenticationMethod: chap

Step 7: Create VMFS Datastores

Important Note: Do not use :1 suffix with NAA device paths. Use the full device path without partition numbers.

# Method 1: Using vmkfstools (creates partition automatically)
vmkfstools -C vmfs6 -b 1m -S NUC-High-Performance \
/vmfs/devices/disks/naa.6001405c6045e3cdae12d4bb7d9913d3

vmkfstools -C vmfs6 -b 1m -S Development-Testing \
/vmfs/devices/disks/naa.60014055ae90980dc514d40c4d8a75d2

vmkfstools -C vmfs6 -b 1m -S Archive-Storage \
/vmfs/devices/disks/naa.60014050fe87884dccc3d485bdbe1bd0

Alternative Method 2: Using partedUtil + vmkfstools

# Create GPT partition table
partedUtil setptbl /vmfs/devices/disks/naa.6001405c6045e3cdae12d4bb7d9913d3 gpt \
"1 2048 8388574 AA31E02A400F11DB9590000C2911D1B8 vmfs 0"

# Create VMFS datastore on partition
vmkfstools -C vmfs6 -S NUC-High-Performance \
/vmfs/devices/disks/naa.6001405c6045e3cdae12d4bb7d9913d3:1

Step 8: Verify Datastore Creation 

# List all datastores
esxcli storage filesystem list

# Check datastore capacity and usage
df -h | grep vmfs

Expected Output:

Mount Point                                        Volume Name      UUID
/vmfs/volumes/637a6b2e-12345678-abcd-ef0123456789  NUC-High-Performance  637a6b2e-12345678-abcd-ef0123456789
/vmfs/volumes/637a6b2e-87654321-dcba-fe9876543210  Development-Testing   637a6b2e-87654321-dcba-fe9876543210
/vmfs/volumes/637a6b2e-11111111-aaaa-bbbb11111111  Archive-Storage       637a6b2e-11111111-aaaa-bbbb11111111

Troubleshooting

Common Issues

1. CHAP Authentication Errors

Error: Login failed

Solution: Verify CHAP credentials and syntax

# Check current CHAP settings
esxcli iscsi adapter auth chap get -A vmhba64

# Reset and reconfigure CHAP
esxcli iscsi adapter auth chap set -A vmhba64 -D
esxcli iscsi adapter auth chap set -A vmhba64 -d uni -l required -N vmwcluster -S rad10head1565

2. No LUNs Discovered

Error: esxcli storage core device list shows no iSCSI devices

Solution: Force rescan and check session

# Check iSCSI session status
esxcli iscsi session list

# Force storage rescan
esxcli storage core adapter rescan -A vmhba64
esxcli storage core adapter rescan --all

# Restart hostd if needed
/etc/init.d/hostd restart

3. VMFS Creation Failures

Error: Device path name is not a valid path

Solution: Use device path without partition suffix

# Incorrect (with :1 suffix)
vmkfstools -C vmfs6 -S MyDatastore /vmfs/devices/disks/naa.xxxxxxxxxxxx:1

# Correct (without :1 suffix)
vmkfstools -C vmfs6 -S MyDatastore /vmfs/devices/disks/naa.xxxxxxxxxxxx

4. Network Portal Issues

Error: Network portal not binding to correct interface

Solution: Remove and re-add network portal

# Remove existing portal
esxcli iscsi networkportal remove -A vmhba64 -n vmk0

# Re-add with correct interface
esxcli iscsi networkportal add -A vmhba64 -n vmk0

Verification Commands 

# Complete system check
echo "=== iSCSI Adapter Status ==="
esxcli iscsi adapter list

echo "=== Network Portals ==="
esxcli iscsi networkportal list

echo "=== Discovery Targets ==="
esxcli iscsi adapter discovery sendtarget list -A vmhba64

echo "=== Active Sessions ==="
esxcli iscsi session list

echo "=== Discovered Devices ==="
esxcli storage core device list | grep SYNOLOGY

echo "=== VMFS Datastores ==="
esxcli storage filesystem list | grep vmfs

Configuration Script

Save the following as configure-iscsi.sh for automated deployment:

#!/bin/bash
# ESXi iSCSI Configuration Script

# Configuration variables
SYNOLOGY_IP="192.168.10.5"
CHAP_USERNAME="vmwcluster"
CHAP_PASSWORD="rad10head1565"
ISCSI_ADAPTER="vmhba64"

# Enable iSCSI software adapter
echo "Enabling iSCSI software adapter..."
esxcli iscsi software set --enabled=true

# Add network portal (management network)
echo "Configuring network portal..."
esxcli iscsi networkportal add -A $ISCSI_ADAPTER -n vmk0

# Add discovery target
echo "Adding discovery target..."
esxcli iscsi adapter discovery sendtarget add -A $ISCSI_ADAPTER -a $SYNOLOGY_IP:3260

# Configure CHAP authentication
echo "Configuring CHAP authentication..."
esxcli iscsi adapter auth chap set -A $ISCSI_ADAPTER -d uni -l required -N $CHAP_USERNAME -S $CHAP_PASSWORD

# Trigger discovery
echo "Discovering targets..."
esxcli iscsi adapter discovery rediscover -A $ISCSI_ADAPTER

# Rescan storage
echo "Rescanning storage..."
esxcli storage core adapter rescan -A $ISCSI_ADAPTER

# Display discovered devices
echo "=== Discovered iSCSI Devices ==="
esxcli storage core device list | grep SYNOLOGY

echo "iSCSI configuration completed successfully!"
echo "Next step: Create VMFS datastores on the discovered LUNs"

Best Practices

Security

  • Use strong CHAP passwords (minimum 12 characters)
  • Consider enabling mutual CHAP for enhanced security
  • Restrict iSCSI target access to specific initiator IQNs

Performance

  • Use dedicated storage network (VLAN 30) for iSCSI traffic when possible
  • Enable jumbo frames if supported by network infrastructure
  • Monitor storage latency and adjust queue depths if needed

Backup and Recovery

  • Document NAA identifiers for disaster recovery
  • Backup ESXi configuration including iSCSI settings
  • Test failover scenarios regularly

Document Version: 1.0 Last Updated: August 23, 2025 Tested Environment: ESXi 8.0.3, Synology DS918+ DSM 7.x

This project is for educational and home lab purposes.