Manage packet captures for virtual machines with Azure Network Watcher using PowerShell

The Network Watcher packet capture tool allows you to create capture sessions to record network traffic to and from an Azure virtual machine (VM). Filters are provided for the capture session to ensure you capture only the traffic you want. Packet capture helps in diagnosing network anomalies both reactively and proactively. Its applications extend beyond anomaly detection to include gathering network statistics, acquiring insights into network intrusions, debugging client-server communication, and addressing various other networking challenges. Network Watcher packet capture enables you to initiate packet captures remotely, alleviating the need for manual execution on a specific virtual machine.

In this article, you learn how to remotely configure, start, stop, download, and delete a virtual machine packet capture using Azure PowerShell. To learn how to manage packet captures using the Azure portal or Azure CLI, see Manage packet captures for virtual machines using the Azure portal or Manage packet captures for virtual machines using the Azure CLI.

Prerequisites

• An Azure account with an active subscription. Create a trial subscription.

• Azure PowerShell.

  You can install Azure PowerShell locally to run the cmdlets. This article requires the Az PowerShell module. For more information, see How to install Azure PowerShell. To find the installed version, run Get-InstalledModule -Name Az. If you run PowerShell locally, sign in to Azure using the Connect-AzAccount -Environment AzureChinaCloud cmdlet.

• A virtual machine with the following outbound TCP connectivity:

  • to the storage account over port 443
  • to 169.254.169.254 over port 80
  • to 168.63.129.16 over port 8037

If a network security group is associated to the network interface, or subnet that the network interface is in, ensure that rules exist to allow outbound connectivity over the previous ports. Similarly, ensure outbound connectivity over the previous ports when adding user-defined routes to your network.

Install Network Watcher agent

To use packet capture, the Network Watcher agent virtual machine extension must be installed on the virtual machine.

Use Get-AzVMExtension cmdlet to check if the extension is installed on the virtual machine:

# List the installed extensions on the virtual machine.
Get-AzVMExtension -VMName 'myVM' -ResourceGroupName 'myResourceGroup' | format-table Name, Publisher, ExtensionType, EnableAutomaticUpgrade 

If the extension is installed on the virtual machine, then you can see it listed in the output of the preceding command:

Name                         Publisher                      ExtensionType            EnableAutomaticUpgrade
----                         ---------                      -------------            ----------------------
AzureNetworkWatcherExtension Microsoft.Azure.NetworkWatcher NetworkWatcherAgentLinux                   True

If the extension isn't installed, then use Set-AzVMExtension cmdlet to install it:

# Install Network Watcher agent on a Linux virtual machine.
Set-AzVMExtension -Publisher 'Microsoft.Azure.NetworkWatcher' -ExtensionType 'NetworkWatcherAgentLinux' -Name 'AzureNetworkWatcherExtension' -VMName 'myVM' -ResourceGroupName 'myResourceGroup' -TypeHandlerVersion '1.4' -EnableAutomaticUpgrade 1 

# Install Network Watcher agent on a Windows virtual machine.
Set-AzVMExtension -Publisher 'Microsoft.Azure.NetworkWatcher' -ExtensionType 'NetworkWatcherAgentWindows' -Name 'AzureNetworkWatcherExtension' -VMName 'myVM' -ResourceGroupName 'myResourceGroup' -TypeHandlerVersion '1.4' -EnableAutomaticUpgrade 1 

After a successful installation of the extension, you see the following output:

RequestId IsSuccessStatusCode StatusCode ReasonPhrase
--------- ------------------- ---------- ------------
                         True         OK 

Start a packet capture

To start a capture session, use New-AzNetworkWatcherPacketCapture cmdlet:

# Place the virtual machine configuration into a variable.
$vm = Get-AzVM -ResourceGroupName 'myResourceGroup' -Name 'myVM'

# Place the storage account configuration into a variable.
$storageAccount = Get-AzStorageAccount -ResourceGroupName 'myResourceGroup' -Name 'mystorageaccount'

# Start the Network Watcher capture session.
New-AzNetworkWatcherPacketCapture -Location 'chinaeast' -PacketCaptureName 'myVM_1' -TargetVirtualMachineId $vm.Id  -StorageAccountId $storageAccount.Id 

Once the capture session is started, you see the following output:

ProvisioningState Name   BytesToCapturePerPacket TotalBytesPerSession TimeLimitInSeconds
----------------- ----   ----------------------- -------------------- ------------------
Succeeded         myVM_1 0                       1073741824           18000

The following table describes the optional parameters that you can use with the New-AzNetworkWatcherPacketCapture cmdlet:

Parameter	description
-Filter	Add filter(s) to capture only the traffic you want. For example, you can capture only TCP traffic from a specific IP address to a specific port.
-TimeLimitInSeconds	Set the maximum duration of the capture session. The default value is 18000 seconds (5 hours).
-BytesToCapturePerPacket	Set the maximum number of bytes to be captured per each packet. All bytes are captured if not used or 0 entered.
-TotalBytesPerSession	Set the total number of bytes that are captured. Once the value is reached the packet capture stops. Up to 1 GB (1,073,741,824 bytes) is captured if not used.
-LocalFilePath	Enter a valid local file path if you want the capture to be saved in the target virtual machine (For example, C:\Capture\myVM_1.cap). If you're using a Linux machine, the path must start with /var/captures.

Stop a packet capture

Use Stop-AzNetworkWatcherPacketCapture cmdlet to manually stop a running packet capture session.

# Manually stop a packet capture session.
Stop-AzNetworkWatcherPacketCapture -Location 'chinaeast' -PacketCaptureName 'myVM_1'

Get a packet capture

Use Get-AzNetworkWatcherPacketCapture cmdlet to retrieve the status of a packet capture (running or completed).

# Get information, properties, and status of a packet capture.
Get-AzNetworkWatcherPacketCapture -Location 'chinaeast' -PacketCaptureName 'myVM_1'

The following output is an example of the output from the Get-AzNetworkWatcherPacketCapture cmdlet. The following example is after the capture is complete. The PacketCaptureStatus value is Stopped, with a StopReason of TimeExceeded. This value shows that the packet capture was successful and ran its time.

ProvisioningState Name   Target                                                                                                                              BytesToCapturePerPacket TotalBytesPerSession TimeLimitInSeconds
----------------- ----   ------                                                                                                                              ----------------------- -------------------- ------------------
Succeeded         myVM_1 /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/myVM 0                       1073741824           18000

Download a packet capture

After concluding your packet capture session, the resulting capture file is saved to Azure storage, a local file on the target virtual machine or both. The storage destination for the packet capture is specified during its creation. For more information, see Start a packet capture.

If a storage account is specified, capture files are saved to the storage account at the following path:

https://{storageAccountName}.blob.core.chinacloudapi.cn/network-watcher-logs/subscriptions/{subscriptionId}/resourcegroups/{storageAccountResourceGroup}/providers/microsoft.compute/virtualmachines/{virtualMachineName}/{year}/{month}/{day}/packetcapture_{UTCcreationTime}.cap

To download a packet capture file saved to Azure storage, use Get-AzStorageBlobContent cmdlet:

# Download the packet capture file from Azure storage container.
Get-AzStorageBlobContent -Container 'network-watcher-logs' -Blob 'subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/myresourcegroup/providers/microsoft.compute/virtualmachines/myvm/2024/01/25/packetcapture_22_44_54_342.cap' -Destination 'C:\Capture\myVM_1.cap'

Delete a packet capture

# Remove a packet capture resource.
Remove-AzNetworkWatcherPacketCapture -Location 'chinaeast' -PacketCaptureName 'myVM_1'

Related content

• To learn how to automate packet captures with virtual machine alerts, see Create an alert triggered packet capture.
• To learn how to analyze a Network Watcher packet capture file using Wireshark, see Inspect and analyze Network Watcher packet capture files.