Knowledge Base

The VMware Knowledge Base provides support solutions, error messages and troubleshooting guides
 
Search the VMware Knowledge Base (KB)   View by Article ID
 

Masking a LUN from ESX and ESXi using the MASK_PATH plug-in (1009449)

Details

This article provides steps to mask a LUN from ESX 4/ESXi 4.x and ESXi 5.x using the MASK_PATH plug-in.

VMware recommends this procedure when unpresenting a LUN to avoid the All-Paths-Down (APD) condition. For more information, see Virtual machines stop responding when any LUN on the host is in an all-paths-down (APD) condition (1016626).

The APD issue is resolved in ESX/ESXi 4.0 Update 3, ESX/ESXi 4.1 Update 1 and ESXi 5.x.

Note: If you are unpresenting a LUN containing a datastore, see:

Solution

Caution: This procedure only applies to LUNs that are being managed by the VMware NMP multipathing service. If you are using 3rd party multipathing plugin such as Powerpath/VE then LUNs must be excluded from the 3rd party multipathing software and put under NMP control before they can be masked again properly.

To mask a LUN from ESX/ESXi 4.x and ESXi 5.x using the MASK_PATH plug-in:

Note: Any differences in the commands between ESX/ESX 4.x and ESXi 5.x is noted with the version of ESX/ESXi before the command.

