Loading

×Sorry to interrupt
CSS Error

Refresh

Cookie Preference Center

General Information on cookies

When you visit our website, we use cookies to ensure that we give you the best experience. This information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies by clicking on the different category headings to find out more and change your settings. However, blocking some types of cookies may impact your experience on the site and the services we are able to offer. Further information can be found in our

Cookie Policy.

Strictly Necessary

Strictly Necessary

Always Active

Strictly Necessary

Strictly necessary cookies are always enabled since they are essential for our website to function. They enable core functionality such as security, network management, and website accessibility. You can set your browser to block or alert you about these cookies, but this may affect how the website functions. For more information please visit www.aboutcookies.org or www.allaboutcookies.org.

Cookie Details‎

Performance

Performance

Performance

Performance cookies are used to analyze the user experience to improve our website by collecting and reporting information on how you use it. They allow us to know which pages are the most and least popular, see how visitors move around the site, optimize our website and make it easier to navigate.

Cookie Details‎

Please confirm your settings by refreshing the page.

Functional

Functional

Functional

Functional cookies help us keep track of your past browsing choices so we can improve usability and customize your experience. These cookies enable the website to remember your preferred settings, language preferences, location and other customizable elements such as font or text size. If you do not allow these cookies, then some or all of these services may not function properly.

Cookie Details‎

Advertising

Advertising

Advertising

Advertising cookies are used to send you relevant advertising and promotional information. They may be set through our site by third parties to build a profile of your interests and show you relevant advertisements on other sites. These cookies do not directly store personal information, but their function is based on uniquely identifying your browser and internet device.

Cookie Details‎

Advertising Cookies

Consent Leg.Interest

Select All Vendors

Select All Vendors

Select All Hosts

Select All

Clear Filters

Information storage and access

Apply

Confirm My Choices Reject All Allow All

Skip to main content

My Subscriptions

Loading

Knowledge Base

How VMware ESXi determines the order in which names are assigned to devices (2091560)

Last Updated: 3/17/2023Categories: InformationalTotal Views: 50293Language:
Chinese (Simplified)JapaneseEnglish

93 like this article

Subscribe to get an email
newsletter with new updates

93 people found this helpful Please provide article feedback:

Learn how VMware Skyline Advisor and Skyline Health Diagnostics work together to provide proactive intelligence and self-service log analysis.

Use Skyline Advisor to avoid issues before they occur across VCF, vSphere, vSAN, NSX, vROps & Horizon. Skyline Findings are based on top KBs, VMSAs/CVEs and design best practices.

Use Skyline Health Diagnostics to root cause vSphere & vSAN logs when an issue occurs. Skyline Health Diagnostic Findings are based on top KBs and VMSA/CVEs. You can use the Skyline Health Diagnostics tool in online or offline mode.

If you require additional help from technical support, please use Skyline Advisor to initiate a Log Assist to reduce time to upload logs. TSEs can also initiate logs to reduce effort.

Purpose

This article provides the new algorithm used beginning in ESXi 5.5 to assign short names (called aliases or device names) to the various input/output ports of a modern server system. This article also explains how you can change the aliases if needed. The ESXi now assigns devices in an improved and more uniform, stable and predictable fashion.

This document will discuss primarily network device naming but the concepts and algorithms presented here apply to storage adapters and graphics devices as well. Network devices are aliased as vmnicN, where N is an integer.

Similarly, storage adapters have aliases in the form of vmhbaN, and a graphics device alias looks like vmgfxN. See the additional information section for more information on the numbers used.

Cause

Starting in ESXi 5.5 the device alias assignment function was made a part of a newly designed device manager, and the device alias assignment upgraded as described in this document. This was done because in ESXi releases earlier to 5.5, there was little documentation of the assignment of aliases to physical (or logical) devices. Additionally, device assignments made by specialized programs (esxcfg-init and later jumpstart plug-in) were difficult to correlate with case markings, and difficult to predict for a new machine before ESXi installation. Finally, the assignments could change across reboots when other devices were added or removed from the system.

Resolution

On initial install, the new naming scheme tries to assign names in a predictable order by physical location. Thereafter it keeps a device's name stable even across the addition or removal of other devices to the system. At install time, typically devices that are integrated on the system's motherboard receive the lowest numbered names, in the order that their output ports are numbered on the system's case, and devices that are in pluggable slots receive the next highest numbered names, in the order that the slots are numbered on the case. The reader should note that this process ignores devices for which no driver is found.

Device Name Assignment
After the ESXi device manager has an ordered list of information for devices in the system, it can assign aliases to these devices according to their types: network, storage, or graphics adapter.

New installation/autodeploy
In the case of a new installation or autodeploy with no host profile, the device manager will query the machine's firmware to get location information for each port, generally including which ports are onboard, which are in pluggable slots, and how those ports and slots are numbered on the system's case. ESXi then assigns aliases to the ports from 0 upwards in order of onboard ports first, then ports not described by the firmware, then ports in pluggable slots.

If a system has:

Two onboard network ports

One single-port NIC in slot #3

One dual-port NIC in slot#5

Then devices names should be assigned as:

Physical Port

Device Alias

Onboard port 1

vmnic0

Onboard port 2

vmnic1

Slot #3 port 1

vmnic2

Slot #5 port 1

vmnic3

Slot #5 port 2

vmnic4

This should produce uniform device name assignments across a population of identical and freshly installed or deployed hosts. The assignment will generally be predictable from the rules described, assuming the host's firmware provides the necessary information and no special situations arise.

On stateful hosts, alias assignments are immediately recorded in persistent local storage. On stateless hosts, alias assignments are part of the host profile and are thus recorded and persistent whenever the system administrator captures the profile.

Hardware changes and device aliases
Changes to the hardware configuration are subject to these rules:

When cards are added or removed after the initial installation, ports remaining retain their assigned names.

ESXi assigns a new port to the first available unassigned alias for its type.

The alias for a removed port becomes available.

A replaced port may be seen either as being the same as the original port or as a removal followed by an addition. In the former case, the new port has the same alias. In the later case, it may acquire the same alias.This occurs if the old alias is the lowest-numbered free alias.

In the event the replacement device has more ports, these will be assigned the next available unassigned alias(es) of its type. A replacement device with fewer ports will release the unused aliases for re-assignment.

Where the system is configured with a host profile the system administrator should capture an updated profile after the hardware changes.

ESXi Upgrades
Upgrades from one release of ESXi to the next, including autodeploy configurations, do not change the aliases previously assigned to the system's ports. This includes upgrading from prior releases to ESXi 5.5 and later.

Note: In rare cases, aliases can change across an ESXi upgrade or patch installation, due to ESXi parsing the firmware device location information. For example, in ESXi, NICs are named in vmnicN format, where N is a number ranging from 0 upward, where other vendors may name them different: ESXi vmnic order changed after adding more vNICs in UCS Service Profile.
If you need to correct a changed alias, follow the procedure in "Changing the names assigned by the ESXi host" below.

With stateful systems, the aliases are preserved through the upgrade in local storage and a host profile, if one exists. Stateless systems have device alias assignments recorded in the host profile. However, host profiles from releases earlier than ESXi 5.5 will not contain the alias assignments. Where a release prior to 5.5 is upgraded to 5.5 or later, ESXi recognizes this case and uses the original pre ESXi 5.5 alias assignment algorithm, to prevent alias reassignment across this kind of upgrade. After a stateless upgrade, VMware recommends capturing a new host profile so that device assignments remains stable.

To upgrade a cluster of homogenous stateless hosts from one release to another:

Upgrade the auto-deploy server with the new ESXi image.

Remove the reference host from the cluster.

Reboot the reference host with the new ESXi image.

Extract a host profile.

If any device names are not what you expect, edit the device alias section of the host profile.

Reboot the reference host with the new profile.

If the host is now configured as desired, attach the host profile to the remainder of the hosts, otherwise repeat from step 5.

Reattach the reference host back to the cluster.

Reboot the rest of the cluster (typically a rolling reboot).

Device Types and Name Persistence

Physical Devices
Most drivers create device objects that map one to one with physical PCI functions. The range of aliases reserved for these physical devices begins at 0. Some drivers create objects that are not mapped one to one with physical functions. For native drivers, these aliases are recorded persistently, in local storage (on stateful systems) and/or in the host profile.

Logical Devices
Drivers built on ESXi's native driver framework can create logical devices with additional devices that do not correspond with PCI functions. These devices are assigned higher numbered aliases at the time their driver first creates them, in an unspecified order. Just as with aliases for physical devices, aliases for logical devices are persistent across reboots in local storage and/or in the host profile. As an example, consider a converged network adapter (CNA) whose PCI class identifies it as a network device, but whose native driver exports both a network uplink object and an iSCSI storage adapter object. In this case, the network uplink would be a physical device, perhaps with alias vmnic1, while the iSCSI adapter would be a logical device, perhaps with the alias vmhba64.

Pseudo-logical Devices
Drivers built on ESXi's Linux driver compatibility layer vmklinux can create pseudo-logical devices. As with true logical devices, these devices do not correspond one-to-one with PCI functions. In general, their aliases are not guaranteed persistent across reboots. However, certain vmklinux drivers may use special algorithms to provide persistence, such as inserting digits into the corresponding persistent physical device alias in a fixed pattern. With other vmklinux drivers, the pseudo-logical device aliases are generally assigned in a deterministic way and thus do not change from boot to boot if the set of hardware and drivers installed in the system remains the same, but again this is not guaranteed.

