Managing Claim Rules

The PSA uses claim rules to determine which multipathing module should claim the paths to a particular device and to manage the device. esxcli storage core claimrule manages claim rules.

Claim rule modification commands do not operate on the VMkernel directly. Instead they operate on the configuration file by adding and removing rules. Specify one of the options listed in Connection Options in place of <conn_options>.

To change the current claim rules in the VMkernel

1	Run one or more of the esxcli storage core claimrule modification commands (add, remove, or move).

2	Run esxcli storage core claimrule load to replace the current rules in the VMkernel with the modified rules from the configuration file.

You can also run esxcli storage core plugin list to list all loaded plugins.

Adding Claim Rules

The esxcli storage core claimrule add command adds a claim rule to the set of claim rules on the system. You can use this command to add new claim rules or to mask a path using the MASK_PATH claim rule. You must load the rules after you add them.

Options	Description
- -adapter <adapter> -A <adapter>	Adapter of the paths to use. Valid only if - -type is location.
--autoassign -u	Adds a claim rule based on its characteristics. The rule number is not required.
- -channel <channel> -C <channel>	Channel of the paths to use. Valid only if - -type is location.
--claimrule-class <cl> -c <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 plugin. See vSphere Storage for detailed instructions.
- -driver <driver> -D <driver>	Driver for the HBA of the paths to use. Valid only if - -type is driver.
- -force -f	Force claim rules to ignore validity checks and install the rule.
- -lun <lun_number> -L <lun_number>	LUN of the paths to use. Valid only if - -type is location.
- -model <model> -M <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.
- -plugin -P	PSA plugin to use. Currently, the values are NMP or MASK_PATH, but third parties can ship their own PSA plugins in the future. MASK_PATH refers to the plugin MASK_PATH_PLUGIN. The command adds claimrules for this plugin if the user wants to mask the path. ESX 3.5 includes the MaskLUNs advanced configuration option. This option is not available in ESX/ESXi 4.x and ESXi 5.0. It has been replaced by the MASK_PATH_PLUGIN. You can add a claim rule that causes the MASK_PATH_PLUGIN to claim the path to mask a path or LUN from the host. See the vSphere Storage documentation for details.
- -rule <rule_ID> -r <rule_ID>	Rule ID to use. Run esxcli storage core claimrule list to see the rule ID. 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.
- -target <target> -T <target>	Target of the paths to use. Valid only if - -type is location.
- -transport <transport> -R <transport>	Transport of the paths to use. Valid only if - -type is transport. The following values are supported: ■ block – block storage ■ fc – FibreChannel ■ iscsivendor — iSCSI ■ iscsi – not currently used ■ ide — IDE storage ■ sas — SAS storage ■ sata — SATA storage ■ usb – USB storage ■ parallel – parallel ■ unknown
- -type <type> -t <type>	Type of matching to use for the operation. Valid values are vendor, location, driver, and transport.
- -vendor -V	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	World-Wide Node Number for the target to use in this operation.
--wwpn	World-Wide Port Number for the target to use in this operation.

Claim rules are numbered as follows.

■	Rules 0–100 are reserved for internal use by VMware.

■	Rules 101–65435 are available for general use. Any third party multipathing plugins installed on your system use claim rules in this range. By default, the PSA claim rule 101 masks Dell array pseudo devices. Do not remove this rule, unless you want to unmask these devices.

■	Rules 65436–65535 are reserved for internal use by VMware.

When claiming a path, the PSA runs through the rules starting from the lowest number and determines is a path matches the claim rule specification. If the PSA finds a match, it gives the path to the corresponding plugin. This is worth noticing because a given path might match several claim rules.

The following examples illustrate adding claim rules. Specify one of the options listed in Connection Options in place of <conn_options>.

■	Add rule 321, which claims the path on adapter vmhba0, channel 0, target 0, LUN 0 for the NMP plugin.

esxcli <conn_options> storage core claimrule add -r 321 -t location -A vmhba0 -C 0 -T 0 -L 0 -P NMP

■	Add rule 429, which claims all paths provided by an adapter with the mptscsi driver for the MASK_PATH plugin.

esxcli <conn_options> storage core claimrule add -r 429 -t driver -D mptscsi -P MASK_PATH

■	Add rule 914, which claims all paths with vendor string VMWARE and model string Virtual for the NMP plugin.

esxcli <conn_options> storage core claimrule add -r 914 -t vendor -V VMWARE -M Virtual -P NMP

■	Add rule 1015, which claims all paths provided by FC adapters for the NMP plugin.

esxcli <conn_options> storage core claimrule add -r 1015 -t transport -R fc -P NMP

