How to set Hyper-V promiscuous mode for monitoring external traffic

A Hyper-V related question that shows regularly up in the forums is how to setup virtual switch ports in promiscuous mode so that external traffic can be received / monitored on the host’s root partition or on virtual machines.

Hyper-V 2012 introduced the concept of port monitoring (also called port mirroring) which can be enabled on any virtual machine network adapter or on the host. The interesting part is that there’s quite some official documentation available if you want to setup port monitoring / mirroring between two or more VMs, but you are almost on your own if you want to capture traffic coming from an external network or from the host root partition. PowerShell APIs, which do a great job in setting up port monitoring between VMs, are quite convoluted and obscure when it comes to host monitoring settings.

This blog post has the purpose of explaining how to handle non trivial Hyper-V promiscuous mode requirements and introduces a simple PowerShell module to easily handle port monitoring settings on the host.

How does port monitoring / mirroring work?

The Hyper-V port monitoring functionality is already well explained elsewhere, so I’ll keep the basics to the minimum here. In short, unlike other virtualization solutions like VMWare ESXi where you set an entire virtual switch or group of ports in promiscuous mode, in Hyper-V you need to enable monitoring on each switch port individually, for either VM network adapters (vNICs) or host adapters (NICs).

Furthermore, Hyper-V does not let you simply set a “promiscuous mode” flag on a port, as you need to specify if a given port is supposed to be the source or the destination of the network packets, “mirroring” the traffic, hence the name.

The Hyper-V PowerShell module does a great job in making life easy from this perspective, for example:

where -PortMirroring can be Source, Destination or None. If you have multiple adapters on a VM you’d most probably want to choose which adapter to configure:

What about external traffic?

There are quite a few scenarios where you want to be able to receive on a VM all the traffic coming from an external network. Some of the most typical use cases include network intrusion detection systems (NIDS), monitoring tools (Wireshark, Message Analyzer, tcpdump, etc) or software defined networking (SDN) routers / switches, like for example Open vSwitch.

The PowerShell cmdlets (Add-VMSwitchExtensionPortFeature, Get-VMSystemSwitchExtensionPortFeature, etc) that can be used to manage port monitoring at the host level are not exactly user friendly and don’t cover all the relevant uses cases when it comes to internal ports. Beside the reference documentation, there are a few forum posts providing some info on how to use them, but not much more at the time of writing. Here’s an example for setting the port monitoring mode of a switch host NIC to source:

With the above example, all traffic passing on the external network NIC of MySwitch will be “mirrored” to any VM whose port monitoring mode has been set to destination.

Internal switches and shared for management NICs

There are two scenarios which are not covered by the previous example: internal switches, used manly for root partition / guest communication and external switches shared for management (i.e. created with New-VMSwitch -ManagementOS $true in PowerShell).

In those cases the above example becomes:

By specifying -ManagementOS it becomes unfortunately not possible to specify the switch, so the monitoring mode will be set for every internal switch and shared management NIC port on the host!

An easier way to set host NIC monitoring mode in PowerShell

The complications and limitations of the PowerShell cmdlets outlined above led to writing a simplified set of PowerShell commands, where enabling port monitoring on external or internal switches gets as simple as:

The module is available here.

How to check the status of port monitoring on a given switch:

Disabling monitoring is also very easy:

In case of external switches shared for management, you can set different port monitoring settings for the external and internal NICs by simply adding the -PortType parameter specifying either Host or Internal.

Edit (Dec 5th, 2020): Starting with Windows Server 2019, consider setting the destination VM network adapter in trunk mode, as described below, even if you don’t use VLANs. Many thanks to Gian Maria for bringing this up! 

How to monitor VLAN tagged traffic?

Traffic generated on a VM with a vNIC set to tag traffic with a VLAN id cannot be directly monitored on another VM, unless trunking is set on the target. For example, let’s say that we want to monitor the traffic between two VMs (VM1 and VM2) on a third VM (VM3), with packets tagged with VLAN id 100.

VM1 and VM2:

VM3 (monitoring):

Monitoring traffic on VM3 while pinging VM2 from VM1 will show something like the following tcpdump output, where the packets 802.1Q (VLAN) info is highlighted by the red ellipse: