How to configure an iSCSI target and CHAP password protection

When to use this procedure

When it is time to export VDC volumes to external hosts. Storage with volumes can exist without iSCSI, but a host cannot connect to it: an access point — a target — is required. This procedure creates the VDC target, protects it with CHAP password authentication, and shows how to read its state.

CHAP is optional. A target can be created without it, and protection can be added later. But adding it is easier than removing it: the controller does not support removing CHAP, so it is best to decide in advance whether to use protection.

This procedure does not map volumes — it only prepares access. Mapping is described in "Connecting volumes over iSCSI".

Prerequisites

• The Unified Storage feature is enabled in the cluster options.
• VDC storage is enabled — see "How to create a VDC with Unified Storage".
• A portal group exists on the storage pool: without it, the iSCSI configuration form does not allow you to proceed — see "Initiator and portal groups".
• The Configure vDC Storage iSCSI privilege (13009) — granted only to the Cluster master role.
• The View vDC Storage iSCSI Detail privilege (13026) for reading the target page — also available to a VDC administrator within their VDCs.
• The VDC storage name differs from the storage name of every other VDC: the IQN is derived from the name, and the IQN must be unique within the cluster.
• vStack Center version — 3.0.4.

Step 1. Create a target

You can create the target in either of two places.

In the storage enablement wizard. The iSCSI readiness step shows pool readiness and creates the target when storage is enabled. The Skip button on this step enables storage without iSCSI.

Later, from the storage summary. Open the VDC card → Storage tab → Overview subtab. A Protocol Status card with the Not configured badge means there is no target.

1. Click Configure — the Configure iSCSI window opens.
2. Check the Portal Group attached to pool block: addresses and ports are shown in a read-only IP address / Port table. You do not select a portal group here — the group attached to the storage pool is used.
3. In the Auth (CHAP) block, select No authentication or Create Auth Group. For the latter, enter the set name and the first user — the fields are the same as in step 2.
4. Click Configure.

The target IQN is not set manually: the platform derives it from the storage name — the name segment of the root dataset after / is appended to the iqn.2024-01.io.vstack: prefix.

After the controller confirms, the badge changes to Configured, and the card shows Target IQN, Portal Group, and the number of LUNs. The target has no identifier: Configured itself means it is ready. The portal group and initiator group are associated with the target when the first volume is mapped, not at this point.

Step 2. Create a CHAP credential set

If No authentication was selected when the target was created, create the set on the target page.

1. Open the Storage tab → iSCSI subtab.
2. Click the Target card — the target page opens.
3. In the Auth Group section, click Create Auth Group.
4. Complete the form:

Field	What to specify
Name	Set name: 1–63 characters — lowercase Latin letters, digits, periods, and hyphens; unique within the VDC
User	One-way CHAP username, 1–255 characters
Secret	One-way CHAP secret, 1–255 characters
Mutual CHAP	Toggle for mutual authentication; enables the pair of fields below. The platform rejects a set without mutual credentials, so the toggle must be enabled
Mutual user, Mutual secret	Mutual CHAP username and secret, 1–255 characters; both must be filled in

5. Confirm creation.

Mutual CHAP is required. The SAN controller rejects a one-way credential set, so vStack Center requires Mutual user and Mutual secret to be filled in both when creating the set and whenever editing it.

Keep two constraints in mind from the start. First, the platform allows one credential set per group — an attempt to add a second entry is rejected. Second, secrets are write-only. Neither the interface nor the API returns them: the table shows the username and the mutual authentication indicator, but not the secret itself.

Step 3. Assign protection to the target

A set created on the target page is assigned to the target immediately — there is no separate association step. The Auth (CHAP) block in the Configure iSCSI window and on the wizard's iSCSI readiness step does the same.

The relationship is one-to-one: a target has one auth group, and assigning a new one replaces the previous one. The target page does not offer a choice of an existing set — this replacement is performed through the API (see "API methods").

CHAP cannot be removed from a target: the controller does not support this operation, so the interface has no clear button. To change protection, assign a different set to the target.

Step 4. View the set and its members

The Auth Group section on the target page shows the assigned set's name and a table of its users.

Column	What it shows
User	One-way CHAP username
Mutual CHAP	Whether the entry has mutual credentials