Special Situations
This section discusses a few special situations where the results may seem unexpected. It is not exhaustive.

Devices Without Drivers
As stated, aliases are assigned only for devices that have drivers. For example, if the ESXi release that is initially installed on a machine that does not have a driver for one of the machines NICs, that NIC's ports do not receive vmnic aliases. Numbers will not be reserved for them in the sequence. If ESXi is later upgraded to a release that does support the NIC, those ports receive the next available unused aliases, as if the NIC is newly added. This can put the aliases in a different order than would be seen in a fresh install of the new ESXi release on the same machine.

What Devices Are Onboard
On certain systems, ports that a user may think of as being integrated are actually on pluggable PCI/PCIe cards. For example, on systems from at least one vendor, several network ports that are standard equipment included with the base system and may be perceived as onboard by the end customer, are actually on a PCIe card that is factory installed in the highest numbered slot. Therefore, they appear later in the vmnic alias order than any NICs that may be added in other slots.

As another example, on blade systems there is often not a clear distinction between which devices are onboard and which are pluggable. The blade chassis may provide a way to move devices between different blades, or even to create and remove multiple virtual devices and assign them to different blades. In these cases, the detailed rules in the next section still apply.

Typically, a hardware vendor is likely to provide M1/M2 information for devices that are hardwired to a single blade and S1/S2/S3 for devices that are assignable. Alternatively, the hardware vendor can provide M1 information for all devices, which gives the vendor full control over the order in which ESXi assigns names. See the next section, Device Information and Naming for an explanation of the information source tags, M1, M2, S1, S2, and S3.

Device Information and Naming
ESXi assigns names to all the devices having drivers that it finds.

Information Sources

Note: The ACPI specification does not designate 0 as a special value for _SUN, so ESXi 6.7 and earlier accept 0 as a possible number for a pluggable slot, expecting devices that are not in pluggable slots (that is, motherboard integrated or other non-removable devices) not to have a _SUN method.  However, VMware has seen an increasing number of systems that provide a _SUN method that returns 0 for some motherboard devices.  To allow finding the correct motherboard location of such devices, ESXi 7.0 and later ignores _SUN methods that return 0.

ESXi obtains device location information from these sources. For each device, these sources are consulted in order until information is found from one of them.

Tag

Device Data Source

Device Information Specification

M1

PCIe _DSM for Device Naming

PCIe Firmware Specification, Rev. 3.1, section 4.6.7, DSM for Naming a PCI or PCI Express Device Under Operating Systems

M2

SMBIOS Type 41 Structure

System Management BIOS (SMBIOS) Reference Specification, Version 2.6 or later, section Onboard Devices Extended Information (Type 41)

S1

ACPI _SUN Object

Advanced Configuration and Power Interface Specification (ACPI), Revision 5.0, section 6.1.11 _SUN (Slot User Number). The _SUN method for the PCI function is tried first; then if that does not exist, the _SUN method for function 0 of the same PCI device is tried

S2

Legacy $PIR Table

Legacy $PIR table: PCI System Architecture, 4th Edition, MindShare, Inc., Tom Shanley and Don Anderson, Interrupt Routing Table, pages 233-238

S3

SMBIOS Type 9 Structure

System Management BIOS (SMBIOS) Reference Specification, Version 2.6 or later, section System Slots (Type 9)

P

PCI SBDF Address

The device's current PCI SBDF (segment:bus:device.function) address

Sources tagged M1-M2 typically apply to on-board devices, though source M1 can be present for any device. Sources S1-S3 apply to devices in pluggable slots. Source P provides no real location information and is not necessarily stable across addition/removal of other devices to the system, so it is used only as a last resort.

Naming
After these information sources are consulted for all devices having drivers, devices within each type are sorted and named in this order:

Devices whose information came from M1 or M2, in the port number order given by that information.

Devices whose information came from P. These are often onboard devices for which the hardware platform vendor has not supplied M1 or M2 information.

Devices whose information came from S1, S2, or S3, in slot number order. If more than one device is in the same slot such as with a typical multi-port NIC, devices within the slot are sorted in PCI SBDF order.

Note: In rare cases, aliases can change across an ESXi upgrade or patch installation, as a side effect of a bugfix or workaround having been added in ESXi's parsing of firmware device location information. If you need to correct a changed alias, follow the procedure in "Changing the names assigned by the ESXi host" below.

Changing the names assigned by the ESXi host

In some cases you may want to change the aliases assigned by the ESXi host. The procedure is as follows:

