How to Add iSCSI Storage in Proxmox VE (Step-by-Step with LVM)

Introduction

Most Proxmox VE storage guides walk you through NFS shares, local ZFS pools, or a directory on a spare disk. Those cover the common home-lab and small-office cases, but once you're running a real SAN — a NetApp filer, a TrueNAS box, a Dell/EMC array, or even a Linux box exporting LVM volumes with targetcli — the protocol you'll actually be reaching for is iSCSI. It's the block-storage backbone behind most shared Proxmox VE clusters that don't use Ceph, and it's also the one storage type that trips people up the most, because Proxmox treats a raw iSCSI LUN very differently from a ZFS pool or an NFS export.

This guide covers the full path: connecting Proxmox VE to an iSCSI target, understanding why a bare iSCSI LUN isn't actually useful for running VMs on its own, and layering LVM on top so you get a proper shared storage pool that supports multiple VM disks, thin allocation of the LUN's space, and cluster-wide locking. It applies to Proxmox VE 8.x and 9.x — the iSCSI and LVM storage plugins haven't changed in any way that affects this workflow between those release lines.

What You Will Learn

What iSCSI actually is, and how it differs from NFS, ZFS, and Ceph as a Proxmox VE storage backend
Why Proxmox VE won't let you store more than one VM disk directly on a raw iSCSI LUN
How to install and configure the iSCSI initiator on your Proxmox VE nodes
How to discover and log in to an iSCSI target, both through the GUI and the CLI
How to layer LVM on top of the LUN so it becomes usable shared storage for VM disks
How CHAP authentication works and when you should enable it
What multipathing is for, and when you actually need it
The troubleshooting steps for the most common failure modes: targets that won't discover, LUNs that won't appear, and locking errors in a cluster

What Is iSCSI, and Why Use It With Proxmox VE?

iSCSI ("Internet SCSI") is a protocol that carries SCSI commands over a regular TCP/IP network. In practice, it lets a storage array on one machine present a block device — a LUN, or Logical Unit Number — to another machine as if it were a locally attached disk. There's no filesystem involved on the wire; the initiator (your Proxmox VE node) sees raw blocks, exactly like it would with a local SATA or NVMe drive.

That's the key difference from NFS. NFS hands you a filesystem — Proxmox stores files (qcow2 disk images, ISOs) inside a directory the NFS server manages. iSCSI hands you a block device with no filesystem at all. Proxmox VE has to put something on top of it to make it usable, and that something is almost always LVM.

Here's how the common Proxmox VE storage backends compare:

