Generic iSCSI Pools (Existing LUNs)
Use this page when you want to attach LUNs that already exist on your own iSCSI target to Karios VMs. Each LUN becomes a data disk of one VM. Your data stays on your target.
If you want Karios to create the disks on a SAN array instead, use iSCSI Pools on a Managed Array (COMSTAR). For shared concepts (portals, paths, health), see iSCSI Storage.
UI path: Control Center -> Storage -> Instance Storage
When to Use
You have data on LUNs of an existing iSCSI target and want a VM to use it as a disk.
You manage the target yourself, with any vendor’s software or appliance.
You want Karios to attach and detach LUNs, not to create or change them.
What Karios Does and Does Not Do
Karios does:
Log every host in the zone in to your target and scan for the LUNs it exports.
List each LUN with its number, identity, size, paths, and state.
Attach a LUN to one VM as a data disk, and detach it again.
Watch each LUN and warn you if it goes missing, changes identity, or shrinks.
Karios never:
Creates, resizes, wipes, or deletes a LUN.
Changes the target’s configuration, ACLs, or CHAP settings.
Reads, checks, or formats what is on a LUN. Whatever is on it becomes the VM’s disk.
Before You Start
[ ] You are a platform administrator. Every generic iSCSI task, including viewing the LUNs, is limited to the platform administrator.
[ ] The platform setting
mount.disabled.storage.poolistrue. See Task 1.[ ] The target has its LUNs created and exported. LUNs must use a 512-byte logical block size. A LUN with any other block size cannot be attached.
[ ] The LUNs are not write-protected on the target.
[ ] The target is not used by another pool in the zone. One target serves one pool.
[ ] If you use CHAP, the target offers CHAP with SHA-256 or SHA3-256. Karios hosts never offer MD5, so an MD5-only target refuses every login.
[ ] CHAP secrets are 12 to 16 bytes long. For Mutual CHAP, the target’s secret differs from the initiator’s.
[ ] The storage network and portals meet the checklist in iSCSI Storage.
Task 1: Check the Platform Setting
When to Use: Do this once, before your first generic iSCSI pool.
Purpose: Make sure hosts keep the pool connected after they reconnect.
Steps:
Open
All Settings.Search for
mount.disabled.storage.pool.Set it to
trueif it is not already.
Expected Outcome:
The setting reads
true.
If this fails:
If the create later says the setting is false, set it to
trueand retry. Karios refuses the pool, because a host that reconnects would drop it and every VM start there would fail.
Task 2: Prepare the Target ACL
When to Use: Do this before you create the pool, and again when you add a host to the zone.
Purpose: Allow every Karios host to log in and see the LUNs.
Steps:
Open
Control Center -> Storage -> Instance Storageand clickAdd Instance Storage.Set
ProtocoltoiscsiandDrivertogeneric (attaches LUNs your target already exports).Pick the
Zone. The form listsHosts that will log inwith each host’s initiator IQN. Use the copy button next to each IQN.On your target, add every listed IQN to the ACL and export the LUNs to each of them, on every portal.
Note
A host that has not reported its IQN yet shows not reported yet. Its IQN appears
after the first attempt. A refused create also names every host and its IQN.
Expected Outcome:
Every host IQN in the zone is in the target’s ACL with the LUNs exported to it.
Task 3: Create the Pool
When to Use: Do this after Tasks 1 and 2.
Purpose: Connect the zone’s hosts to your target and list its LUNs.
Steps:
In
Add New Instance Storage, keep the form from Task 2.Scopeis fixed toZone (generic iSCSI pools are zone-wide).Enter a
Namefor the pool.Under
Portals, add one row per portal of your target: its address, and the port when it is not3260. Do not enter a target IQN per portal.In
Target IQN(s), enter the target IQN, or several separated by commas. Leave it blank to use the one target discovery finds.Set
CHAP authentication:None: no CHAP.CHAP: enterCHAP usernameandCHAP secret.Mutual CHAP: also enterTarget CHAP usernameandTarget CHAP secret, the pair your target presents to initiators.
Pick
Minimum paths. The default is2. The list is not limited by the portals you typed, because discovery can find more portals.Storage tagsshows a lockedReserved for existing LUNschip. Karios adds it to keep ordinary disks off this pool.Click
Add Instance Storage.If discovery finds more than one target, the form shows
Discovery returned more than one target. Pick the ones this pool logs in to:. Tick the targets and clickCreate with the selected targets. Targets another pool uses are marked(used by pool <name>)and cannot be picked.
Expected Outcome:
A toast reads
Generic iSCSI pool <name> created.The pool appears in the list with protocol
ISCSIand the badgeExisting LUNs.The pool’s
LUNstab lists the exported LUNs.
If this fails:
A refused create leaves nothing behind. Fix the cause and create again.
KF-4014: hosts cannot reach or log in to the target. The error has one line per host, such ashost (iqn): 1 of 2 portals refused the login (cause), and a hint:CHAP negotiation failed: set the target’s CHAP to SHA-256 or SHA3-256.
Authorization failure or login refused: add the host’s IQN to the target ACL.
Name does not resolve: fix DNS for the portal name, or use its IP address.
Connection refused, no route, or timed out: check the portal address, port, and storage network.
The full answer from each host is under
Details.KF-4013: a host logged in on fewer paths thanMinimum paths. Export the LUNs on every portal, or lowerMinimum paths.Discovery returned no target: add the host’s IQN to the target ACL.
The target is already used by another pool: one target serves one pool. Use that pool, or delete it first.
The hosts lack the generic iSCSI host safety: contact Karios support.
KF-5022: no host answered the check. Retry.
Note
A target that exports no LUNs to the hosts still creates a pool with zero LUNs. The
LUNs tab then says the target exports no LUNs. Export them, then click Rescan.
Task 4: Review the LUNs Tab
When to Use: Use this after the create, and any time you change exports on the target.
Purpose: See what the hosts see on your target.
Steps:
Open the pool. Or, in the pool row, open
Actionsand chooseView LUNs.Open the
LUNstab. The header showsTarget,Portals,Hosts n of m(hosts logged in, of hosts in the zone), andLast scan.Click
Rescanafter you change the target. Karios asks each host for a fresh scan. Nothing on the target changes.Refreshonly reloads the page data.Filter by state, or search by LUN number, identity, vendor, or VM.
Open a row to see its identity, vendor and model, volume, holding host, state reason, and the paths at the last scan.
Expected Outcome:
Every exported LUN is listed. LUNs ready to use read
Detached.
LUN States
State |
Meaning |
|---|---|
|
Every host sees the LUN on at least |
|
The LUN is a data disk of the VM shown in |
|
A host does not see the LUN, sees it on fewer than |
|
The LUN is attached, but no host has reported it for two scans in a row. A LUN that is not attached and disappears is simply dropped from the list. |
|
Karios found a problem it will not guess about. See Task 8. |
Task 5: Attach a LUN to a VM
When to Use: Use this to give a VM one of your LUNs as a data disk.
Purpose:
Attach a Detached LUN to one VM.
Steps:
Use any one of these three ways:
From the
LUNstab: clickAttachon the LUN row. InAttach LUN to VM, pick theVM, optionally enter aVolume name, and clickAttach.From the VM: open the VM, go to
Volumes, clickAdd Disk, setSourcetoExisting LUN, pick the LUN, and clickAttach.When creating a VM: in
Create VM, pick one or more LUNs inExisting LUNs. Karios attaches each LUN after the VM is created, and starts the VM once every LUN is attached.
Rules:
The VM must be in the pool’s zone.
If the VM is running, its host must see the LUN on at least
Minimum pathsportals.The volume name is optional. It can be at most 255 bytes, with no semicolon, equals sign, or line break. Left blank, Karios names it.
A LUN is attached to one VM at a time.
Each attached LUN becomes a volume of the reserved
Karios LUNvolume profile. Karios creates that profile on the first attach and never offers it for new disks.
Warning
Karios does not read, check, or wipe the LUN. Whatever is on it becomes the VM’s disk. Make sure you attach the right LUN.
Expected Outcome:
The row reads
Attaching..., thenAttachedwith the VM name.The VM’s disk list shows the disk with a
LUNbadge.
If this fails:
A failed attach puts the LUN back to
Detachedby itself in about 7 to 9 minutes. Then attach it again.KF-4018: the VM’s host cannot see the LUN. Export it to that host’s IQN on every portal, thenRescan.KF-4019that names the VM’s host: the VM is running and its host sees the LUN on fewer paths thanMinimum paths, or the host is not in the pool’s zone. Export the LUN to that host’s IQN on every portal andRescan, or stop the VM first.KF-4019about the LUN: the LUN is notDetached, or the VM is in another zone. Wait for the LUN to readDetached, clear a conflict first, or pick a VM in the pool’s zone.KF-4013: the host could not open the minimum number of paths to the LUN. Check the exports on every portal, thenRescan.KF-4040: generic iSCSI is not enabled on that host. Contact Karios support.
Task 6: Detach a LUN
When to Use: Use this to take a LUN away from a VM. The LUN keeps its data.
Purpose:
Return the LUN to Detached so it can be attached again.
Steps:
Stop the VM that holds the LUN. Karios never unplugs a LUN from a running VM.
On the
LUNstab, clickDetachon the row. Or useDetach LUNon the disk inBlock Storageor on the VM’sVolumestab.Detach LUNreplacesDeletefor these disks.Type the volume name to confirm, and click
Detach.
Expected Outcome:
The row reads
Detaching...until the host confirms, thenDetached.The data on the LUN is unchanged.
If this fails:
KF-4019withstop VM <name> first: stop the VM, then detach again.If the LUN’s volume ends up attached to no VM, for example because the VM was destroyed, Karios releases the LUN by itself within a few minutes and records the event
SANFABRIC.LUN.DETACHED_RELEASED. The row then readsDetached.
Task 7: Grow a LUN
When to Use: Use this when a VM needs more space on an attached LUN.
Purpose: Grow the LUN on your target and let the VM see the new size.
Steps:
Stop the VM.
Grow the LUN on your target.
In the
LUNstab, clickRescanuntil the LUN shows the new size.Start the VM.
Expected Outcome:
The guest sees the larger disk. The volume size recorded in Karios stays at the old value.
Note
Karios refuses to resize a LUN disk itself (KF-4017). Always grow it on the target.
Task 8: Acknowledge a Change
When to Use:
Use this when a LUN reads Conflict or shows the Size reduced chip.
Purpose: Confirm that you checked a change Karios found on the target.
Steps:
Open the LUN row and read the
State reason.Check the target. Fix it if needed.
Click
Acknowledgeand confirm.
Conflicts that Karios flags and that you clear with Acknowledge:
A different LU now sits at the same LUN number.
The LUN shrank under an attached volume. Until you acknowledge, Karios refuses to attach the LUN or to start a VM that has it.
The volume was deleted outside Karios, without a detach.
Conflicts that come from the scan clear by themselves once the cause is gone. Fix the
cause, then click Rescan. Acknowledge does not apply to them (KF-4019):
Another pool lists the same LU.
A host sees the LUN at two LUN numbers.
A host refuses the LUN’s identity.
A LUN that shrank while it was not attached shows the Size reduced chip.
Acknowledge clears it. It never blocks an attach.
Expected Outcome:
The flag clears and the LUN returns to its normal state.
When a LUN Goes Missing
If an attached LUN disappears from the target, the row reads Missing. The guest’s disk
I/O to it is queued, not failing. The VM hangs on that disk until the LUN returns.
If the LUN was removed by mistake, export the same LU again at the same LUN number to the same hosts. I/O resumes. Nothing is needed in Karios.
If the LUN is gone for good, contact Karios support before you stop or move the VM.
Task 9: Retire a LUN
When to Use: Use this when a LUN should no longer be offered to VMs.
Purpose: Take a LUN out of the pool’s list. Karios does not change the LUN or its data.
Steps:
If the LUN is attached, detach it first (Task 6).
On your target, stop exporting the LUN to the Karios hosts, or remove it.
In the
LUNstab, clickRescan. Once no host has seen the LUN for two scans, Karios drops the row.
Expected Outcome:
The LUN no longer appears on the
LUNstab or in the LUN pickers.
Warning
Never remove an attached LUN on the target. It reads Missing and its VM hangs on that
disk. Detach it in Karios first.
Task 10: Delete the Pool
When to Use: Use this to retire a generic iSCSI pool.
Purpose: Log the hosts out of the target and remove the pool from Karios.
Steps:
Detach every LUN (Task 6). Delete is refused while any LUN is attached, with
pool "<name>" still has N attached LUN(s); detach them first.In the pool row, open
Actionsand chooseDelete. Delete is offered while the pool readsExisting LUNsorMaintenance.Type the pool name and confirm.
Expected Outcome:
Karios logs every host out of the target and the pool is gone from the list.
The LUNs and their data stay on your target.
Limits
New disks and root disks never land on this pool. It stays disabled for placement, and its card reads
Existing LUNs only.No templates from a LUN, and no clone or resize by Karios (
KF-4017).No volume snapshots (
KF-4016). The UI turns snapshot creation off for a LUN disk and an API request is refused.No Storage QoS on a LUN disk. A resize that asks for IOPS limits is refused with
KF-4017, because Karios never resizes a LUN.A LUN is attached to one VM at a time. Shared disks are not supported.
Zone scope only. A target serves one pool in its zone.
No array fence. Karios cannot force a LUN away from a host. If a host dies while it holds a LUN, the LUN stays held until that host returns and confirms the release.
Every host in the target’s ACL can see every LUN the target exports to it. Karios keeps LUNs that are not attached off its hosts, but an administrator who runs
iscsiadmby hand on a host is not fenced.
Both fence notes also show on the pool’s Fabric card, in the warning icon next to
Health.
Troubleshooting
Code or message |
What it means |
What to do |
|---|---|---|
|
Hosts cannot reach or log in to the target. |
Follow the hint on each host’s line: CHAP to SHA-256, IQN in the ACL, DNS, or the portal address and network. |
|
A host has fewer paths than |
Export on every portal, check the ACL on each portal, or lower |
|
Create, resize, clone, or template asked on this pool. |
Attach LUNs from the |
|
The host cannot see the LUN. |
Export it to the host’s IQN, then |
|
The LUN is not in the state the action needs, or the VM’s host does not see it on enough paths. |
Stop the VM before detach, wait for attach to finish, fix a scan conflict, or export the LUN to the VM’s host on every portal. |
|
Generic iSCSI is not enabled on a host. |
Contact Karios support. |
|
Karios could not run a check. Nothing was sent. |
Retry. |
|
The platform setting would drop the pool on host reconnect. |
Set it to |
|
Hosts log in, but see no LUNs. |
Add the IQNs to the ACL, export the LUNs, then |
|
No host could log in. |
Check the portal address and port, CHAP, and the ACL. |
|
The host safety is missing on those hosts. |
Contact Karios support. |
Done Criteria
[ ]
mount.disabled.storage.poolistrue.[ ] The pool shows
Hosts n of non theLUNstab.[ ] The LUNs you need read
DetachedorAttached.[ ] A test VM sees its attached LUN and keeps its data after detach and attach.