Managing NMP with esxcli storage nmp

The NMP (Native Multipathing Plugin) is an extensible multipathing module that ESXi supports by default. You can use esxcli storage nmp to manage devices associated with NMP and to set path policies.

The NMP supports all storage arrays listed on the VMware storage Hardware Compatibility List (HCL) and provides a path selection algorithm based on the array type. The NMP associates a set of physical paths with a storage device (LUN). A Storage Array Type Plugin (SATP) determines how path failover is handled for a specific storage array. A Path Selection Plugin (PSP) determines which physical path is used to issue an I/O request to a storage device. SATPs and PSPs are plugins within the NMP plugin.

Device Management with esxcli storage nmp device

The device option performs operations on devices currently claimed by the VMware NMP plugin.

esxcli storage nmp device list

The list command lists the devices controlled by VMware NMP and shows the SATP and PSP information associated with each device. To show the paths claimed by NMP, run esxcli storage nmp path list to list information for all devices, or for just one device with the --device option.

Options	Description
- -device <device> -d <device>	Filters the output of the command to show information about a single device. Default is all devices.

esxcli storage nmp device set

The set command sets the Path Selection Policy (PSP) for a device to one of the policies loaded on the system.

Any device can use the PSP assigned to the SATP handling that device, or you can run esxcli storage nmp device set --device naa.xxx --psp <psp> to specifically override the PSP assigned to the device.

■

If a device does not have a specific PSP set, it always uses the PSP assigned to the SATP. If the default PSP for the SATP changes, the PSP assigned to the device changes only after reboot or after a device is reclaimed. A device is reclaimed when you unclaim all paths for the device and reclaim the paths.

■	If you use esxcli storage nmp device set to override the SATPs default PSP with a specific PSP, the PSP changes immediately and remains the user-defined PSP across reboots. A change in the SATP’s PSP has no effect.

Use the --default option to return the device to using the SATP’s PSP.

Options	Description
- -default -E	Sets the PSP back to the default for the SATP assigned to this device.
- -device <device> -d <device>	Device to set the PSP for.
- -psp <PSP> -P <PSP>	PSP to assign to the specified device. Call esxcli storage nmp psp list to display all currently available PSPs. See Supported Path Policies. See vSphere Storage for a discussion of path policies.

To set the path policy for the specified device to VMW_PSP_FIXED, run the following command:

esxcli <conn_options> storage nmp device set - -device naa.xxx - -psp VMW_PSP_FIXED

Listing Paths with esxcli storage nmp path

Use the path option to list paths claimed by NMP. By default, the command displays information about all paths on all devices. You can filter in the following ways:

■	Only show paths to a singe device (esxcli storage nmp path list --device <device>).

