How to use VMware vSphere PowerCLI to find a virtual machine by MAC address

Sometimes you need to find a virtual machine by MAC address. This can be very time consuming if you have to do this by hand using the VMware vSphere Client. PowerCLI can do this task for you in only a few seconds. The script presented in this blogpost will retrieve the virtual machine that has a certain MAC address.

You can find the virtual machine with a certain MAC address by just using the PowerCLI Get-VM and Get-NetworkAdapter cmdlets and piping these together. E.g. to find the virtual machine with MAC address “00:0c:29:1d:5c:ec” you can give the following PowerCLI command:

Get-VM | `
  Get-NetworkAdapter | `
  Where-Object {$_.MacAddress -eq "00:0c:29:1d:5c:ec"} | `
  Format-List -Property *

Figure 1. PowerCLI command to find a virtual machine with certain MAC address.

The PowerCLI command of figure 1 gives the following output:

Figure 2: Output of the command of figure 1.

In my environment with about five hundred fifty virtual machines this PowerCLI command takes about two minutes and twenty seconds to return.

So I decided to build a PowerCLI advanced function called Get-VmByMacAddress that uses the VMware vSphere SDK to find the virtual machine with a certain MAC address as fast as possible. The function uses PowerShell comment-based help. And there are some examples how you can use this function in the help.

function Get-VmByMacAddress {
  <#
  .SYNOPSIS
    Retrieves the virtual machines with a certain MAC address on a vSphere server.
	
  .DESCRIPTION
    Retrieves the virtual machines with a certain MAC address on a vSphere server.
	
  .PARAMETER MacAddress
    Specify the MAC address of the virtual machines to search for.
	
  .EXAMPLE
    Get-VmByMacAddress -MacAddress 00:0c:29:1d:5c:ec,00:0c:29:af:41:5c
	Retrieves the virtual machines with MAC addresses 00:0c:29:1d:5c:ec and 00:0c:29:af:41:5c.
	
  .EXAMPLE
    "00:0c:29:1d:5c:ec","00:0c:29:af:41:5c" | Get-VmByMacAddress
	Retrieves the virtual machines with MAC addresses 00:0c:29:1d:5c:ec and 00:0c:29:af:41:5c.
	
  .COMPONENT
    VMware vSphere PowerCLI
	
  .NOTES
    Author:  Robert van den Nieuwendijk
	Date:    18-07-2011
	Version: 1.0
  #>
  
  [CmdletBinding()]
  param(
    [parameter(Mandatory = $true,
	           ValueFromPipeline = $true,
			   ValueFromPipelineByPropertyName = $true)]
	[string[]] $MacAddress
  )
  
  begin {
    # $Regex contains the regular expression of a valid MAC address
	$Regex = "^[0-9A-Fa-f][0-9A-Fa-f]:[0-9A-Fa-f][0-9A-Fa-f]:[0-9A-Fa-f][0-9A-Fa-f]:[0-9A-Fa-f][0-9A-Fa-f]:[0-9A-Fa-f][0-9A-Fa-f]:[0-9A-Fa-f][0-9A-Fa-f]$"	
  
    # Get all the virtual machines
    $VMsView = Get-View -ViewType VirtualMachine -Property Name,Guest.Net
  }
  
  process {
    ForEach ($Mac in $MacAddress) {
	  # Check if the MAC Address has a valid format
	  if ($Mac -notmatch $Regex) {
	    Write-Error "$Mac is not a valid MAC address. The MAC address should be in the format 99:99:99:99:99:99."
	  }
	  else {	
        # Get all the virtual machines
        $VMsView | `
	      ForEach-Object {
            $VMview = $_
            $VMView.Guest.Net | Where-Object {
	          # Filter the virtual machines on Mac address
              $_.MacAddress -eq $Mac
            } | `
			  Select-Object -property @{N="VM";E={$VMView.Name}},
			    MacAddress,
			    IpAddress,
				Connected
		  }
      }
    }
  }
}

Figure 3: Get-VmByMacAddress PowerCLI advanced function.

The Get-VmByMacAddress function gives the following output:

Figure 4: Output of the Get-VMHostByMacAddress PowerCLI function.

The Get-VmByMacAddress function took about 1.7 seconds to complete. That is about eighty times faster than the first script.