Storage Admin Hub
All guides/SAN
SAN · Worked procedure

Provision an iSCSI LUN

Target LIFs, initiator, igroup, LUN, mapping, multipath.

By Hrishikesh NaikUpdated 5 min read
Scope

AFF/FAS SCSI iSCSI · Linux host · two Ethernet failure domains

Scenario

Example: one Linux host with initiator IQN iqn.1993-08.org.debian:01:labhost gets a 500 GiB test LUN. Use host-specific NetApp interoperability guidance for the actual OS.

About the command and output examples

Names, addresses and results are illustrative. Commands have not been executed against a live storage system or SAN switch for this publication. Confirm syntax and compatibility for your release, then rehearse in an approved lab. Existing-data recovery and destructive changes need an environment-specific plan. Read the editorial standards.

01Design paths

  1. Confirm the host, ONTAP, switch and multipath combination in the interoperability matrix. Enable iSCSI on the SVM and create target LIFs on appropriate nodes and fabrics.
  2. Record host initiator IQN, intended target portal IPs, VLAN, MTU, authentication if required, and the host OS type for the LUN. Avoid a single network path.
Read-only checks 
vserver iscsi show
network interface show
lun show

02Provision and map

  1. In System Manager, create a LUN on the correct SVM with the host OS type, size, and volume placement. Create an igroup for only the approved initiator(s).
  2. Map the LUN to that igroup. Review the resulting LUN ID and reporting nodes. ONTAP Selective LUN Map normally advertises paths through the owner and HA partner; do not manually add reporting nodes without a reason.
  3. On the host, discover target portals, log in, rescan the SCSI bus, and configure the supported multipath package. Verify path count and LUN serial before formatting.
Read-only validation 
lun show
lun mapping show
network interface show

03Worked CLI example: one Linux test LUN

  1. Assume the SVM already has iSCSI service and redundant target LIFs, and a suitable volume vol_san exists. Confirm the host OS type and initiator IQN from the actual host.
  2. Create the LUN, a host-specific igroup and the mapping. On the host, rescan and verify serial and multipath before creating a file system.
Example change commands · review before running 
vserver iscsi show -vserver svm_prod
network interface show -vserver svm_prod
lun create -vserver svm_prod -volume vol_san -lun lun_lab -size 500GB -ostype linux -space-reserve disabled
igroup create -vserver svm_prod -igroup ig_lab -protocol iscsi -ostype linux -initiator iqn.1993-08.org.debian:01:labhost
lun mapping create -vserver svm_prod -volume vol_san -lun lun_lab -igroup ig_lab
lun mapping show -vserver svm_prod
Acceptance check

The LUN is mapped only to ig_lab and the host discovers the expected serial through redundant paths.

04Test safely

  1. Test failover of a network path during an approved window and confirm I/O continues through another path. Monitor ONTAP and host logs for path recovery.
  2. If no device appears, test portal connectivity, initiator login, IQN in the igroup, mapping, LUN online status, and host rescan in that order. Never format a device until its identity is confirmed.
Acceptance check

Host sees exactly the intended LUN and supported path count, with no duplicate or unexpected devices.

05Worked host path plan and initiator discovery

An iSCSI portal is a target network endpoint. An initiator IQN identifies the host. The igroup contains that IQN, while multipathing combines the host’s paths to the same LUN identity. Do not create a separate filesystem on every discovered /dev/sdX path. A single LUN reached through several portals must be handled through the supported multipath device.

The four-portal plan is illustrative; actual topology, path count and ASA behavior vary
NetworkHost interfacePlanned target portalsEvidence
AApproved host NIC on network AN1_A and N2_A LIF addressesConnectivity and sessions to A endpoints
BApproved host NIC on network BN1_B and N2_B LIF addressesIndependent connectivity and sessions to B endpoints
  1. On Linux, read the actual initiator IQN from /etc/iscsi/initiatorname.iscsi. Compare it character-for-character with the planned igroup. Install the supported host utilities, initiator and multipath configuration for the distribution/release.
  2. Discover and log in to each planned portal through the intended network. Record authentication requirements and route/NIC binding; two sessions over a single NIC do not prove network redundancy.
  3. Capture the LUN serial on ONTAP. After host discovery, compare its WWID/serial, capacity and paths with that record before any partition or filesystem action.
Example host discovery/login; verify the supported host configuration first 
cat /etc/iscsi/initiatorname.iscsi
# Replace this one portal, then repeat for each planned portal:
sudo iscsiadm -m discovery -t sendtargets -p <actual_target_portal>
sudo iscsiadm -m node -p <actual_target_portal> --login
sudo iscsiadm -m session -P 3
sudo multipath -ll
lsblk -o NAME,TYPE,SIZE,WWN,MOUNTPOINTS
Acceptance check

The same LUN identity is represented by one supported multipath device, with paths through both intended networks.

06Expected evidence and a reversible failure exercise

Read this as an acceptance checklist rather than exact output
EvidenceMeaningFollow-up if absent
Portal reachable but no sessionTransport and initiator login are separate stagesCheck service, authentication and initiator configuration.
Sessions up but no deviceMapping may not include the discovered IQNInspect igroup, mapping and supported host rescan.
Several raw paths with one WWIDThese can be alternate paths to the same LUNVerify multipath aggregation before use.
One network removed and I/O continuesThe tested failure domain has a surviving routeRestore the route and confirm paths recover.
  1. On a disposable test workload, remove one approved host network path in a controlled window and observe multipath and I/O. Restore it before trying another failure.
  2. If a single path loss causes application failure, preserve the host logs and sessions. Check independent network reachability and multipath settings before widening maps or changing the LUN.
  3. For pilot rollback, unmount the test filesystem and log out only the test sessions after the test device is unused. Do not unmap or delete a LUN still used by another host.
Continue learning

Use the section links to revisit a step, or follow a related guide below.

Official references and further reading

Choose the matching release in the vendor documentation before using a command or design. References open on the publisher’s website; linked material remains with its publisher.