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.pool is true. 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:

  1. Open All Settings.

  2. Search for mount.disabled.storage.pool.

  3. Set it to true if it is not already.

Expected Outcome:

  • The setting reads true.

If this fails:

  1. If the create later says the setting is false, set it to true and 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:

  1. Open Control Center -> Storage -> Instance Storage and click Add Instance Storage.

  2. Set Protocol to iscsi and Driver to generic (attaches LUNs your target already exports).

  3. Pick the Zone. The form lists Hosts that will log in with each host’s initiator IQN. Use the copy button next to each IQN.

  4. 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:

  1. In Add New Instance Storage, keep the form from Task 2. Scope is fixed to Zone (generic iSCSI pools are zone-wide).

  2. Enter a Name for the pool.

  3. Under Portals, add one row per portal of your target: its address, and the port when it is not 3260. Do not enter a target IQN per portal.

  4. In Target IQN(s), enter the target IQN, or several separated by commas. Leave it blank to use the one target discovery finds.

  5. Set CHAP authentication:

    • None: no CHAP.

    • CHAP: enter CHAP username and CHAP secret.

    • Mutual CHAP: also enter Target CHAP username and Target CHAP secret, the pair your target presents to initiators.

  6. Pick Minimum paths. The default is 2. The list is not limited by the portals you typed, because discovery can find more portals.

  7. Storage tags shows a locked Reserved for existing LUNs chip. Karios adds it to keep ordinary disks off this pool.

  8. Click Add Instance Storage.

  9. 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 click Create 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 ISCSI and the badge Existing LUNs.

  • The pool’s LUNs tab lists the exported LUNs.

If this fails:

A refused create leaves nothing behind. Fix the cause and create again.

  1. KF-4014: hosts cannot reach or log in to the target. The error has one line per host, such as host (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.

  2. KF-4013: a host logged in on fewer paths than Minimum paths. Export the LUNs on every portal, or lower Minimum paths.

  3. Discovery returned no target: add the host’s IQN to the target ACL.

  4. The target is already used by another pool: one target serves one pool. Use that pool, or delete it first.

  5. The hosts lack the generic iSCSI host safety: contact Karios support.

  6. 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:

  1. Open the pool. Or, in the pool row, open Actions and choose View LUNs.

  2. Open the LUNs tab. The header shows Target, Portals, Hosts n of m (hosts logged in, of hosts in the zone), and Last scan.

  3. Click Rescan after you change the target. Karios asks each host for a fresh scan. Nothing on the target changes. Refresh only reloads the page data.

  4. Filter by state, or search by LUN number, identity, vendor, or VM.

  5. 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

Detached

Every host sees the LUN on at least Minimum paths portals, and no VM has it. You can attach it.

Attached

The LUN is a data disk of the VM shown in Attached to.

Not ready

A host does not see the LUN, sees it on fewer than Minimum paths portals, or has no good scan yet. Or the host safety is missing on a host, the target write-protects the LUN, its block size is not 512 bytes, or its identity is not an NAA identity. The State reason says which.

Missing

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.

Conflict

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 LUNs tab: click Attach on the LUN row. In Attach LUN to VM, pick the VM, optionally enter a Volume name, and click Attach.

  • From the VM: open the VM, go to Volumes, click Add Disk, set Source to Existing LUN, pick the LUN, and click Attach.

  • When creating a VM: in Create VM, pick one or more LUNs in Existing 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 paths portals.

  • 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 LUN volume 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..., then Attached with the VM name.

  • The VM’s disk list shows the disk with a LUN badge.

If this fails:

  1. A failed attach puts the LUN back to Detached by itself in about 7 to 9 minutes. Then attach it again.

  2. KF-4018: the VM’s host cannot see the LUN. Export it to that host’s IQN on every portal, then Rescan.

  3. KF-4019 that names the VM’s host: the VM is running and its host sees the LUN on fewer paths than Minimum paths, or the host is not in the pool’s zone. Export the LUN to that host’s IQN on every portal and Rescan, or stop the VM first.

  4. KF-4019 about the LUN: the LUN is not Detached, or the VM is in another zone. Wait for the LUN to read Detached, clear a conflict first, or pick a VM in the pool’s zone.

  5. KF-4013: the host could not open the minimum number of paths to the LUN. Check the exports on every portal, then Rescan.

  6. 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:

  1. Stop the VM that holds the LUN. Karios never unplugs a LUN from a running VM.

  2. On the LUNs tab, click Detach on the row. Or use Detach LUN on the disk in Block Storage or on the VM’s Volumes tab. Detach LUN replaces Delete for these disks.

  3. Type the volume name to confirm, and click Detach.

Expected Outcome:

  • The row reads Detaching... until the host confirms, then Detached.

  • The data on the LUN is unchanged.

If this fails:

  1. KF-4019 with stop VM <name> first: stop the VM, then detach again.

  2. 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 reads Detached.

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:

  1. Stop the VM.

  2. Grow the LUN on your target.

  3. In the LUNs tab, click Rescan until the LUN shows the new size.

  4. 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:

  1. Open the LUN row and read the State reason.

  2. Check the target. Fix it if needed.

  3. Click Acknowledge and 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:

  1. If the LUN is attached, detach it first (Task 6).

  2. On your target, stop exporting the LUN to the Karios hosts, or remove it.

  3. In the LUNs tab, click Rescan. Once no host has seen the LUN for two scans, Karios drops the row.

Expected Outcome:

  • The LUN no longer appears on the LUNs tab 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:

  1. 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.

  2. In the pool row, open Actions and choose Delete. Delete is offered while the pool reads Existing LUNs or Maintenance.

  3. 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 iscsiadm by 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

KF-4014

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.

KF-4013

A host has fewer paths than Minimum paths.

Export on every portal, check the ACL on each portal, or lower Minimum paths.

KF-4017

Create, resize, clone, or template asked on this pool.

Attach LUNs from the LUNs tab. To grow a LUN, follow Task 7.

KF-4018

The host cannot see the LUN.

Export it to the host’s IQN, then Rescan.

KF-4019

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.

KF-4040

Generic iSCSI is not enabled on a host.

Contact Karios support.

KF-5022

Karios could not run a check. Nothing was sent.

Retry.

mount.disabled.storage.pool is false

The platform setting would drop the pool on host reconnect.

Set it to true (Task 1).

The target exports no LUNs to these hosts

Hosts log in, but see no LUNs.

Add the IQNs to the ACL, export the LUNs, then Rescan.

No host is logged in to the target

No host could log in.

Check the portal address and port, CHAP, and the ACL.

Generic iSCSI is not enabled on <hosts>

The host safety is missing on those hosts.

Contact Karios support.

Done Criteria

  • [ ] mount.disabled.storage.pool is true.

  • [ ] The pool shows Hosts n of n on the LUNs tab.

  • [ ] The LUNs you need read Detached or Attached.

  • [ ] A test VM sees its attached LUN and keeps its data after detach and attach.