| title | description | services | documentationcenter | author | manager | editor | ms.assetid | ms.service | ms.devlang | ms.topic | ms.tgt_pltfrm | ms.workload | ms.date | ms.author |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Manage packet captures with Azure Network Watcher - Azure CLI 2.0 | Microsoft Docs |
This page explains how to manage the packet capture feature of Network Watcher using Azure CLI 2.0 |
network-watcher |
na |
jimdial |
timlt |
cb0c1d10-f7f2-4c34-b08c-f73452430be8 |
network-watcher |
na |
article |
na |
infrastructure-services |
02/22/2017 |
jdial |
[!div class="op_single_selector"]
Network Watcher packet capture allows you to create capture sessions to track traffic to and from a virtual machine. Filters are provided for the capture session to ensure you capture only the traffic you want. Packet capture helps to diagnose network anomalies both reactively and proactively. Other uses include gathering network statistics, gaining information on network intrusions, to debug client-server communications and much more. By being able to remotely trigger packet captures, this capability eases the burden of running a packet capture manually and on the desired machine, which saves valuable time.
This article uses our next generation CLI for the resource management deployment model, Azure CLI 2.0, which is available for Windows, Mac and Linux.
To perform the steps in this article, you need to install the Azure Command-Line Interface for Mac, Linux, and Windows (Azure CLI).
This article takes you through the different management tasks that are currently available for packet capture.
This article assumes you have the following resources:
- An instance of Network Watcher in the region you want to create a packet capture
- A virtual machine with the packet capture extension enabled.
Important
Packet capture requires an agent to be running on the virtual machine. The Agent is installed as an extension. For instructions on VM extensions, visit Virtual Machine extensions and features.
Run the az vm extension set cmdlet to install the packet capture agent on the guest virtual machine.
For Windows virtual machines:
az vm extension set --resource-group resourceGroupName --vm-name virtualMachineName --publisher Microsoft.Azure.NetworkWatcher --name NetworkWatcherAgentWindows --version 1.4
For Linux virtual machines:
az vm extension set --resource-group resourceGroupName --vm-name virtualMachineName --publisher Microsoft.Azure.NetworkWatcher --name NetworkWatcherAgentLinux--version 1.4
To ensure that the agent is installed, run the vm extension show cmdlet and pass it the resource group and virtual machine name. Check the resulting list to ensure the agent is installed.
az vm extension show --resource-group resourceGroupName --vm-name virtualMachineName --name NetworkWatcherAgentWindows
The following sample is an example of the response from running az vm extension show
{
"autoUpgradeMinorVersion": true,
"forceUpdateTag": null,
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/extensions/NetworkWatcherAgentWindows",
"instanceView": null,
"location": "westcentralus",
"name": "NetworkWatcherAgentWindows",
"protectedSettings": null,
"provisioningState": "Succeeded",
"publisher": "Microsoft.Azure.NetworkWatcher",
"resourceGroup": "{resourceGroupName}",
"settings": null,
"tags": null,
"type": "Microsoft.Compute/virtualMachines/extensions",
"typeHandlerVersion": "1.4",
"virtualMachineExtensionType": "NetworkWatcherAgentWindows"
}Once the preceding steps are complete, the packet capture agent is installed on the virtual machine.
The next step is to retrieve the Network Watcher instance. TThe name of the Network Watcher is passed to the az network watcher show cmdlet in step 4.
az network watcher show --resource-group resourceGroup --name networkWatcherName
Retrieve a storage account. This storage account is used to store the packet capture file.
azure storage account list
Filters can be used to limit the data that is stored by the packet capture. The following example sets up a packet capture with several filters. The first three filters collect outgoing TCP traffic only from local IP 10.0.0.3 to destination ports 20, 80 and 443. The last filter collects only UDP traffic.
az network watcher packet-capture create --resource-group {resoureceurceGroupName} --vm {vmName} --name packetCaptureName --storage-account gwteststorage123abc --filters "[{\"protocol\":\"TCP\", \"remoteIPAddress\":\"1.1.1.1-255.255.255\",\"localIPAddress\":\"10.0.0.3\", \"remotePort\":\"20\"},{\"protocol\":\"TCP\", \"remoteIPAddress\":\"1.1.1.1-255.255.255\",\"localIPAddress\":\"10.0.0.3\", \"remotePort\":\"80\"},{\"protocol\":\"TCP\", \"remoteIPAddress\":\"1.1.1.1-255.255.255\",\"localIPAddress\":\"10.0.0.3\", \"remotePort\":\"443\"},{\"protocol\":\"UDP\"}]"
The following example is the expected output from running the az network watcher packet-capture create cmdlet.
{
"bytesToCapturePerPacket": 0,
"etag": "W/\"b8cf3528-2e14-45cb-a7f3-5712ffb687ac\"",
"filters": [
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "20"
},
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "80"
},
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "443"
},
{
"localIpAddress": "",
"localPort": "",
"protocol": "UDP",
"remoteIpAddress": "",
"remotePort": ""
}
],
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/NetworkWatcherRG/providers/Microsoft.Network/networkWatchers/NetworkWatcher_westcentralus/pa
cketCaptures/packetCaptureName",
"name": "packetCaptureName",
"provisioningState": "Succeeded",
"resourceGroup": "NetworkWatcherRG",
"storageLocation": {
"filePath": null,
"storageId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/gwteststorage123abc",
"storagePath": "https://gwteststorage123abc.blob.core.windows.net/network-watcher-logs/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/{resourceGroupName}/p
roviders/microsoft.compute/virtualmachines/{vmName}/2017/05/25/packetcapture_16_22_34_630.cap"
},
"target": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}",
"timeLimitInSeconds": 18000,
"totalBytesPerSession": 1073741824
}Running the az network watcher packet-capture show cmdlet, retrieves the status of a currently running, or completed packet capture.
az network watcher packet-capture show --name packetCaptureName --location westcentralus
The following example is the output from the az network watcher packet-capture show 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.
{
"bytesToCapturePerPacket": 0,
"etag": "W/\"b8cf3528-2e14-45cb-a7f3-5712ffb687ac\"",
"filters": [
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "20"
},
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "80"
},
{
"localIpAddress": "10.0.0.3",
"localPort": "",
"protocol": "TCP",
"remoteIpAddress": "1.1.1.1-255.255.255",
"remotePort": "443"
},
{
"localIpAddress": "",
"localPort": "",
"protocol": "UDP",
"remoteIpAddress": "",
"remotePort": ""
}
],
"id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/NetworkWatcherRG/providers/Microsoft.Network/networkWatchers/NetworkWatcher_westcentralus/packetCaptures/packetCaptureName",
"name": "packetCaptureName",
"provisioningState": "Succeeded",
"resourceGroup": "NetworkWatcherRG",
"storageLocation": {
"filePath": null,
"storageId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/gwteststorage123abc",
"storagePath": "https://gwteststorage123abc.blob.core.windows.net/network-watcher-logs/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/{resourceGroupName}/providers/microsoft.compute/virtualmachines/{vmName}/2017/05/25/packetcapt
ure_16_22_34_630.cap"
},
"target": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}",
"timeLimitInSeconds": 18000,
"totalBytesPerSession": 1073741824
}
By running the az network watcher packet-capture stop cmdlet, if a capture session is in progress it is stopped.
az network watcher packet-capture stop --name packetCaptureName --location westcentralus
Note
The cmdlet returns no response when ran on a currently running capture session or an existing session that has already stopped.
az network watcher packet-capture delete --name packetCaptureName --location westcentralus
Note
Deleting a packet capture does not delete the file in the storage account.
Once your packet capture session has completed, the capture file can be uploaded to blob storage or to a local file on the VM. The storage location of the packet capture is defined at creation of the session. A convenient tool to access these capture files saved to a storage account is Microsoft Azure Storage Explorer, which can be downloaded here: http://storageexplorer.com/
If a storage account is specified, packet capture files are saved to a storage account at the following location:
https://{storageAccountName}.blob.core.windows.net/network-watcher-logs/subscriptions/{subscriptionId}/resourcegroups/{storageAccountResourceGroup}/providers/microsoft.compute/virtualmachines/{VMName}/{year}/{month}/{day}/packetCapture_{creationTime}.cap
Learn how to automate packet captures with Virtual machine alerts by viewing Create an alert triggered packet capture
Find if certain traffic is allowed in or out of your VM by visiting Check IP flow verify