How to map a volume over iSCSI and remove the mapping

When to use this procedure

When a volume has been created but the host cannot see it yet. Mapping is the last step in the sequence: it adds the volume to the VDC target under the selected LUN number and limits its visibility to one initiator group. Before this step, the volume exists and consumes quota but is not accessible to anyone.

The reverse operation is unmapping. It removes the LUN from the target but leaves the volume in place: no data is deleted. Unmapping is needed when the volume must be kept but access to it must be blocked or changed. When a mapped volume is deleted, vStack Center removes the mapping automatically.

Prerequisites

• The Unified Storage feature is enabled in the cluster options.
• An iSCSI target is configured for the VDC — see "How to configure an iSCSI target and CHAP password protection".
• A portal group exists on the VDC storage pool — see "Initiator and portal groups".
• The volume has been created and is not yet mapped: its Status in the Volumes list is Unmapped (see "VDC volumes").
• The Map vDC Volume privilege for mapping and Unmap vDC Volume for unmapping — both are available to the Cluster master role and to a VDC administrator within their VDC.
• vStack Center version — 3.0.4.

Step 1. Select a LUN number and initiator group

The LUN number is unique within the target and is in the range 0..255. The mapping form automatically supplies an available number; numbers already in use are shown in the LUN ID field under Properties on the pages of this VDC's mapped volumes.

Use an existing initiator group or create one during mapping — both options are available in the same selection row in the form.

What you need	What to select in the form	When it is useful
Export the volume to hosts already defined in a group	An existing group in the Initiator Group list	The group is reused; membership is edited separately on its page
Create a group for this volume immediately	Create and fill in the membership in place	The first mapping in a VDC; saves a trip to another screen

Step 2. Map the volume

1. Open the VDC card → Storage tab → Volumes subtab and click the volume name.
2. In the Initiator Group Mapping section, click Map volume.
3. Complete the form:

Field	What to specify
Protocol	iSCSI; the NVMe option is unavailable in this version and marked Coming soon
LUN ID	An available number in 0..255; the field is already filled in with a suggested value
Initiator Group	An existing group or Create — then fill in Group name, Allowed Initiators (IQN), and Authorized networks

4. Confirm the mapping.

You do not select a portal group in the form: the group attached to the VDC storage pool is used.

The form waits for the entire operation to complete, not just for it to be accepted. During this wait, the pool controller executes a sequence of steps in a deliberate order:

1. The initiator group is created, if creation was requested.
2. The "target — portal group — initiator group" association is created, if it does not yet exist.
3. The volume is added to the target as a LUN.
4. LUN visibility is limited to this initiator group.

Masking comes last because the mask is applied to a LUN that has already been added. The volume is considered mapped only after all steps succeed: until the sequence completes, its Status remains Unmapped. If the mask cannot be applied, the added LUN is removed by a compensating step — no partial mapping remains.

Step 3. Check isolation

The mask limits LUN visibility to one initiator group: other groups on the same target cannot see this volume. A volume is exported to exactly one group — it cannot be mapped to a second group.

This suggests a practical approach: to expand the set of hosts, add IQNs to the already associated group rather than unmapping the volume. On the volume page, use the Edit group members button in the Initiator Group Mapping section. The changes affect the volume immediately.

caution

An initiator group is a shared resource: editing membership through Edit group members affects all volumes mapped to this group.

You cannot change the group of a mapped volume in a single operation. To change the group, use Unmap, then Map volume with a different group.

Step 4. Remove the mapping

1. Open the volume page.
2. In the Initiator Group Mapping section, click Unmap.
3. Confirm unmapping in the dialog.

The unmapping sequence mirrors mapping and consists of two steps: first the LUN mask is removed, then the LUN itself. This order is required — the mask is not automatically removed with the LUN, and reversing the order would leave a dangling association. If the controller reports that it has no LUN or mask, this is considered successful: the records are cleared and the discrepancy is resolved.

The initiator group, target, and "target — portal group — initiator group" association survive unmapping. The association is reused for the next mapping, so reconnecting the same volume requires less work than the first connection.

Verify the result

Stay on the volume page.

Expected after step 2: the header shows Mapped; Properties now contains Protocol, LUN ID with the specified number, and Target with a link to the target page. The Initiator Group Mapping section shows the group name and the Initiators and Authorized networks subcards.

Expected after step 4: the header shows Unmapped, the mapping section shows "Volume is not mapped" and the Map volume button, and Protocol under Properties is None.

The initiator indicator in the Initiators subcard reflects a comparison of group membership with the controller: Disconnected means the entry exists in vStack Center records but not on the controller.

Troubleshooting

What you see	Why	What to do
"iSCSI is not configured for VDC" (-45032)	The VDC has no target, so there is nowhere to add the LUN	Configure iSCSI on the Overview subtab of the Storage tab
"Unknown portal group" (-45010)	The portal group was not found or is not on this VDC's storage pool	Check the group's pool in the cluster's Unified Storage → Protocols → iSCSI section, in the Pool column
"LUN ID … is already in use on target …" (-45029)	The number is used by another volume on the same target; the message shows the target and number	Specify an available number in the range 0..255 — numbers already in use are shown under Properties for mapped volumes
"Volume is already mapped" (-45027)	The volume is already mapped, and a volume is exported to exactly one group	Expand the associated group's membership through Edit group members instead of creating a second mapping
"Volume is not mapped" (-45028)	There is nothing to unmap: the volume is not mapped	Check the volume's Status in the Volumes list — unmapping has probably already completed
"Unknown volume" (-45026)	The volume does not exist, belongs to another VDC, or has not yet been confirmed by the controller	Refresh the Volumes list; the same response covers all three cases — another VDC's volume is not disclosed
"Unknown initiator group" (-45022)	The selected group does not exist or belongs to another VDC	Select a group from your VDC's Initiator Groups table
"Initiator group already exists" (-45023)	The new group name is already in use in this VDC	Specify a different Group name or select an existing group
"Invalid initiator group parameters" (-45025)	The new group's membership failed validation	Check the name, IQN format, and CIDR format
"Invalid volume map parameters" (-45031)	The parameter set does not match the protocol	Check that LUN ID is in 0..255 and that exactly one group is selected — either an existing group or a new one with a nonempty initiator list
"Volume map protocol is out of scope: nvme" (-45030)	The NVMe protocol is not supported in this version	Mapping is available only over iSCSI; there is no workaround
"Storage is not enabled for VDC" (-45013)	VDC storage is not enabled	Enable storage on the Storage tab
The pool controller did not respond or rejected the operation (-45020, -45021)	The pool is unavailable or rejected a step in the sequence	During mapping, the volume remains unmapped; during unmapping, the mapping record is retained; check pool availability and retry
Unmapping rejected with a message from the platform	The controller rejected removal of the mask or LUN and passed the reason through unchanged	The mapping record is retained and the volume remains mapped — investigate the cause on the pool
"Unified Storage feature is disabled" (-45001)	The Unified Storage feature is disabled in the cluster options	The cluster administrator must enable it; while the feature is disabled, storage operations are rejected
"Access denied" (-403)	The Map vDC Volume or Unmap vDC Volume privilege is missing, or another VDC is open	Work within your VDC; the response does not disclose whether another VDC exists

See also

• VDC volumes — volume creation, the card, and deletion.
• Initiator and portal groups — the access rules that mapping relies on.
• VDC storage — model and architecture — mapping invariants and access separation.

API methods

API operations covered on this page: vdc-volume-map, vdc-volume-unmap, vdc-list-volumes, vdc-volume-get, iscsi-initiator-group-set — see the API reference.