Note: After the paths is masked and the LUN is unpresented from the storage array. The claim rules can be removed but only after the reboot of the host.
  1. Log in to a console or SSH session on your host. For more information, see Using Tech Support Mode in ESXi 4.1 and ESXi 5.x (1017910)

  2. Look at the Multipath plug-ins currently installed on your ESX by running this command:

    # esxcfg-mpath -G

    The output indicates that there are, at a minimum, 2 plug-ins: The VMware Native Multipath plug-in (NMP) and the MASK_PATH plug-in (ESXi 5.0 only shows the NMP plugin by default), which is used for masking LUNs. There may be other plug-ins if third-party software (such as EMC PowerPath) is installed. For example:

    # esxcfg-mpath -G
    MASK_PATH
    NMP


  3. List all the claimrules currently on the ESX host by running these commands:

    ESXi 5.x: # esxcli storage core claimrule list

    ESX/ESXi 4.x: # esxcli corestorage claimrule list

    There are two MASK_PATH entries: one of class runtime and the other of class file.

    The runtime is the rules currently running in the PSA. The file is a reference to the rules defined in /etc/vmware/esx.conf. These are identical, but they could be different if you are in the process of modifying the /etc/vmware/esx.conf.

    Note: There is already a rule of vendor=DELL model=Universal Xport. This means that pseudo or management LUNs with these attributes are masked from the ESX.

    You see output similar to:

    Rule Class Type Plugin Matches
    0 runtime transport NMP transport=usb
    1 runtime transport NMP transport=sata
    2 runtime transport NMP transport=ide
    3 runtime transport NMP transport=block
    4 runtime transport NMP transport=unknown
    101 runtime vendor MASK_PATH vendor=DELL model=Universal Xport
    101 file vendor MASK_PATH vendor=DELL model=Universal Xport
    65535 runtime vendor NMP vendor=* model=*


  4. Add a rule to hide the LUN with the command:

    ESXi 5.x: # esxcli storage core claimrule add --rule <number> -t location -A <hba_adapter> -C <channel> -T <target> -L <lun> -P MASK_PATH

    ESX/ESXi 4.x: # esxcli corestorage claimrule add --rule <number> -t location -A <hba_adapter> -C <channel> -T <target> -L <lun> -P MASK_PATH

    The parameters -A <hba_adapter> -C <channel> -T <target> -L <lun> define a unique path. You can leave some of them unspecified if the LUN is uniquely defined. The value for parameter --rule can be any number between 101 and 200 that does not conflict with a pre-existing rule number from step 3.

    Note: For a detailed command description, see esxcli corestorage Command-Line Options and vSphere Command-Line Interface Installation and Scripting Guide.

    This is a brief example of usage:

    • Find the naa device of the datastore you want to unpresent with the command:

      # esxcfg-scsidevs -m
      naa.600508b1001037383941424344450300:3 /vmfs/devices/disks/naa.600508b1001037383941424344450300:3 4b44572e-8a1c74b2-42d4-00237dde59b8 0 datastore1
      naa.600601604550250018ea2d38073cdf11:1 /vmfs/devices/disks/naa.600601604550250018ea2d38073cdf11:1 4bb21500-dc941493-2904-00237dde59ba 0 DatastoreToMask


    • Check all of the paths that the naa device has:

      # esxcfg-mpath -b -d naa.600601604550250018ea2d38073cdf11
         vmhba33:C0:T3:L0 state:active Local HBA vmhba33 channel 0 target 3
         vmhba33:C0:T2:L0 state:standby Local HBA vmhba33 channel 0 target 2
         vmhba33:C0:T1:L0 state:active Local HBA vmhba33 channel 0 target 1
         vmhba33:C0:T0:L0 state:standby Local HBA vmhba33 channel 0 target 0


    • As you apply the rule -A vmhba33 -C 0 -L 0, verify that there is no other device with those parameters. You can use the wildcard vmhba33:C0.*L0 (. means any character and * means zero or more times).

      # esxcfg-mpath -L | egrep "vmhba33:C0.*L0"
      vmhba33:C0:T3:L0 state:active naa.600601604550250018ea2d38073cdf11 vmhba33 0 3 0 NMP active san iqn.1998-01.com.vmware:cs-tse-h42-17d4ba81 00023d000001,iqn.1992-04.com.emc:cx.ckm00092300229.b2,t,4
      vmhba33:C0:T2:L0 state:standby naa.600601604550250018ea2d38073cdf11 vmhba33 0 2 0 NMP standby san iqn.1998-01.com.vmware:cs-tse-h42-17d4ba81 00023d000001,iqn.1992-04.com.emc:cx.ckm00092300229.a3,t,3
      vmhba33:C0:T1:L0 state:active naa.600601604550250018ea2d38073cdf11 vmhba33 0 1 0 NMP active san iqn.1998-01.com.vmware:cs-tse-h42-17d4ba81 00023d000001,iqn.1992-04.com.emc:cx.ckm00092300229.b3,t,2
      vmhba33:C0:T0:L0 state:standby naa.600601604550250018ea2d38073cdf11 vmhba33 0 0 0 NMP standby san iqn.1998-01.com.vmware:cs-tse-h42-17d4ba81 00023d000001,iqn.1992-04.com.emc:cx.ckm00092300229.a2,t,1


    • Add a rule for this LUN with the command:

      ESXi 5.x: # esxcli storage core claimrule add --rule 192 -t location -A vmhba33 -C 0 -T 0 -L 0 -P MASK_PATH

      ESX/ESXi 4.x: # esxcli corestorage claimrule add --rule 192 -t location -A vmhba33 -C 0 -T 0 -L 0 -P MASK_PATH

      Notes:
  5. Verify that the rule is in effect with the command:

    ESXi 5.x: # esxcli storage core claimrule list
    ESX/ESXi 4.x: # esxcli corestorage claimrule list

    The output indicates our new rule. It is only of class file. You must then load it into the PSA.

    For example:

    Rule Class Type Plugin Matches
    0 runtime transport NMP transport=usb
    1 runtime transport NMP transport=sata
    2 runtime transport NMP transport=ide
    3 runtime transport NMP transport=block
    4 runtime transport NMP transport=unknown
    101 runtime vendor MASK_PATH vendor=DELL model=Universal Xport
    101 file vendor MASK_PATH vendor=DELL model=Universal Xport
    192 file location MASK_PATH adapter=vmhba33 channel=0 target=* lun=0
    65535 runtime vendor NMP vendor=* model=*


  6. Reload your claimrules with the command:

    ESXi 5.x: # esxcli storage core claimrule load
    ESX/ESXi 4.x: # esxcli corestorage claimrule load

  7. Re-examine your claimrules and verify that you can see both the file and runtime class. Run the command:

    ESXi 5.x: # esxcli storage core claimrule list
    ESX/ESXi 4.x: # esxcli corestorage claimrule list

    For example:

    Rule Class Type Plugin Matches
    0 runtime transport NMP transport=usb
    1 runtime transport NMP transport=sata
    2 runtime transport NMP transport=ide
    3 runtime transport NMP transport=block
    4 runtime transport NMP transport=unknown
    101 runtime vendor MASK_PATH vendor=DELL model=Universal Xport
    101 file vendor MASK_PATH vendor=DELL model=Universal Xport
    192 runtime location MASK_PATH adapter=vmhba33 channel=0 target=* lun=0
    192 file location MASK_PATH adapter=vmhba33 channel=0 target=* lun=0
    65535 runtime vendor NMP vendor=* model=*


  8. Unclaim all paths to a device and then run the loaded claimrules on each of the paths to reclaim them.

    Note: Unclaiming disassociates the paths from a PSA plugin. These paths are currently owned by NMP. You need to dissociate them from NMP and associate them to MASK_PATH.

    Run the command:

    ESXi 5.x:

    # esxcli storage core claiming reclaim -d naa.id
    # esxcli storage core claiming unclaim -d naa.id -t location
    # esxcli storage core claimrule run

    You need to rescan the HBAs after the last step

    ESX/ESXi 4.x: # esxcli corestorage claiming reclaim -d naa.id

    Where naa.id is the naa ID used in step 3. This device is the LUN being unpresented. This command attempts to unclaim all paths to a device and runs the loaded claimrules on each of the paths unclaimed to attempt to reclaim them.

    For example:

    ESXi 5.x: # esxcli storage core claiming reclaim -d naa.600601604550250018ea2d38073cdf11
    ESX/ESXi 4.x: # esxcli corestorage claiming reclaim -d naa.600601604550250018ea2d38073cdf11

  9. Verify that the masked device is no longer used by the ESX host.

    If you are masking a datastore, perform one of these options:

    • Connect the vSphere Client to the host and click Host > Configuration > Storage, then click Refresh. The masked datastore does not appear in the list.

    • Rescan the host by navigating to Host > Configuration > Storage Adapters > Rescan All.

    • Run the command:

      # esxcfg-scsidevs -m

      The masked datastore does not appear in the list.

      To see all the masked LUNs run this command:

      # esxcfg-scsidevs -c

    To verify that a masked LUN is no longer an active device, run the command:

    # esxcfg-mpath -L | grep naa.id

    For example:

    # esxcfg-mpath -L | grep 600601604550250018ea2d38073cdf11

    Empty output indicates that the LUN is not active.

Note: You may still see a single path to the LUN on one or more storage adapters after following the steps in this article. This disappears after the ESX host is rebooted. As long as the datastore is no longer visible, no issues are being reported in the logs, and rescans are completing in a timely fashion, the residual path can be safely ignored.

For more/related information, see Unable to claim the LUN back after unmasking it (1015252).

Additional Information

For translated versions of this article, see:

Tags

LUN-masking-MASK_PATH

Update History

11/11/2011 - Updated Step 8 to include a rescan of all hosts 11/23/2011 - Added information related to APD in the Details section and added a link to 1016626 01/16/2012 - Added ESXi 5.0 procedure. 08/01/2012 - Updated two commands with -T option for the targets. 02/04/2013 - Added ESXi 5.1 to Products 01/15/2014 - Added ESXi 5.5 to Products

Request a Product Feature

To request a new product feature or to provide feedback on a VMware product, please visit the Request a Product Feature page.

Feedback

  • 74 Ratings

Did this article help you?
This article resolved my issue.
This article did not resolve my issue.
This article helped but additional information was required to resolve my issue.

What can we do to improve this information? (4000 or fewer characters)




Please enter the Captcha code before clicking Submit.
  • 74 Ratings
Actions
KB: