Skip to main content

How to manage initiator and portal groups

When to use this procedure​

When you need to define who connects to VDC storage and through which addresses. The two groups answer two different questions. An initiator group defines "who is authorized": a list of host IQNs and the networks from which they are allowed to connect. A portal group defines "where the target listens": a set of "address + TCP port" pairs on the pool.

The difference is reflected both in ownership scope and in where the groups appear in the interface. An initiator group belongs to a VDC — the VDC administrator manages it on the Storage tab. A portal group belongs to a pool and affects all VDCs on that pool, so it is in the cluster's Unified Storage section. Only the Cluster master role can create and delete portal groups. A VDC administrator can also read portal group membership, across all pools in the cluster.

Both groups are needed before the first volume is mapped. Mapping itself is described in "Connecting volumes over iSCSI".

Prerequisites​

  • The Unified Storage feature is enabled in the cluster options.
  • VDC storage is enabled — initiator groups reside within the storage.
  • To create and delete portal groups — the Cluster master role with the iSCSI Create Portal Group (13004) and iSCSI Delete Portal Group (13005) privileges.
  • To read portal groups — the iSCSI View Portal Group (13006) and iSCSI List Portal Groups (13007) privileges; these are also granted to a VDC administrator across the entire cluster.
  • For initiator groups — a Unified Storage domain privilege scoped to your VDC.
  • The IQNs of initiator hosts and the networks from which they connect are known.
  • vStack Center version — 3.0.4.

Initiator groups​

Step 1. Create a group​

  1. Open the VDC card → Storage tab → iSCSI subtab.
  2. Above the Initiator Groups table, click Create IG.
  3. In the Create Initiator Group window, fill in the fields:
FieldWhat to specify
Group name1–63 characters: lowercase Latin letters, digits, periods, and hyphens; unique within the VDC
Allowed Initiators (IQN)A list of host IQNs; add each row using the Add link; IQNs can be up to 223 characters
Authorized networksA list of networks in CIDR notation from which connections are allowed
  1. Confirm creation.

The pool is not specified in the form — it is taken from the VDC storage. The group has no intermediate "creating" state: it appears in the table only after the controller confirms. If the group is in the list, the controller knows it.

Step 2. View the VDC groups​

The Initiator Groups table on the iSCSI subtab shows this VDC's groups in summary form: Name, Allowed Initiators, Authorized Networks, Status. The membership columns contain counts: the number of initiators and networks in the group.

The group page shows the full membership: click a row in the table. The page has two tables — Allowed Initiators (IQN) and Authorized Networks — each with its own pagination and Add button.

Step 3. Change group membership​

  1. Open the group page.
  2. For initiators: Add adds rows; the row menu provides Edit and Delete.
  3. For networks: use the same actions in the Authorized Networks table.
  4. To rename the group: Actions → Edit Group name.

The platform applies the entire new membership, not a difference: the controller makes the change by recreating the group with the same identifier. Changes immediately affect volumes exported to this group — there is no need to unmap and remap volumes.

caution

An initiator group is a shared resource. Editing its membership affects all volumes mapped to this group, not just the volume whose page you came from.

If membership has not changed, the controller is not called: if a name is specified, only the name changes. If the controller rejects the recreation step, the previous membership is retained.

Step 4. Delete a group​

  1. On the group page, open Actions → Delete.
  2. Confirm deletion.

A group associated with a target cannot be deleted: the platform reports how many targets are using it. The "target — portal group — initiator group" association is created when the first volume is mapped and then exists independently. The Unmap button removes the volume mapping but does not affect the association, so the group remains in use after all mappings are removed. It is released only when the VDC is deleted. If the controller reports that it has no such group, deletion is also considered successful. The records are cleared.

Portal groups​

Step 5. Create a portal group​

  1. In the cluster tree, open Unified Storage → Protocols tab → iSCSI selector.
  2. In the Portal groups list, click Create portal group.
  3. Complete the form:
FieldWhat to specify
Name1–256 characters
PoolA cluster pool; the selected pool determines which VDC the group can serve
PortalsA repeating block with at least one row: IP address (IPv4) and Port in the range 1000–65535, with a default of 3260. The Add link adds a row
  1. Click Create.

There is no need to create portals in advance: a portal is not an independent object; it exists only as a row in the group's membership. Duplicate "address + port" pairs are consolidated into one, and pairs already known to the cluster are reused.

