Claim rules determine which multipathing module owns the paths to a particular storage device. They also define the type of multipathing support that the host provides to the device.

To learn more about multipathing modules, see Multipathing Concepts and Acronyms.

The claim rules are listed in the host’s /etc/vmware/esx.conf file.

The rules fall into these categories:
  • Core Claim Rules . These claim rules determine which multipathing module, the NMP, HPP, or a third-party MPP, claims the specific device.
  • SATP Claim Rules. Depending on the device type, these rules assign a particular SATP submodule that provides vendor-specific multipathing management to the device.

You can use the esxcli commands to add or change the core and SATP claim rules. Typically, you add the claim rules to load a third-party MPP or to hide a LUN from your host. Changing claim rules might be necessary when default settings for a specific device are not sufficient.

For more information about commands available to manage PSA claim rules, see the Getting Started with ESXCLI.

For a list of storage arrays and corresponding SATPs and PSPs, see the Storage/SAN section of the vSphere Compatibility Guide.

Multipathing Considerations

Specific considerations apply when you manage storage multipathing plug-ins and claim rules.

The following considerations help you with multipathing:

  • If no SATP is assigned to the device by the claim rules, the default SATP for iSCSI or FC devices is VMW_SATP_DEFAULT_AA. The default PSP is VMW_PSP_FIXED.
  • When the system searches the SATP rules to locate a SATP for a given device, it searches the driver rules first. If there is no match, the vendor/model rules are searched, and finally the transport rules are searched. If no match occurs, NMP selects a default SATP for the device.
  • If VMW_SATP_ALUA is assigned to a specific storage device, but the device is not ALUA-aware, no claim rule match occurs for this device. The device is claimed by the default SATP based on the device's transport type.
  • The default PSP for all devices claimed by VMW_SATP_ALUA is VMW_PSP_MRU. The VMW_PSP_MRU selects an active/optimized path as reported by the VMW_SATP_ALUA, or an active/unoptimized path if there is no active/optimized path. This path is used until a better path is available (MRU). For example, if the VMW_PSP_MRU is currently using an active/unoptimized path and an active/optimized path becomes available, the VMW_PSP_MRU will switch the current path to the active/optimized one.
  • While VMW_PSP_MRU is typically selected for ALUA arrays by default, certain ALUA storage arrays need to use VMW_PSP_FIXED. To check whether your storage array requires VMW_PSP_FIXED, see the VMware Compatibility Guide or contact your storage vendor. When using VMW_PSP_FIXED with ALUA arrays, unless you explicitly specify a preferred path, the ESXi host selects the most optimal working path and designates it as the default preferred path. If the host selected path becomes unavailable, the host selects an alternative available path. However, if you explicitly designate the preferred path, it will remain preferred no matter what its status is.
  • By default, the PSA claim rule 101 masks Dell array pseudo devices. Do not delete this rule, unless you want to unmask these devices.

List Multipathing Claim Rules for the Host

Use the esxcli command to list available multipathing claim rules.

Claim rules indicate whether the NMP, HPP, or a third-party MPP manages a given physical path. Each claim rule identifies a set of paths based on the following parameters:

  • Vendor/model strings
  • Transportation, such as SATA, IDE, Fibre Channel
  • Adapter, target, or LUN location
  • Device driver, for example, Mega-RAID

Procedure

  • ♦ List the multipathing claim rules by running the esxcli storage core claimrule list --claimrule-class=MP command.
    If you do not use the claimrule-class option, the MP rule class is implied.

Example: Sample Output of the esxcli storage core claimrule list Command