Each row has a menu with Edit and Delete actions; an Add button appears above the table.

If the username is known but the secret is lost, it cannot be recovered — set a new one as described in step 5.

Step 5. Change the secret

1. Open the menu in the user row and select Edit.
2. Set a new Secret. Leaving the field empty keeps the previous secret — use this to change only the mutual credentials.
3. Save the changes.

This also works for a set already assigned to a target: the controller changes the secret without recreating the target. However, the change affects all targets to which this set is assigned — they share it.

Step 6. Delete an entry or set

Delete a CHAP entry in its table row: row menu → Delete.

The interface does not support deleting an entire auth group. The platform does not allow a group assigned to a target to be deleted at all — first assign a different set to the target, then delete the released set through the API.

Verify the result

Open the target page: Storage tab → iSCSI subtab → Target card.

Expected after step 1: the badge on the Protocol Status card is Configured, Target IQN is filled in under Properties (the value can be copied), and Portal Group is specified. Expected after step 3: the Auth Group section shows the set name, and the table shows its user.

Empty values on the page follow one rule: an empty state rather than an error.

What you see	What it means
Not configured badge	The VDC has no target; the other fields are empty, and this is not an error
Target IQN is empty	iSCSI is not configured
Portal Group is empty	The portal group is not yet associated with the target — the association is created when the first volume is mapped
The Auth Group section offers Create Auth Group	CHAP is not assigned to the target
Active sessions is 0	There are no connections, or iSCSI is not configured
Active sessions is empty	The pool controller is unavailable; the rest of the page is displayed

Active sessions counts TCP sessions to the target: the addresses from which initiators have connected.

Another way to verify is the storage summary: Overview subtab, Properties card. It shows the storage name, pool, root dataset, capacity, list of protocols, and number of volumes. The actual mapping configuration is not displayed there — go to the target page and the Volumes list for that information.

Troubleshooting

What you see	Why	What to do
"Storage is not enabled for VDC" (-45013)	VDC storage is not enabled, so there is nothing to configure iSCSI for	Enable storage on the Storage tab, then configure iSCSI
"iSCSI is already configured for VDC" (-45014)	The VDC already has a target, and the invariant is one target per VDC	There is no need to configure it again: view its state on the target page
"Target already exists" (-45015)	The IQN is in use: this VDC's storage name matches another VDC's storage name, and the IQN is derived from the name	There is no iSCSI-side workaround — the root dataset name is set when storage is enabled and cannot be changed afterward
"iSCSI is not configured for VDC" (-45032)	There is no target in the VDC to assign CHAP to	Complete step 1
"Unknown auth group" (-45033)	No set with this identifier exists, or it belongs to another VDC	Check the set on the target page; the same response covers both cases — another VDC's set is not disclosed
"Auth group already exists" (-45034)	The set name is already in use in this VDC	Specify a different Name — names are unique within the VDC
"Invalid auth group parameters" (-45035)	The set failed validation	Keep one entry, fill in User, Secret, Mutual user, and Mutual secret, and keep the fields shorter than 255 characters; without mutual credentials, the set is rejected both at creation and when edited
"Auth group is in use by a target" (-45036)	The set is assigned to a target, and the controller cannot remove CHAP	Assign a different set to the target, then delete the released set
The pool controller did not respond or rejected the operation (-45020, -45021)	The pool is unavailable or rejected the secret change; the set remains unchanged	Check pool availability and retry the operation
"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)	Configuring a target requires the Configure vDC Storage iSCSI privilege (Cluster master role only); reading the page requires View vDC Storage iSCSI Detail	Sign in with an appropriate role; the same response is returned for a request for another VDC — its existence is not disclosed

See also

• Initiator and portal groups — the addresses on which the target listens and who is authorized to connect.
• Connecting volumes over iSCSI — how to export a volume to an initiator.
• VDC storage — model and architecture — where the IQN comes from and why there is one target per VDC.

API methods

API operations covered on this page: vdc-storage-iscsi-configure, vdc-storage-iscsi-get, vdc-storage-get, iscsi-auth-group-create, iscsi-auth-group-list, iscsi-auth-group-get, iscsi-auth-group-set, iscsi-auth-group-delete, iscsi-target-set-auth — see the API reference.