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 vCLI or deploy the vSphere Management Assistant (vMA) virtual machine. See Getting Started with vSphere Command-Line Interfaces. 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, value of the SCSI channel number for the paths to run the claim rules on. 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, value of the SCSI LUN for 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, value of the SCSI target number for 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 or SCSI addresses. 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