Rule Class  Rule   Class    Type       Plugin     Matches
MP           10    runtime  vendor     HPP        vendor=NVMe model=*              
MP           10    file     vendor     HPP        vendor=NVMe model=*              
MP           50    runtime  transport  NMP        transport=usb
MP           51    runtime  transport  NMP        transport=sata
MP           52    runtime  transport  NMP        transport=ide
MP           53    runtime  transport  NMP        transport=block
MP           54    runtime  transport  NMP        transport=unknown
MP          101    runtime  vendor     MASK_PATH  vendor=DELL model=Universal Xport
MP          101    file     vendor     MASK_PATH  vendor=DELL model=Universal Xport
MP          200    runtime  vendor     MPP_1      vendor=NewVend model=* 
MP          200    file     vendor     MPP_1      vendor=NewVend model=* 
MP          201    runtime  location   MPP_2      adapter=vmhba41 channel=* target=* lun=* 
MP          201    file     location   MPP_2      adapter=vmhba41 channel=* target=* lun=* 
MP          202    runtime  driver     MPP_3      driver=megaraid 
MP          202    file     driver     MPP_3      driver=megaraid 
MP          65535  runtime  vendor     NMP        vendor=* model=*
This example indicates the following:
  • The NMP claims all paths connected to storage devices that use the USB, SATA, IDE, and Block SCSI transportation.
  • The rules for HPP, MPP_1, MPP_2, and MPP_3 have been added, so that the modules can claim specified devices. For example, the HPP claims all devices with vendor NVMe. All devices handled by the inbox nvme driver are claimed regardless of the actual vendor. The MPP_1 module claims all paths connected to any model of the NewVend storage array.
  • You can use the MASK_PATH module to hide unused devices from your host. By default, the PSA claim rule 101 masks Dell array pseudo devices with a vendor string DELL and a model string Universal Xport.
  • The Rule Class column in the output describes the category of a claim rule. It can be MP (multipathing plug-in), Filter, or VAAI.
  • The Class column shows which rules are defined and which are loaded. The file parameter in the Class column indicates that the rule is defined. The runtime parameter indicates that the rule has been loaded into your system. For a user-defined claim rule to be active, two lines with the same rule number must exist, one line for the rule with the file parameter and another line with runtime. Several default system-defined claim rules have only one line with the Class of runtime. You cannot modify these rules.
  • The default rule 65535 assigns all unclaimed paths to the NMP. Do not delete this rule.

Add Multipathing Claim Rules

Use the esxcli commands to add a multipathing PSA claim rule to the set of claim rules on the system. For the new claim rule to be active, you first define the rule and then load it into your system.

Examples when you add a PSA claim rule include the following:
  • You load a new third-party MPP and must define the paths that this module claims.
  • You must enable the native HPP.
Warning: You cannot create rules where two different plug-ins claim paths to the same device. Your attempts to create these claim rules fail with a warning in vmkernel.log.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. To define a new claim rule, use the following command:
    esxcli storage core claimrule add

    The command takes the following options:

    Option Description
    -A|--adapter=<adapter> Adapter of the paths to use. Valid only if --type is location.
    -u|--autoassign Adds a claim rule based on its characteristics. The rule number is not required.
    -C|--channel=<channel> Channel of the paths to use. Valid only if --type is location.
    -c|--claimrule-class=<cl> Claim rule class to use in this operation. You can specify MP (default), Filter, or VAAI.

    To configure hardware acceleration for a new array, add two claim rules, one for the VAAI filter and another for the VAAI plug-in. See Add Hardware Acceleration Claim Rules for detailed instructions.

    -d|--device=<device_uid> UID of the device. Valid only when --type is device.
    -D|--driver=<driver> Driver for the HBA of the paths to use. Valid only if --type is driver.
    -f|--force Force claim rules to ignore validity checks and install the rule anyway.
    --force-reserved Override protection of reserved rule ID ranges.

    Reserved claim rules are the rules with an ID below 100. You can use them to reassign local devices to specific plug-ins, for example, the NVMe device to HPP.

    --if-unset=<str> Run this command if this advanced user variable is not set to 1.
    -i|--iqn=<iscsi_name> iSCSI Qualified Name for the target. Valid only when --type is target.
    -L|--lun=<lun_id> LUN of the paths. Valid only if --type is location.

    LUN ID must not be higher than the value of the advanced configuration option /Disk/MaxLUN.

    -M|--model=<model> Model of the paths to use. Valid only if --type is vendor.

    Valid values are values of the Model string from the SCSI inquiry string. Run vicfg-scsidevs <conn_options> -l on each device to see model string values.

    -P|--plugin=<plugin> PSA plug-in to use. The values are NMP, MASK_PATH, or HPP. Third parties can also provide their own PSA plug-ins. Required.
    -r|--rule=<rule_ID> Rule ID to use. The rule ID indicates the order in which the claim rule is to be evaluated. User-defined claim rules are evaluated in numeric order starting with 101.

    You can run esxcli storage core claimrule list to determine which rule IDs are available.

    -T|--target=<target> Target of the paths to use. Valid only if --type is location.
    -R|--transport=<transport>

    Transport of the paths to use. Valid only if --type is transport. The following values are supported.

    • block — block storage
    • fc — Fibre Channel
    • iscsivendor — iSCSI
    • iscsi — not currently used
    • ide — IDE storage
    • sas — SAS storage
    • sata — SATA storage
    • usb — USB storage
    • parallel — parallel
    • fcoe — FCoE
    • unknown
    -t|--type=<type> Type of matching to use for the operation. Valid values are the following. Required.
    • vendor
    • location
    • driver
    • transport
    • device
    • target
    -V|--vendor=<vendor> Vendor of the paths to use. Valid only if --type is vendor.

    Valid values are values of the vendor string from the SCSI inquiry string. Run vicfg-scsidevs <conn_options> -l on each device to see vendor string values.

    --wwnn=<wwnn> World-Wide Node Number for the target.
    --wwpn=<wwpn> World-Wide Port Number for the target.
    -a|--xcopy-use-array-values Use the array reported values to construct the XCOPY command to be sent to the storage array. This applies to VAAI claim rules only.
    -s|--xcopy-use-multi-segs Use multiple segments when issuing an XCOPY request. Valid only if --xcopy-use-array-values is specified.
    -m|--xcopy-max-transfer-size Maximum data transfer size in MB when you use a transfer size different than array reported. Valid only if --xcopy-use-array-values is specified.
    -k|--xcopy-max-transfer-size-kib Maximum transfer size in KiB for the XCOPY commands when you use a transfer size different than array reported. Valid only if --xcopy-use-array-values is specified.
  2. To load the new claim rule into your system, use the following command:
    esxcli storage core claimrule load
    This command loads all newly created multipathing claim rules from the esx.conf configuration file into the VMkernel. The command has no options.
  3. To apply claim rules that are loaded, use the following command:
    esxcli storage core claimrule run

    The command takes the following options:

    Option Description
    -A|--adapter=<adapter> If --type is location, name of the HBA for the paths to run the claim rules on. To run claim rules on paths from all adapters, omit this option.
    -C|--channel=<channel> If --type is location, indicate the channel of the paths to use in this operation. To run claim rules on paths with any channel number, omit this option.
    -c|--claimrule-class=<cl> Claim rule class to use in this operation.
    -d|--device=<device_uid> UID of the device.
    -L|--lun=<lun_id> If --type is location, indicate the LUN of the paths to run claim rules on. To run claim rules on paths with any LUN, omit this option.
    -p|--path=<path_uid> If --type is path, this option indicates the unique path identifier (UID) or the runtime name of a path to run claim rules on.
    -T|--target=<target> If --type is location, indicate the target of the paths to run claim rules on. To run claim rules on paths with any target number, omit this option.
    -t|--type=<location|path|all> Type of claim to perform. By default, uses all, which means claim rules run without restriction to specific paths. Valid values are location, path, and all.
    -w|--wait You can use this option only if you also use --type all.

    If the option is included, the claim waits for paths to settle before running the claim operation. In that case, the system does not start the claiming process until it is likely that all paths on the system have appeared before starting the claim process.

    After the claiming process has started, the command does not return until device registration has completed.

    If you add or remove paths during the claiming or the discovery process, this option might not work correctly.