■	Only show information for a single path (esxcli storage nmp path list --path=<path>.

To list devices, call esxcli storage nmp device list.

Managing Path Selection Policy Plugins with esxcli storage nmp psp

Use esxcli storage nmp psp to manage VMware path selection policy plugins included with the VMware NMP plugin and to manage third-party PSPs.

Important When used with third-party PSPs, the syntax depends on the third-party PSP implementation.

Retrieving PSP Information

The esxcli storage nmp psp generic deviceconfig get and esxcli storage nmp psp generic pathconfig get command retrieves PSP configuration parameters. The type of PSP determines which command to use.

■	Use nmp psp generic deviceconfig get for PSPs that are set to VMW_PSP_RR, VMW_PSP_FIXED or VMW_PSP_MRU.

■	Use nmp psp generic pathconfig get for PSPs that are set to VMW_PSP_FIXED or VMW_PSP_MRU. No path configuration information is available for VMW_PSP_RR.

To retrieve PSP configuration parameters, use the appropriate command for the PSP.

■	Device configuration information.

esxcli <conn_options> storage nmp psp generic deviceconfig get --device=<device>

esxcli <conn_options> storage nmp psp fixed deviceconfig get --device=<device>

esxcli <conn_options> storage nmp psp roundrobin deviceconfig get --device=<device>

■	Path configuration information.

esxcli <conn_options> storage nmp psp generic pathconfig get --path=<path>

■	Retrieve the PSP configuration for the specified path.

esxcli <conn_options> nmp psp pathconfig generic get - -path vmhba4:C1:T2:L23

The esxcli storage nmp psp list command shows the list of Path Selection Plugins on the system and a brief description of each plugin.

Setting Configuration Parameters for Third-Party Extensions

The esxcli storage nmp psp generic deviceconfig set and esxcli storage nmp psp generic pathconfig set commands support future third-party PSA expansion. The setconfig command sets PSP configuration parameters for those third-party extensions.

Note The precise results of these commands depend on the third-party extension. See the extension documentation for information.

Use esxcli storage nmp roundrobin setconfig for other path policy configuration. See Customizing Round Robin Setup.

You can run esxcli storage nmp psp generic deviceconfig set --device=<device> to specify PSP information for a device, and esxcli storage nmp psp generic pathconfig set --path=<path> to specify PSP information for a path. For each command, use --config to set the specified configuration string.

Options	Description
- -config <config_string> -c <config_string>	Configuration string to set for the device or path specified by --device or - -path. See Supported Path Policies.
- -device <device> -d <device>	Device for which you want to customize the path policy.
- -path <path> -p <path>	Path for which you want to customize the path policy.

Fixed Path Selection Policy Operations

The fixed option gets and sets the preferred path policy for NMP devices configured to use VMW_PSP_FIXED.

Retrieving the Preferred Path

The esxcli storage nmp fixed deviceconfig get command retrieves the preferred path on a specified device that is using NMP and the VMW_PSP_FIXED PSP.

Options	Description
- -device <device> -d <device>	Device for which you want to get the preferred path. This device must be controlled by the VMW_PSP_FIXED PSP.

To return the path configured as the preferred path for the specified device, run the following command. Specify one of the options listed in Connection Options in place of <conn_options>.

esxcli <conn_options> storage nmp fixed deviceconfig get - -device naa.xxx

Setting the Preferred Path

The esxcli storage nmp fixed deviceconfig set command sets the preferred path on a specified device that is using NMP and the VMW_PSP_FIXED path policy.

Options	Description
- -device <device> -d <device>	Device for which you want to set the preferred path. This device must be controlled by the VMW_PSP_FIXED PSP. Use esxcli storage nmp device - -list to list the policies for all devices.
- -path <path> -p <path>	Path to set as the preferred path for the specified device.

To set the preferred path for the specified device to vmhba3:C0:T5:L3, run the following command. Specify one of the options listed in Connection Options in place of <conn_options>.

esxcli <conn_options> storage nmp fixed deviceconfig set - -device naa.xxx --path vmhba3:C0:T5:L3

Customizing Round Robin Setup

The esxcli storage nmp psp roundrobin commands sets round robin path options on a device controlled by the VMW_PSP_RR PSP. Specify one of the options listed in Connection Options in place of <conn_options>.

To specify and customize round robin path policies

1	Set the path policy to round robin.

esxcli <conn_options> storage nmp device set - -device naa.xxx - -psp VMW_PSP_RR

2	Specify when to switch paths.

You can choose the number of I/O operations, number of bytes, and so on. For example:

esxcli <conn_options> storage nmp psp roundrobin deviceconfig set - -type "bytes" -B 12345 - -device naa.xxx

Sets the device specified by - -device to switch to the next path each time 12345 bytes have been sent along the current path.

esxcli <conn_options> storage nmp psp roundrobin deviceconfig set - -type=iops - -iops 4200 - -device naa.xxx

Sets the device specified by - -device to switch after 4200 I/O operations have been performed on a path.

Retrieving Path Selection Settings

The esxcli storage nmp psp roundrobin deviceconfig get command retrieves path selection settings for a device that is using the roundrobin PSP. You can specify the device to retrieve the information for.

Options	Description
-d <device> - -device <device>	Device to get round robin properties for.

Specifying Conditions for Path Changes

The esxcli storage nmp psp roundrobin deviceconfig set command specifies under which conditions a device that is using the VMW_PSP_RR PSP changes to a different path. You can use - -bytes or - -iops to specify when the path should change.

Options	Description
- -bytes -B	Number of bytes to send along one path for this device before the PSP switches to the next path. You can use this option only when - -type is set to bytes.
- -device -d	Device to set round robin properties for. This device must be controlled by the round robin (VMW_PSP_RR) PSP.
- -iops -I	Number of I/O operations to send along one path for this device before the PSP switches to the next path. You can use this option only when - -type is set to iops.
- -type -t	Type of round robin path switching to enable for this device. The following values for type are supported: ■ bytes: Set the trigger for path switching based on the number of bytes sent down a path. ■ default: Set the trigger for path switching back to default values. ■ iops: Set the trigger for path switching based on the number of I/O operations on a path. An equal sign (=) before the type or double quotes around the type are optional.
- -useANO -U	If set to 1, the round robin PSP includes paths in the active, unoptimized state in the round robin set. If set to 0, the PSP uses active, unoptimized paths only if no active optimized paths are available. Otherwise, the PSP includes only active optimized paths in the round robin path set.

Managing SATPs

The esxcli storage nmp satp commands manage SATPs. You can use these commands to perform the following tasks:

■	Retrieve and set configuration parameters

■	Add and remove rules from the list of claim rules for a specified SATP

■	Set the default PSP for a specified SATP

■	List SATPs that are currently loaded into NMP and the associated claim rules

The default SATP for an active-active FC array with a vendor and model not listed in the SATP rules is VMW_SATP_DEFAULT_AA.

Retrieving Information About SATPs

The esxcli storage nmp satp list command lists the SATPs that are currently available to the NMP system and displays information about those SATPs. This command supports no options and displays information about these SATPs.

esxcli <conn_options> storage nmp satp list

The rule list command lists the claim rules for SATPs.

esxcli <conn_options> storage nmp satp rule list

Adding SATP Rules

Claim rules specify that a storage device that uses a certain driver or transport or has a certain vendor or model should use a certain SATP. The esxcli storage nmp satp rule add command adds a rule that performs such a mapping to the list of claim rules. The options you specify define the rule. For example, the following command specifies that if a path has vendor VMWARE and model Virtual, the PSA assigns it to the VMW_SATP_LOCAL SATP.

esxcli <conn_options> storage nmp satp rule add - -satp="VMW_SATP_LOCAL" - -vendor="VMWARE" - -model="Virtual" - -description="VMware virtual disk”

Option	Description
- -driver -D	Driver string to set when adding the SATP claim rule.
--device -d	Device to set when adding SATP claim rules. Device rules are mutually exclusive with vendor/model and driver rules.
--force -f	Force claim rules to ignore validity checks and install the rule even if checks fail.
- -model -M	Model string to set when adding the SATP claim rule. Can be the model name or a pattern ^mod*, which matches all devices that start with mod. That is, the pattern successfully matches mod1 and modz, but not mymod1. The command supports the start/end (^) and wildcard (*) functionality but no other regular expressions.
- -transport -R	Transport string to set when adding the SATP claim rule. Describes the type of storage HBA, for example, iscsi or fc.
- -vendor -V	Vendor string to set when adding the SATP claim rule.
--satp -s	SATP for which the rule is added.
- -claim-option -c	Claim option string to set when adding the SATP claim rule.
- -description -e	Description string to set when adding the SATP claim rule.
- -option -o	Option string to set when adding the SATP claim rule. Surround the option string in double quotes, and use a space, not a comma, when specifying more than one option. “enable_local enable_ssd”.
--psp -P	Default PSP for the SATP claim rule.
--psp-option -O	PSP options for the SATP claim rule.
--type -t	Set the claim type when adding a SATP claim rule.

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

■	Add a SATP rule that specifies that disks with vendor string VMWARE and model string Virtual should be added to VMW_SATP_LOCAL.

esxcli <conn_options> storage nmp satp rule add - -satp="VMW_SATP_LOCAL" - -vendor="VMWARE"

- -model="Virtual" - -description="VMware virtual disk"

■	Add a SATP rule that specifies that disks with the driver string somedriver should be added to VMW_SATP_LOCAL.

esxcli <conn_options> storage nmp satp rule add - -satp="VMW_SATP_LOCAL" - -driver="somedriver"

■	Add a rule that specifies that all storage devices with vendor string ABC and a model name that starts with 120 should use VMW_SATP_DEFAULT_AA (VMW_SATP_DEFAULT_AA is an example).

esxcli <conn_options> storage nmp satp rule add - -satp VMW_SATP_DEFAULT_AA - -vendor="ABC" - -model="^120*

Removing SATP Rules

The esxcli storage nmp satp rule remove command removes an existing SATP rule. The options you specify define the rule to remove. The options listed for Adding SATP Rules are supported.

The following example removes the rule that assigns devices with vendor string VMWARE and model string Virtual to VMW_SATP_LOCAL.

esxcli <conn_options> storage nmp satp rule remove

- -satp="VMW_SATP_LOCAL" - -vendor="VMWARE" - -model="Virtual"

Retrieving and Setting SATP Configuration Parameters

The esxcli storage nmp satp generic deviceconfig get and esxcli storage nmp satp generic pathconfig get commands retrieve per-device or per-path SATP configuration parameters. You cannot retrieve paths or devices for all SATPs, you must retrieve the information one path or one device at a time.

Use this command to retrieve per device or per path SATP configuration parameters, and to see whether you can set certain configuration parameters for a device or path.

For example esxcli storage nmp satp generic deviceconfig get --device naa.xxx might return SATP VMW_SATP_LSI does not support device configuration.

esxcli storage nmp satp generic pathconfig get -path vmhba1:C0:T0:L8 might return INIT,AVT OFF,v5.4,DUAL ACTIVE,ESX FAILOVER

The esxcli storage nmp satp generic deviceconfig set and esxcli storage nmp satp generic pathconfig set commands set configuration parameters for SATPs that are loaded into the system, if they support device configuration. You can set per-path or per-device SATP configuration parameters.

Important The command passes the configuration string to the SATP associated with that device or path.

The configuration strings might vary by SATP. VMware supports a fixed set of configuration strings for a subset of its SATPs. The strings might change in future releases.

Options	Description
- -config -c	Configuration string to set for the path specified by - -path or the device specified by - -device. You can set the configuration for the following SATPs: ■ VMW_SATP_ALUA_CX ■ VMW_SATP_ALUA ■ VMW_SATP_CX ■ VMW_SATP_INV You can specify one of the following device configuration strings: ■ navireg_on – starts automatic registration of the device with Navisphere. ■ navireg_off – stops the automatic registration of the device. ■ ipfilter_on – stops the sending of the host name for Navisphere registration. Used if host is known as localhost. ■ ipfilter_off – enables the sending of the host name during Navisphere registration.
- -device -d	Device to set SATP configuration for. Not all SATPs support the setconfig option on devices.
- -path -p	Path to set SATP configuration for. Not all SATPs support the setconfig option on paths.

Run esxcli storage nmp device set --default --device=<device> to set the PSP for the specified device back to the default for the assigned SATP for this device.