The group is immutable: the platform does not support editing the membership of an existing group. To change the set of addresses, create a new group and move the mappings to it.

caution

A portal group belongs to a pool, not a VDC. All VDCs whose storage resides on this pool can see and use it, so changing the set of addresses is a cluster-level operation.

Step 6. View portal groups​

The Portal groups list shows three columns: Name, Pool, and Portals — the number of portals in the group. For groups created before pool associations were introduced, the Pool column is empty: these are legacy records, not a failure. The list supports search, sorting by column, pagination, and CSV export.

Click a group name — its read-only card opens on the right: Name, Pool, and a Portals table with IP address and Port columns. The card has no input fields or membership editing buttons for the same reason — group membership is immutable. The Delete portal group action is at the bottom of the card.

The section is visible only to the Cluster master role: without cluster overview privileges, the Unified Storage node does not appear in the tree at all.

Step 7. Delete a portal group​

Deletion can be initiated in two places — using the trash icon in the list row or the Delete portal group action in the card. Both open the same confirmation dialog with the group name.

Once the controller confirms, the group's membership, the group itself, and any portals that do not belong to other groups are removed from the records. Clients that used these addresses immediately lose path discovery — the confirmation dialog therefore warns about this.

A legacy group without a pool is deleted only from the database: the controller is not called in this case, and the response is immediate.

Verify the result​

After steps 1–4, open the initiator group page. Expected: the Allowed Initiators (IQN) table contains exactly the IQNs specified in your last edit, and Authorized Networks contains the specified networks.

After steps 5–7, refresh the Portal groups list. Expected after creation: the list contains a row with your group name, a filled-in Pool column, and a nonzero count in the Portals column. Expected after deletion: the row is no longer in the list.

An additional check for mapped volumes is the Initiators subcard on the volume page: Disconnected for an initiator means that the entry exists in vStack Center records but not on the controller.

Troubleshooting​

What you seeWhyWhat to do
"Portal group not found. Refresh the list." (-45010)The group no longer exists — the displayed list is outdatedRefresh the Portal groups list. When mapping a volume, the same code means something different: the group exists but is on a different pool, not the VDC storage pool
"Portal group … is in use by a target and cannot be deleted." (-45016)The group is associated with a target; deletion does not reach the controllerRemove the mappings that use this target, or keep the group: the "target — portal group" association is created once and reused
"Unknown initiator group" (-45022)The group does not exist or belongs to another VDCCheck the group in your VDC's Initiator Groups table; the same response covers both cases — another VDC's group is not disclosed
"Initiator group already exists" (-45023)The group name is already in use in this VDCSpecify a different Group name — names are unique within the VDC, not the cluster
"Initiator group is in use by … target(s)" (-45024)The group is associated with a target; the message shows the number of targets using itThe Unmap button removes the volume mapping but does not remove the association. The group is released only when the VDC is deleted, so leave it in place until then
"Invalid initiator group parameters" (-45025)Membership failed validationEnter at least one initiator and one network, and check the IQN format, CIDR format, and group name
"Storage is not enabled for VDC" (-45013)Initiator groups reside in VDC storage, which does not existEnable storage on the Storage tab
Pool not found (-45002)The selected pool does not exist or has no nameSelect the pool again; pool states are described in the "Storage pools" section
The form does not accept the values (-32602)A value cannot be parsed: an empty or overly long name, no portal rows, or an invalid IPv4 addressCheck the fields against the rules in step 5; the form flags a duplicate "address + port" pair on the second matching row
The pool controller did not respond or rejected the operation (-45020, -45021)The pool is unavailable or rejected the group recreation step; membership is unchangedCheck pool availability and retry the operation
Rejection with a message from the platformThe controller returned its own reason — for example, that it already has a group with this numberThe group does not appear in the list, and no discrepancy remains between the records and the controller; resolve the cause and retry
"Access denied" (-403)Creating and deleting portal groups are available only to the Cluster master role; for initiator groups, a privilege is missing or the VDC is outside your scopeSign in with a cluster-level role or work within your VDC; this rejection does not block reading portal groups

See also​

API methods​

API operations covered on this page: iscsi-initiator-group-create, iscsi-initiator-group-list, iscsi-initiator-group-get, iscsi-initiator-group-set, iscsi-initiator-group-delete, iscsi-portal-group-create, iscsi-portal-group-list, iscsi-portal-group-get, iscsi-portal-group-delete — see the API reference.