Converting ESX 3.5 LUN Masks to Claim Rule Format

The esxcli storage core claimrule convert command converts LUN masks in ESX 3.5 format (/adv/Disk/MaskLUNs) to claim rule format. The command writes the converted list and erases the old LUN mask data. Specify one of the options listed in Connection Options in place of <conn_options>.

To convert ESX 3.5 format LUN masks to claim rule format

1	Run esxcli storage core claimrule convert without options.

That call returns No /adv/Disk/MaskLUNs config entry to convert or displays the list of claim rules that would result from the conversion. For example:

Rule	Plugin	HbaName	Controller	Target	LUN
120	MASK_PATH	vmhba11	0	0	11
121	MASK_PATH	vmhba11	0	0	10
122	MASK_PATH	vmhba4	0	2	1

2	Run esxcli storage core claimrule convert - -commit to actually commit the change.

When you convert LUN masking to the claim rule format after an upgrade from ESX/ESXi 3.5 to ESX/ESXi 4.x, this command converts the /adv/Disk/MaskLUNs advanced configuration entry in the esx.conf file to claim rules with MASK_PATH as the plug-in.

Important This conversion does not work for all input Mask LUN variations. For example, role conversion for software iSCSI LUNs is not supported. Inspect the list of generated claim rules carefully before you commit them by using - -commit.

esxcli storage core claimrule convert Options 

Options	Description
- -commit -C	Forces LUN mask configuration changes to be saved. If you call the command without this parameter, changes are not saved, and you can first inspect the generated claim rules.

Removing Claim Rules

The esxcli storage core claimrule remove command removes a claim rule from the set of claim rules on the system.

Important By default, the PSA claim rule 101 masks Dell array pseudo devices. Do not remove this rule, unless you want to unmask these devices.

Option	Description
- -rule <rule_ID> -r <rule_ID>	ID of the rule to be removed. Run esxcli storage core claimrule list to see the rule ID.

The following example removes rule 1015.

esxcli <conn_options> storage core claimrule remove -r 1015

Listing Claim Rules

The list command lists all claim rules on the system. You can specify the claim rule class as an argument.

Option	Description
--claimrule-class <cl> -c <cl>	Claim rule class to use in this operation. You can specify MP (Multipathing), Filter, or VAAI. Multipathing is the default. Filter is used only for VAAI. Specify claim rules for both VAAI_FILTER and VAAI plugin to use it. See vSphere Storage for information about VAAI.

You can run the command as follows. The equal sign is optional, so both forms of the command have the same result. Specify one of the options listed in Connection Options in place of <conn_options>.

esxcli <conn_options> storage core claimrule list -c Filter

esxcli <conn_options> storage core claimrule list --claimrule-class=Filter

Loading Claim Rules

The esxcli storage core claimrule load command loads claim rules from the esx.conf configuration file into the VMkernel. Developers and experienced storage administrators might use this command for boot time configuration.

This command has no options; it always loads all claim rules from esx.conf.

Moving Claim Rules

The esxcli storage core claimrule move command moves a claim rule from one rule ID to another.

Options	Description
--claimrule-class <cl> -c <cl>	Claim rule class to use in this operation.
- -new-rule <rule_ID> -n <rule_ID>	New rule ID you want to give to the rule specified by the - -rule option.
- -rule <rule_ID> -r <rule_ID>	ID of the rule to be removed. Run esxcli storage core claimrule list to display the rule ID.

The following example renames rule 1016 to rule 1015 and removes rule 1016. Specify one of the options listed in Connection Options in place of <conn_options>.

esxcli <conn_options> storage core claimrule move -r 1015 -n 1016

Running Path Claiming Rules

The esxcli storage core claimrule run command runs path claiming rules. Run this command apply claim rules that are loaded. If you do not call run, the system checks for claim rule updates every five minutes and applies them. Specify one of the options listed in Connection Options in place of <conn_options>.

To load and apply claim rules

1	Modify rules and load them.

esxcli <conn_options> storage core claimrule load

2	Quiesce the devices that use paths for which you want to change the rule and unclaim those paths.

esxcli <conn_options> storage core claiming unclaim --device=<device>

3	Run path claiming rules.

esxcli <conn_options> storage core claimrule run

This command is also used for troubleshooting and boot time configuration.

Options	Description
- -adapter <adapter> -A <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.
- -channel <channel> -C <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.
--claimrule-class -c	Claim rule class to use in this operation.
- -lun <lun> -L <lun>	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.
- -path <path_UID> -p <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.
- -target <target> -T <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
- -type <location|path|all> -t <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.
- -wait -w	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.