If you are using Host Profiles

If the affected system is attached to a Host Profile, edit the Device Alias Configuration component of the profile, which is found under the General System Settings in the profile. Then remediate the affected ESXi host.

Note: The host must be rebooted to complete the remediation.

If you are not using Host Profiles

From the ESXi shell, run the command to see the current assignment of aliases to device locations:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias list

Output:

Bus type  Bus address          Alias
------------------------------------
pci       s00000007.00         vmnic2
pci       s00000008.00         vmnic4
pci       s00000008.01         vmnic5
pci       s00000008.03         vmnic7
pci       s00000008.02         vmnic6
pci       s00000002.01         vmnic1
pci       s00000002.00         vmnic0
pci       s00000007.01         vmnic3
logical   pci#s00000008.02#0   vmnic6
logical   pci#s00000008.00#0   vmnic4
logical   pci#s00000008.01#0   vmnic5
logical   pci#s00000008.03#0   vmnic7

When a nic is controlled by a native driver, then there are actually two aliases associated with the device: a pci alias for the pci device and a logical alias for the uplink logical device.  For Example, we see two aliases for vmnic7 here:

localcli --plugin-dir /usr/lib/vmware/esxcli/int deviceInternal alias list | grep vmnic7
pci       s00000008.03        vmnic7
logical   pci#s00000008.03#0  vmnic7

For each alias that you want to reassign, use the command:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type pci --alias vmnicN --bus-address B

When the logical alias is present, then both the pci alias and logical alias need to be renamed:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type logical --alias vmnicN --bus-address B

where the vmnicN and B are the new assignment that you want to make. For instance, in the above example you could swap vmnic0 and vmnic7 using the commands:

localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type pci --alias vmnic0 --bus-address s00000008.03
localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type pci --alias vmnic7 --bus-address s00000002.00
localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type logical --alias vmnic0 --bus-address "pci#s00000008.03#0"
localcli --plugin-dir /usr/lib/vmware/esxcli/int/ deviceInternal alias store --bus-type logical --alias vmnic7 --bus-address "pci#s00000002.00#0"

After giving all the necessary alias store commands, perform a clean shut down and reboot the system.

NOTE: Ensure you have a console access before executing the above steps.

Related Information

Device Numbering Information
Currently, these alias numbering assignments are used:

For physical PCI aliases:

vmnic: 0-31, 64-127

vmhba: 0-31

vmgfx: 0-31

For native driver logical aliases:

vmnic: 128-1000000

vmhba: 64-95, 128-159, ...

vmgfx: 32 - 1000000

For vmlinux logical aliases:

vmnic: 32-63, 1000000-MAX

vmhba: 32-63, 96-127, ...

Counting physical PCI functions, VMware supports names for 32 HBA and GFX adapters, and 96 NICs.

Multiple pseudo-logical device alias assignments
Some devices make multiple ports available at the same PCI address. This is a brief description of the algorithm used to assign aliases in this case.

Requirements:

Standard Naming convention (for example, vmnicX where X is a decimal number)

Need to have persistence across reboots for logical uplinks.

Algorithm: for each device with multiple ports of the same type, indicated here by relative port numbers port 1, port 2, etc:

port 1 - Assign the PCI alias (the number will be from the range of 0-31 or 64-127)

port 2 (and higher) - Gets its alias number in million range, as explained in step 3

In order to enable persistence for additional ports, perform this approach. The number for each alias is obtained using this formula:

1000000 + (pciIndex*100) + p#

Where:

pciIndex: is the number in the PCI alias.
p#: is the relative port number

For example: If PCIe function gets a name as vmnic4, then:
lspci : 00:04:00.0 - vmnic4
and
Port1 gets vmnic4
Port2 gets vmnic1000402
Port3 gets vmnic1000403

This method allows defining up to 100 pseudo devices for a single PCIe PF (physical function).

VMware ESXi がデバイスに割り当てる名称の順序について
VMware ESXi 如何确定为设备分配名称的顺序

Detectable by VMware SkylineTM

Actions

Copy

link to clipboard
copied!

Print

Language:
Chinese (Simplified)JapaneseEnglish

Attachments

Additional Resources

KB
•
End Of General Availability of the Free vSphere Hypervisor (ESXi 7.x and 8.x) (2107518)

Result 1 of 1

Ask The Community

Get answers quickly from VMware experts in the community

Post Subject

CONTINUE IN COMMUNITIES

Related Products:

VMware vSphere ESXi

Related Versions:

Take Our Survey

Was this article helpful?

YES

NO

Copyright © 2005-2024 Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries.

Terms of Use

Your California Privacy Rights

Privacy

Accessibility

Cookie Settings

Support Assistant