ProxMenux LogoProxMenux

Host: Add iSCSI target as Proxmox storage

Storage & Share · Host~10 minView script

Register an iSCSI target (from a SAN, TrueNAS / FreeNAS, Synology, a Windows Server target, any array that speaks iSCSI) as Proxmox storage. The exported LUNs appear as block devices and can host VM disk images at near-local performance over the network.

What this does

ProxMenux wraps pvesm add iscsi with a guided flow: it installs open-iscsi if needed, asks for the iSCSI portal (IP:port), runs iscsiadm --mode discovery --type sendtargets against it, lets you pick a target IQN, and registers the iSCSI storage in Proxmox. The iscsid service then keeps the iSCSI session alive across reboots.

iSCSI vocabulary (quick reference)

TermMeaning
PortalThe iSCSI service endpoint on the target server — an IP (or hostname) plus a TCP port. Default port is 3260; ProxMenux assumes it if you do not specify one.
TargetA single exported "server" inside the portal, identified by its IQN (iSCSI Qualified Name). One portal can host many targets.
IQNCanonical form is iqn.YYYY-MM.reverse.domain:identifier, for example iqn.2024-08.com.truenas:proxmox-pool. Both the target and the initiator have their own IQN.
LUNA block device inside a target (Logical Unit Number). A single target can expose several LUNs; each LUN appears as its own disk in Proxmox and can become a VM disk.
InitiatorThe client that connects to a target — in this case, your Proxmox host. The initiator has its own IQN stored in /etc/iscsi/initiatorname.iscsi. Targets typically only accept sessions from pre-authorised initiator IQNs.

Opening the tool

From ProxMenux's main menu, open Storage & Share Manager → Add iSCSI Target as Proxmox Storage. You will see this sub-menu with four options:

iSCSI Host Manager menu — Add / View / Remove / Test connectivity

How the script runs (Add flow)

The flow has two phases with clear separation between "setting up the initiator, discovering targets" and "actually registering storage in Proxmox". Unlike NFS / Samba, there is no auto-discovery on the subnet — you must know the portal address (iSCSI is not broadcast-friendly).

┌─────────────────────────────────────────────┐
│  PHASE 1 — Prepare initiator, discover      │
│  (nothing touched yet in storage.cfg)       │
└──────────────────┬──────────────────────────┘
                   ▼
      Dependency check
      └─ iscsiadm present? (open-iscsi package)
         If missing → apt-get install open-iscsi
                     + systemctl enable --now iscsid
                   │
                   ▼
      Portal entry (manual only)
      └─ user types  <ip>  or  <ip>:<port>
         If no ':' → ProxMenux appends ":3260"
                   │
                   ▼
      Reachability validation
      ├─ ping -c 1 -W 3 <host>          ── fail → abort
      └─ nc -z -w 3 <host> <port>       ── warn but continue
         (iSCSI over alternative ports may block nc)
                   │
                   ▼
      Target discovery
      iscsiadm --mode discovery --type sendtargets \
               --portal <ip:port>
      Extracts IQNs from stdout (lines matching ^iqn\.)
                   │
                   ▼
      Target selection
      ├─ 1 target found → auto-selected
      └─ 2+ targets    → menu
                   │
                   ▼
      Storage ID
      (default derived from last ':' segment of the IQN:
         "iscsi-<suffix-up-to-20-chars>")
                   │
                   ▼
      Content type (fixed — not a checklist)
      └─ images        iSCSI exposes block devices, so
                       only 'images' makes sense. No
                       backup/iso/vztmpl/rootdir/snippets.
                   │
   ┌──────── Cancel   OR   Confirm ────┐
   ▼                                   ▼
Exit, nothing        ┌─────────────────┴─────────────────┐
was changed          │  PHASE 2 — Register in Proxmox     │
                     └─────────────────┬─────────────────┘
                                       ▼
                       If storage ID already exists:
                       └─ ask "remove and recreate?"
                          └─ yes → pvesm remove <id>
                          └─ no  → abort
                                       ▼
                       pvesm add iscsi <id> \
                           --portal <ip:port> \
                           --target <iqn> \
                           --content images
                                       │
                                       ▼
                       iscsid opens a persistent session to
                       the target; LUNs appear in /dev/disk/
                       by-path/ip-<ip>:<port>-iscsi-<iqn>-lun-N
                                       │
                                       ▼
                       Proxmox auto-connects on every boot
                       via the node.startup=automatic flag
                       written by pvesm

