ESXi Learnswitch

ESXi Learnswitch is a complete implementation of MAC Learning and Filtering and is designed as a wrapper around the host virtual switch. It supports learning multiple source MAC addresses on virtual network interface cards (vNIC) and filters packets from egressing the wrong port based on destination MAC lookup. This substantially improves overall network throughput and system performance for nested ESX and container use cases.

Here are some of the new capabilities provided by the LearnSwitch module:

  • Overlay Network based learning and filtering are done in Etherswitch forwarding check
  • MAC Address learning is based on VLAN ID or VXLAN ID on uplink and leaf port
  • Packet is filtered on uplink and leaf port if the MAC is learned on a different port
  • MAC Address table size is 32k per system
  • MAC Address aging support with default aging time of 5 minutes and configurable
  • Unknown unicast packet is flooded by default and configurable to drop
  • vMotion support: learned MAC table is sent to destination host and RARP packet is sent
  • Standalone Kernel module available as a VIB
  • net-learnswitch CLI to display MAC Address table, configuration and stats

If you currently do not meet the requirements of the new Learnswitch, you can continue using the existing ESXi MAC Learn dvFilter, but it is recommended that you do not mix both on a single system but you can definitely make use of both solutions across different ESXi hosts depending on the constraints of your environment.

To learn more, read ESXi Learnswitch – Enhancement to the ESXi MAC Learn DvFilter.

  • Either a vSphere 6.5p01+ or vSphere 6.0 environment
  • ESXi host configured with a Distributed Virtual Switch (VDS)
  • Both Promiscuous Mode and Forged Transmit is still required on the outer VDS or Distributed Portgroup (applicable only for Nested ESXi use cases)
  • System with Python running to configure the LearnSwitch. (Make sure you have both python-six & python-yaml packages installed as this is needed by the script)

Step 1 - Download the package and extract its contents onto your desktop. You will find that it contains the following four files:


Step 2 - Copy either for an ESXi 6.5 host or for an ESXi 6.0 host. To install the VIB, run the following ESXCLI command:

esxcli software vib install -d />

Note: If you installed the VIB on an ESXi 6.0 system and you plan to upgrade to ESXi 6.5, make sure you uninstall the VIB before installing the 6.5 VIB.

Step 3 - Reboot the ESXi host for the changes to go into effect.

Step 4 - Extract the onto a system that has Python running.

Step 5 - Move the into the pyVpx directory that was created from the previous step and then change into pyVpx directory.

Step 6 - Finally, we need to enable the Learnswitch on the Distributed Portgroup(s) that we plan to use for our Nested ESXi workloads. To do so, we need to first edit the and update it with our vCenter Server credentials along with specifying the list of Distributed Portgroup(s) we want enabled. Look for the following section shown below and update it with your own environment configuration.

Here is an example of what this looks like for my environment:

vc_user = "administrator@vghetto.local"
vc_password = "VMware1!"

dvpg_name_list = [

Once you have saved your changes. Run the script with the "add" option and specify the Hostname/IP Address of your vCenter Server, the name of the Distributed Virtual Switch and the IP Address of your ESXi host (do not use hostname).

In my environment, I have the following:

vCenter Server =
ESXi Host =
VDS Name = VDS

python learnswitch_cfg VDS add

Note: If you have more than one ESXi host, you will need to run this script for each of the ESXi hosts.

At this point, you have now successfully installed and configured the new Learnswitch module. You can start deploying and running your Nested ESXi workload just as you did before but now rather than having to configure individual vNICs on your Nested ESXi VM to benefit from MAC Learning, you simply just place your Nested ESXi VMs on the Distributed Virtual Portgroups that have MAC Learning enabled, pretty easy right!?

If you want to disable the MAC Learn functionality on particular set of Distributed Virtual Portgroup(s), you just need to specify the "remove" option in the script by running the following:

python learnswitch_cfg VDS remove
If you wish to completely remove the Learnswitch module, after disabling the functionality on the Distributed Portgroup(s), you just need to uninstall the VIB and reboot the ESXi host. To do so, run the following ESXCLI command:
esxcli software vib remove -n esx-learnswitch

net-learnswitch CLI Examples

In addition to adding the LearnSwitch VMkernel module when installing the VIB, it also includes a really handy net-learnswitch command-line utility.

If you have a VM provisioned onto the Distributed Portgroup(s) which has the LearnSwitch enabled, you can run the following command and specify the name of your VDS to list more details:

net-learnswitch --instance VDS --list

You can also retrieve statistics for either the entire VDS instance or even filter on individual Distributed Portgroup(s) by using the following command:

net-learnswitch --instasnce VDS --stats

Another useful command is to dump out the entire MAC Address table and this is where you could identify aged MAC Addresses(s) that should be removed.

net-learnswitch --instance VDS --mac-address-table

For a complete list of options with the net-learnswitch CLI, you can specify the -h command.

Version 1.0.1

  • When VMs within 2 Nested ESXs on the same host are talking to each other, Learnswitch prevents these packets from going out on the uplink. It ended up filtering some unrelated packets as well, fixed the same.
Add a Comment
Report a Bug