Understand and apply LUN masking using PSA‐related commands

LUN masking can be used to block a hosts access to a storage device or to prevent an ESXi host from using a particular storage path. This can be useful when troubleshooting storage issues, and in earlier versions of ESXi has been necessary when removing storage from the host, as described here.

When an ESXi 5 host loses all communication with a device, an All Paths Down (APD) condition is triggered. The host considers an APD to be temporary with the possibility that it may come back online, after the issue has been resolved (as in the case of a cable disconnect or fabric switch reboot).

Another state, Permanent Device Loss (PDL), is how an ESXi 5 host recognises that I/O should no longer be queued for that device. It will not expect the device to come back once it is in a PDL state. vSphere 5 is able to determine whether paths to a storage device are APD or PDL by the use of SCSI sense codes. When a virtual machine determines that All Paths are Down in vSphere 5, the I/O remains queued until a SCSI response code says officially that the link is down — transitioning it to PDL. If all links go PDL, the device is considered to be lost. In the past (as with ESXi 4), an APD condition could mean the indefinite queuing of I/O to the device. This queue would block hostd processes and eventually it could crash the process and virtual machine.  When a link goes PDL, I/O is failed and the hostd queue workload is freed, preventing the host from locking up. You can read more about APD and PDL here. Although more relevant to ESXi 4, LUN masking can prevent an APD condition affecting your hosts management processes when you remove a storage device by masking the device first.

LUN masking allows you to mask:

  • Complete storage array
  • One or more LUNs
  • Paths to a LUN

How to Mask a LUN in ESXi 5

I’ll run through an example of how to mask a storage device in ESXi 5. I’ll be masking a device which contains a VMFS datastore called SanDatastore1:

Once you have a CLI session on your host the first step is to list all the current storage claimrules on your host by running the following command:

~ # esxcli storage core claimrule list

We then need to create a new claimrule which will hide our chosen LUN. First of all we will need to find the device identifier for the datastore we wish to mask. We can do this by running:

~ # esxcfg-scsidevs -m

We can see that the identifer for SanDatastore1 is naa.98437598437543987598437. We can now check the paths that this device is using:

~ # esxcfg-mpath -L | grep naa.98437598437543987598437

This shows that there is just one path to the device, which is vmhba33 -C 0 -L 0. We can check that no other device is using this path by running:

Having collected this information, the next step is to create a new MASK_PATH storage claim rule for the device by running the following command:

~ # esxcli storage core claimrule add -r 103 -t location -A vmhba33 -C 0 -T 1 -L 0 -P MASK_PATH

We can verify that the rule is in place by running:

We then need to load the claim rules:

~ # esxcli storage core claimrule load

Checking your claim rules again now, you should see that the rule is now loaded in runtime:

Unclaim existing paths to the masked LUN. Unclaiming disassociates the paths from a PSA plugin. These paths are currently owned by NMP. You need to dissociate them from NMP and have them associated to MASK_PATH;

~ # esxcli core storage claiming reclaim –d naa.98437598437543987598437

We can now run the claim rules, which should mask the device:

We can confirm that the device is no longer used by the host:

Unmasking the Storage Device

If you need to make the storage device available to the host again you can follow this process. Start by listing the claim rules on the host:

Delete the MASK_PATH rule that was created earlier:

Verify that the rule was deleted – it will now exist in runtime only:

Run the esxcli storage core claiming unclaim command for each path to the masked storage device:

Finally, we can load and run the claim rules. Once finished, the device should be available once again:

Useful Links and Resources

https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2004684

https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1029786

Related posts

VMware vSphere Virtual Machine Snapshots Explained

How to Enable SSH on All ESXi Hosts using PowerCLI

How to Install VMware Tools on Debian 11

This website uses cookies to improve your experience. We'll assume you're ok with this, but you can opt-out if you wish. Read More