Add iSCSI target as Proxmox storage

  1. Portal entry — type the IP or hostname of the iSCSI target server. Port 3260 is assumed unless you type host:port.
  2. Target discovery — ProxMenux calls iscsiadm --mode discovery --type sendtargets --portal &lt;ip:port&gt;. The server responds with every IQN it allows this initiator to see. If discovery fails, the script shows the exact error from iscsiadm and lists common causes (wrong IP, firewall, initiator IQN not authorised).
  3. Target selection — single target is auto-selected; multiple targets show a menu.
  4. Storage ID — default is iscsi-&lt;last IQN segment, 20 chars max&gt;. Only letters, digits, - and _.
  5. Content type — unlike NFS / Samba, iSCSI content is fixed to images. iSCSI exposes raw block devices, not a filesystem, so Proxmox only lets you host VM disks on it.

Authorise the Proxmox initiator on the target

Before the Add flow works end-to-end, the iSCSI target needs to know your Proxmox host. Get your initiator IQN:
cat /etc/iscsi/initiatorname.iscsi
Then add that IQN to the target's access list (in TrueNAS: Sharing → Block → Initiators Groups; in Synology: SAN Manager → iSCSI → Target → Edit → Initiators; etc.). If the initiator is not authorised, iscsiadm discovery returns an empty list or an authentication error.

Manual equivalent

The whole flow maps to these commands:

apt-get install -y open-iscsi
systemctl enable --now iscsid

# 1. discover targets on a portal
iscsiadm --mode discovery --type sendtargets \
         --portal 10.0.0.60:3260

# 2. register it in Proxmox
pvesm add iscsi myiscsi \
  --portal 10.0.0.60:3260 \
  --target iqn.2024-08.com.truenas:proxmox-pool \
  --content images

# 3. verify + see the block devices
pvesm status myiscsi
ls -la /dev/disk/by-path/ | grep iscsi

View configured iSCSI storages

Lists every iSCSI entry in Proxmox (pvesm status | awk '$2 == "iscsi"') with portal, target IQN, content type and live status.

Remove iSCSI storage

Runs pvesm remove &lt;storage-id&gt; after confirming portal, target and content. Only the Proxmox registration is removed — the iSCSI target itself is not touched and existing sessions on the kernel side may linger until the next reboot.

Existing VM disks on this iSCSI first

Removing an iSCSI storage while VMs still have disks on it leaves those VMs pointing at a disappeared store. Proxmox will flag the error, but the LUN data is untouched on the target — you can re-register the storage later to get the disks back. Still, move or back up the VMs first to be safe.

Test iSCSI connectivity

Runs a diagnostic pass: checks that iscsiadm is installed, prints your initiator IQN, confirms iscsid is running, pings each registered portal, probes its port, and reports pvesm status plus whether an iSCSI session is currently active (iscsiadm --mode session). Active session plus reachable portal but "inactive" in Proxmox usually means a stale state — try pvesm set &lt;id&gt; --disable 0.

Troubleshooting

"Cannot reach portal" but the server IP responds elsewhere

Ping failed on the portal address. Check you are reaching the storage network interface (iSCSI often lives on a separate VLAN / subnet from the management network). Also verify DNS if you typed a hostname.

"iSCSI discovery failed" from iscsiadm

The script shows the exact error. Most common causes:
  • Portal IP / port wrong (double-check, default is 3260).
  • iSCSI service not running on the target server.
  • Firewall blocks 3260 between Proxmox and the target.
  • Initiator IQN is not authorised on the target. Most frequent cause on enterprise arrays. Add your Proxmox IQN to the target's initiator ACL first.

No targets found but discovery succeeded

The server accepted your initiator but does not expose any target to it. Review the target's authentication / access controls — some arrays allow discovery for all IQNs but filter which targets each IQN can see.

LUNs do not appear in /dev/disk/by-path after registering

pvesm add iscsi succeeded but the kernel is not seeing block devices. Check iscsiadm --mode session — if no session is active, start one manually with iscsiadm --mode node --login. If a session exists but no LUNs appear, force a rescan: iscsiadm --mode session --rescan. If still nothing, the target probably has no LUNs assigned to this IQN yet (configure LUN mapping on the target).

CHAP authentication

ProxMenux does not expose the CHAP username / password fields in the interactive flow. If your target requires CHAP, register with ProxMenux first (discovery with CHAP may fail, but pvesm add will still write the entry), then add credentials manually: pvesm set &lt;id&gt; --username &lt;chap-user&gt; and edit /etc/iscsi/iscsid.conf with the password, then systemctl restart iscsid. This is a gap in the current script — documented here so you know what to do.

Related

ProxMenux Scripts: Previous
Add Samba share as Proxmox storage
ProxMenux Scripts: Next
Add local disk as Proxmox storage