Backend	What it hands you	Snapshots	Thin provisioning	Typical use case
NFS	A shared filesystem	Yes (qcow2)	Yes (qcow2)	Simple shared storage, ISOs, backups
ZFS (local)	A local pool	Yes, instant	Yes	Single-node storage with checksums and snapshots
Ceph RBD	A distributed block device	Yes	Yes	Hyper-converged clusters, no external SAN
iSCSI (raw)	A single raw block device	No	No	Rarely used alone — one giant disk for one VM
iSCSI + LVM	A volume group carved from the LUN	No (unless volume-chain snapshots are enabled on PVE 9+)	No (thick LVM) or yes (LVM-thin, but LVM-thin can't be shared across nodes)	Shared SAN storage for clustered VM disks

People reach for iSCSI when they already own a SAN appliance — from a vendor like NetApp, Dell, Synology, or QNAP, or a self-built Linux/FreeBSD box exporting LUNs — and want multiple Proxmox VE nodes to share it for live migration and HA, without adopting Ceph. It's also frequently faster to set up than Ceph for a small cluster, since you're not standing up a distributed storage system, just pointing at one that already exists.

The Catch: Raw iSCSI Storage Only Holds One Disk

This is the part that catches almost everyone the first time. If you add an iSCSI target directly as a Proxmox VE storage (type iscsi), the storage will show up, but it can only allow content type images, and it maps the entire LUN to a single VM disk. There's no way to carve that LUN into multiple VM disks, because Proxmox isn't managing any structure inside it — it's handing the whole block device to one guest.

That's fine if you have one huge LUN per VM, which some SAN-heavy shops genuinely do. For everyone else, the fix is to put LVM on top of the iSCSI LUN. LVM turns the single block device into a volume group, and Proxmox can then carve out as many logical volumes from it as you need — one per VM disk — while still keeping the whole thing shared and cluster-safe.

Prerequisites

A Proxmox VE 8.x or 9.x host (or cluster) with network access to the iSCSI target
An iSCSI target already exported on your SAN, with at least one LUN, and the target's IQN and portal IP address (or hostname) in hand
If your SAN uses CHAP authentication, the CHAP username and secret
Root or a user with the Datacenter.Audit and Sys.Modify / storage-admin privileges on Proxmox VE
A dedicated storage network is strongly recommended — iSCSI traffic is unencrypted by default and benefits from being isolated on its own VLAN or physical NICs, separate from VM traffic and the Proxmox cluster (Corosync) network

Step 1: Confirm the iSCSI Initiator Is Installed

Proxmox VE ships with open-iscsi pre-installed on a standard install, since the GUI relies on it. You can confirm it's present and check the node's initiator name:

dpkg -l | grep open-iscsi
cat /etc/iscsi/initiatorname.iscsi

If for some reason it's missing (rare, but possible on a minimal or scripted install), install it with:

apt update
apt install open-iscsi

Every Proxmox VE node has its own unique initiator name (an IQN). If your SAN restricts access by initiator IQN, you'll need to register each node's IQN on the storage array before it can log in — do this for every node in the cluster that should reach the storage, not just the one you're configuring from.

Step 2: Discover the Target (Optional but Useful for Verification)

Before adding the storage through Proxmox, it's worth confirming the target is reachable and see what LUNs it's presenting. From the shell on any node:

iscsiadm -m discovery -t sendtargets -p 192.0.2.50:3260

Replace 192.0.2.50 with your portal's IP. A working target replies with one or more target IQNs, something like:

192.0.2.50:3260,1 iqn.2026-01.com.example:storage.lun01

If this hangs or returns nothing, that's a network or firewall problem — check that TCP port 3260 is open between the Proxmox node and the SAN before going any further. Proxmox's own "Add iSCSI Storage" dialog performs this same discovery step internally, so if it fails here, it'll fail in the GUI too.

You don't need to log in manually with iscsiadm -m node --login — Proxmox VE's iSCSI plugin manages the login/logout session lifecycle itself once you add the storage. Manually logging in first is only useful for troubleshooting connectivity.

Step 3: Add the iSCSI Storage Through the GUI

Log in to the Proxmox VE web interface and select Datacenter in the left-hand tree.
Go to Storage, click Add, and choose iSCSI from the dropdown.
Fill in the fields:
- ID — a name for this storage entry, e.g. iscsi-san01
- Portal — the SAN's IP address or hostname (add :3260 only if it uses a non-default port)
- Target — select the target IQN from the dropdown; Proxmox performs discovery live and populates this list
- Nodes — leave as "All" if every node in the cluster has network access to the SAN, otherwise restrict it
- Leave Use LUNs directly unchecked — this is exactly the setting that controls whether Proxmox tries to use the raw LUN for a single VM disk (checked) or expects you to layer LVM on top (unchecked, the normal path)
Click Add.

At this point the storage exists, but if you left "Use LUNs directly" unchecked, its content type is effectively unusable until you add the LVM layer in the next step — that's expected, not an error.

Step 4: Add the iSCSI Storage Through the CLI

The equivalent pvesm command, if you'd rather script this or you're doing it over SSH:

pvesm add iscsi iscsi-san01 \
  --portal 192.0.2.50 \
  --target iqn.2026-01.com.example:storage.lun01 \
  --content none

--content none is deliberate here — it tells Proxmox this storage entry exists purely as the base for an LVM volume group, not to store VM images or ISOs directly. You can confirm the entry with:

cat /etc/pve/storage.cfg

You should see a block like:

iscsi: iscsi-san01
        portal 192.0.2.50
        target iqn.2026-01.com.example:storage.lun01
        content none

Step 5: Layer LVM on Top of the LUN

This is the step that turns a single raw LUN into usable, shareable storage for VM disks.

Through the GUI:

Go back to Datacenter > Storage > Add, and this time choose LVM.
ID — e.g. lvm-san01
Base storage — select the iSCSI storage you just created (iscsi-san01)
Base volume — select the specific LUN to build the volume group on
Volume group name — a new name Proxmox will create, e.g. vg_san01
Check Shared — this is critical in a cluster; it tells Proxmox every node may access this volume group concurrently, and enables the cluster-wide locking that prevents two nodes from writing to the same logical volume at once
On Proxmox VE 9.x, expand Advanced and consider enabling Snapshots as volume-chain — this is a newer feature that adds vendor-agnostic snapshot support for block storage like iSCSI/LVM, which historically couldn't snapshot at all

Through the CLI, the equivalent is:

pvesm add lvm lvm-san01 \
  --base iscsi-san01:0.0.0.scsi- \
  --vgname vg_san01 \
  --shared 1 \
  --content images,rootdir

The exact --base value is the volume identifier Proxmox assigned to the LUN under the iSCSI storage — list them with pvesm list iscsi-san01 if you're not sure of the exact string. Once this command finishes, Proxmox has created an LVM physical volume on the LUN, initialized a volume group named vg_san01, and registered it as shared storage. You'll see it appear in the storage tree with content type images and rootdir, meaning it can now hold VM disks and container root filesystems.

Step 6: Verify With a Test VM

Create a small test VM and, on the Hard Disk step, pick your new lvm-san01 storage as the target. Once it's created, confirm the logical volume actually landed on the SAN-backed volume group:

lvs vg_san01
vgs vg_san01

You should see a new logical volume matching the VM's disk (named like vm-100-disk-0) and a volume group size matching your LUN's capacity minus whatever overhead LVM reserves. If you have a second node in the cluster, migrate the VM to it — a live migration completing without needing to copy the disk (since it's already visible to both nodes) confirms the shared storage is genuinely shared, not just configured twice by coincidence.

CHAP Authentication

If your SAN requires CHAP (Challenge-Handshake Authentication Protocol), the iSCSI storage add dialog in Proxmox VE doesn't expose CHAP credential fields directly — you configure them through the initiator's own config on each node, in /etc/iscsi/iscsid.conf:

node.session.auth.authmethod = CHAP
node.session.auth.username = your-chap-username
node.session.auth.password = your-chap-secret

After editing this file, restart the initiator service so it picks up the new credentials before Proxmox attempts to log in to the target:

systemctl restart open-iscsi
systemctl restart iscsid

Do this on every node that needs to reach the target, and confirm the file's permissions stay restrictive (0600) since it holds a plaintext secret.

Do You Need Multipath?

If your SAN and network only expose a single path to each LUN — one portal IP, one NIC — you don't need multipath, and adding it would just add complexity for no benefit. Multipath matters when you have multiple physical paths to the same LUN: two SAN controllers, two switches, two NICs per node, wired so that any single link or controller failure doesn't take storage access down entirely.

Setting up multipath-tools and a correct /etc/multipath.conf for your specific SAN model is enough of its own topic that it deserves separate treatment — the short version is that you install multipath-tools, blacklist everything except your SAN's LUNs by WWID, and let multipathd present a single /dev/mapper/mpathX device that you then point the LVM base volume at instead of the raw iSCSI session device. If you're running a single-path setup today and are only now planning to add redundant paths, treat it as a project of its own rather than bolting it on mid-migration.

Troubleshooting

Discovery hangs or times out

This is almost always network, not Proxmox. Confirm TCP/3260 reachability with nc -zv <portal-ip> 3260, check that the SAN's access control list includes this node's initiator IQN, and rule out a firewall or VLAN misconfiguration between the storage network and the node.

Target discovers fine, but the LUN doesn't show up in Proxmox

Rescan the SCSI bus on the node so the kernel picks up the new LUN, then refresh the storage view:

iscsiadm -m session --rescan
pvesm scan iscsi <portal-ip>

"Volume group already exists" when adding LVM

This usually means a previous attempt partially created the volume group, or another node in the cluster already claimed it. Check vgs on every node before retrying, and don't run pvcreate/vgcreate manually on more than one node against the same LUN — let Proxmox's pvesm add lvm command do it once.

VM freezes or pauses during a SAN blip

By default, open-iscsi's session recovery timeout (node.session.timeo.replacement_timeout, in iscsid.conf) is fairly conservative. A brief network hiccup can cause QEMU to pause I/O rather than fail outright, which looks like a frozen VM for the duration of the timeout. Tuning this value down (commonly to 15–30 seconds) makes the failure surface faster instead of hanging silently, at the cost of being less tolerant of very brief blips — set it based on how flaky your storage network actually is, not a copy-pasted number.

Locking errors during migration ("volume is already locked")

Confirm the LVM storage entry actually has shared set — check /etc/pve/storage.cfg for the shared flag on the LVM block. Without it, Proxmox assumes the storage is node-local and its cluster-wide locking never engages, which produces exactly this symptom when two nodes touch the volume group.

Frequently Asked Questions

Can I snapshot VMs on iSCSI + LVM storage?

Historically no — thick LVM has no native snapshot support, unlike ZFS or qcow2 on NFS. Proxmox VE 9.x introduces an optional "snapshots as volume-chain" mode for this storage type that provides a working, vendor-agnostic alternative, but it changes how disk images are laid out and should be enabled before you have production data on the storage, not retrofitted onto an existing pool.

Should I use LVM-thin instead of regular LVM on the iSCSI LUN?

No — LVM-thin is not cluster-shareable in Proxmox VE. If you need shared storage for live migration and HA, use regular (thick) LVM on top of the iSCSI LUN, as described in this guide. LVM-thin is only appropriate for local, single-node storage.

iSCSI vs NFS — which should I pick?

If your SAN offers both and you don't have a strong reason otherwise, NFS is usually simpler to operate and gives you qcow2-based snapshots for free. iSCSI is worth the extra setup when you need raw block performance, when your SAN vendor's iSCSI implementation is more mature than its NFS one, or when you're standardizing on block storage for other reasons (Fibre Channel migration path, existing SAN tooling, etc).

Do I need a separate physical network for iSCSI traffic?

Strongly recommended, not strictly mandatory. iSCSI is latency-sensitive and unencrypted by default; sharing a NIC with VM traffic or the Corosync cluster network invites both performance problems and, if the network is untrusted, exposure of storage traffic. A dedicated VLAN at minimum, dedicated NICs if you can spare them.

What happens if I check "Use LUNs directly" instead of layering LVM?

Proxmox will let you assign the entire LUN as one VM's disk directly, with no filesystem or volume management in between. It's a legitimate option if you provision one dedicated LUN per VM from the SAN side and want to avoid the LVM layer entirely, but it doesn't scale to "many VMs on one shared LUN," which is the more common goal.

Conclusion

iSCSI storage in Proxmox VE looks like it should work the same way NFS or ZFS storage does — add it, point VMs at it — but the raw LUN itself is only ever one disk. The extra step of layering LVM on top is what actually makes it into general-purpose shared storage, and it's a five-minute step once you know it's coming. Get the initiator, discovery, and CHAP settings right on every node in the cluster, keep the volume group's shared flag set, and you end up with the same live-migration and HA capabilities you'd get from NFS or Ceph, backed by whatever SAN your organization already owns.

Vormox is an independent virtualization management platform built on Proxmox VE. Proxmox® and Proxmox VE® are trademarks of Proxmox Server Solutions GmbH. Vormox is not affiliated with, endorsed by, or sponsored by Proxmox.

How to Add iSCSI Storage in Proxmox VE (With LVM on Top for VM Disks)