Example: Defining Multipathing Claim Rules

In the following example, you add and load rule # 500. The rule claims all paths with the NewMod model string and the NewVend vendor string for the NMP plug-in.

# esxcli storage core claimrule add -r 500 -t vendor -V NewVend -M NewMod -P NMP

# esxcli storage core claimrule load

After you run the esxcli storage core claimrule list command, you can see the new claim rule appearing on the list.

The following output indicates that the claim rule 500 has been loaded into the system and is active. 
Rule Class  Rule   Class    Type       Plugin     Matches
...         ...    ...      ...        ...        ...
MP          500    runtime  vendor     NMP        vendor=NewVend model=NewMod  
MP          500    file     vendor     NMP        vendor=NewVend model=NewMod

Delete Multipathing Claim Rules

Use the esxcli commands to remove a multipathing PSA claim rule from the set of claim rules on the system.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. Delete a claim rule from the set of claim rules.
    esxcli storage core claimrule remove
    Note: By default, the PSA claim rule 101 masks Dell array pseudo devices. Do not delete this rule, unless you want to unmask these devices.

    The command takes the following options:

    Option Description
    -c|--claimrule-class=<str>

    Indicate the claim rule class (MP, Filter, VAAI).

    -P|--plugin=<str> Indicate the plug-in.
    -r|--rule=<long> Indicate the rule ID.
    This step removes the claim rule from the File class.
  2. Remove the claim rule from the system.
    esxcli storage core claimrule load
    This step removes the claim rule from the Runtime class.

Mask Paths

You can prevent the host from accessing storage devices or LUNs or from using individual paths to a LUN. Use the esxcli commands to mask the paths. When you mask paths, you create claim rules that assign the MASK_PATH plug-in to the specified paths.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. Check what the next available rule ID is.
    esxcli storage core claimrule list
    The claim rules that you use to mask paths have rule IDs in the range from 101 through 200. If this command shows that rules 101 and 102 exist, you can specify 103 for the rule to add.
  2. Assign the MASK_PATH plug-in to a path by creating a new claim rule for the plug-in.
    esxcli storage core claimrule add -P MASK_PATH
  3. Load the MASK_PATH claim rule into your system.
    esxcli storage core claimrule load
  4. Verify that the MASK_PATH claim rule was added correctly.
    esxcli storage core claimrule list
  5. If a claim rule for the masked path exists, remove the rule.
    esxcli storage core claiming unclaim
  6. Run the path claiming rules.
    esxcli storage core claimrule run

Results

After you assign the MASK_PATH plug-in to a path, the path state becomes irrelevant and is no longer maintained by the host. As a result, commands that display the masked path's information might show the path state as dead.

Example: Masking a LUN

In this example, you mask the LUN 20 on targets T1 and T2 accessed through storage adapters vmhba2 and vmhba3. 

  1. #esxcli storage core claimrule list
  2. #esxcli storage core claimrule add -P MASK_PATH -r 109 -t location -A vmhba2 -C 0 -T 1 -L 20 
#esxcli storage core claimrule add -P MASK_PATH -r 110 -t location -A vmhba3 -C 0 -T 1 -L 20 
#esxcli storage core claimrule add -P MASK_PATH -r 111 -t location -A vmhba2 -C 0 -T 2 -L 20 
#esxcli storage core claimrule add -P MASK_PATH -r 112 -t location -A vmhba3 -C 0 -T 2 -L 20
  3. #esxcli storage core claimrule load
  4. #esxcli storage core claimrule list
  5. #esxcli storage core claiming unclaim -t location -A vmhba2 
#esxcli storage core claiming unclaim -t location -A vmhba3
  6. #esxcli storage core claimrule run

Unmask Paths

When you need the host to access the masked storage device, unmask the paths to the device.

Note: When you run an unclaim operation using a device property, for example, device ID or vendor, the paths claimed by the MASK_PATH plug-in are not unclaimed. The MASK_PATH plug-in does not track any device property of the paths that it claims.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. Delete the MASK_PATH claim rule.
    esxcli storage core claimrule remove -r rule#
  2. Verify that the claim rule was deleted correctly.
    esxcli storage core claimrule list
  3. Reload the path claiming rules from the configuration file into the VMkernel.
    esxcli storage core claimrule load
  4. Run the esxcli storage core claiming unclaim command for each path to the masked storage device.
    For example:

    esxcli storage core claiming unclaim -t location -A vmhba0 -C 0 -T 0 -L 149

  5. Run the path claiming rules.
    esxcli storage core claimrule run

Results

Your host can now access the previously masked storage device.

Define NMP SATP Rules

The NMP SATP claim rules define which SATP manages a storage device. Usually, you can use the default SATPs provided for storage devices. If default settings are not sufficient, use the esxcli commands to change the SATP for a specific device.

You might need to create an SATP rule when you install a third-party SATP for a specific storage array.

Prerequisites

Install ESXCLI. See Getting Started with ESXCLI. For troubleshooting, run esxcli commands in the ESXi Shell.

Procedure

  1. To add a claim rule for a specific SATP, run the esxcli storage nmp satp rule add command. The command takes the following options.
    Option Description
    -b|--boot This rule is a system default rule added at boot time. Do not modify esx.conf or add to a host profile.
    -c|--claim-option=string Set the claim option string when adding a SATP claim rule.
    -e|--description=string Set the claim rule description when adding a SATP claim rule.
    -d|--device=string Set the device when adding SATP claim rules. Device rules are mutually exclusive with vendor/model and driver rules.
    -D|--driver=string Set the driver string when adding a SATP claim rule. Driver rules are mutually exclusive with vendor/model rules.
    -f|--force Force claim rules to ignore validity checks and install the rule anyway.
    -h|--help Show the help message.
    -M|--model=string Set the model string when adding SATP a claim rule. Vendor/Model rules are mutually exclusive with driver rules.
    -o|--option=string Set the option string when adding a SATP claim rule.
    -P|--psp=string Set the default PSP for the SATP claim rule.
    -O|--psp-option=string Set the PSP options for the SATP claim rule.
    -s|--satp=string The SATP for which a new rule is added.
    -R|--transport=string Set the claim transport type string when adding a SATP claim rule.
    -t|--type=string Set the claim type when adding a SATP claim rule.
    -V|--vendor=string Set the vendor string when adding SATP claim rules. Vendor/Model rules are mutually exclusive with driver rules.
    Note: When searching the SATP rules to locate a SATP for a given device, the NMP searches the driver rules first. If there is no match, the vendor/model rules are searched, and finally the transport rules. If there is still no match, NMP selects a default SATP for the device.
  2. Reboot your host.

Example: Defining an NMP SATP Rule

The following sample command assigns the VMW_SATP_INV plug-in to manage storage arrays with vendor string NewVend and model string NewMod. 

# esxcli storage nmp satp rule add -V NewVend -M NewMod -s VMW_SATP_INV

When you run the esxcli storage nmp satp list -s VMW_SATP_INV command, you can see the new rule on the list of VMW_SATP_INV rules.