Packet Captures - Create
Create and start a packet capture on the specified VM.
PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/networkWatchers/{networkWatcherName}/packetCaptures/{packetCaptureName}?api-version=2023-09-01
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
network
|
path | True |
string |
The name of the network watcher. |
packet
|
path | True |
string |
The name of the packet capture session. |
resource
|
path | True |
string |
The name of the resource group. |
subscription
|
path | True |
string |
The subscription credentials which uniquely identify the Microsoft Azure subscription. The subscription ID forms part of the URI for every service call. |
api-version
|
query | True |
string |
Client API version. |
Request Body
Name | Required | Type | Description |
---|---|---|---|
properties.storageLocation | True |
The storage location for a packet capture session. |
|
properties.target | True |
string |
The ID of the targeted resource, only AzureVM and AzureVMSS as target type are currently supported. |
properties.bytesToCapturePerPacket |
integer |
Number of bytes captured per packet, the remaining bytes are truncated. |
|
properties.filters |
A list of packet capture filters. |
||
properties.scope |
A list of AzureVMSS instances which can be included or excluded to run packet capture. If both included and excluded are empty, then the packet capture will run on all instances of AzureVMSS. |
||
properties.targetType |
Target type of the resource provided. |
||
properties.timeLimitInSeconds |
integer |
Maximum duration of the capture session in seconds. |
|
properties.totalBytesPerSession |
integer |
Maximum size of the capture output. |
Responses
Name | Type | Description |
---|---|---|
201 Created |
Request successful. The operation returns the resulting packet capture session. |
|
Other Status Codes |
Error response describing why the operation failed. |
Security
azure_auth
Azure Active Directory OAuth2 Flow.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Name | Description |
---|---|
user_impersonation | impersonate your user account |
Examples
Create packet capture
Sample Request
PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/networkWatchers/nw1/packetCaptures/pc1?api-version=2023-09-01
{
"properties": {
"target": "/subscriptions/subid/resourceGroups/rg2/providers/Microsoft.Compute/virtualMachines/vm1",
"bytesToCapturePerPacket": 10000,
"totalBytesPerSession": 100000,
"timeLimitInSeconds": 100,
"storageLocation": {
"storageId": "/subscriptions/subid/resourceGroups/rg2/providers/Microsoft.Storage/storageAccounts/pcstore",
"storagePath": "https://mytestaccountname.blob.core.windows.net/capture/pc1.cap",
"filePath": "D:\\capture\\pc1.cap"
},
"filters": [
{
"protocol": "TCP",
"localIPAddress": "10.0.0.4",
"localPort": "80"
}
]
}
}
Sample Response
{
"name": "pc1",
"id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Network/networkWatchers/nw1/packetCaptures/pc1",
"properties": {
"provisioningState": "Updating",
"target": "/subscriptions/subid/resourceGroups/rg2/providers/Microsoft.Compute/virtualMachines/vm1",
"bytesToCapturePerPacket": 10000,
"totalBytesPerSession": 100000,
"timeLimitInSeconds": 100,
"storageLocation": {
"storageId": "/subscriptions/subid/resourceGroups/rg2/providers/Microsoft.Storage/storageAccounts/pcstore",
"storagePath": "https://mytestaccountname.blob.core.windows.net/capture/pc1.cap",
"filePath": "D:\\capture\\pc1.cap"
},
"filters": [
{
"protocol": "TCP",
"localIPAddress": "10.0.0.4",
"localPort": "80"
}
]
}
}
Definitions
Name | Description |
---|---|
Error |
Common error details representation. |
Error |
The error object. |
Packet |
Parameters that define the create packet capture operation. |
Packet |
Filter that is applied to packet capture request. Multiple filters can be applied. |
Packet |
A list of AzureVMSS instances which can be included or excluded to run packet capture. If both included and excluded are empty, then the packet capture will run on all instances of AzureVMSS. |
Packet |
Information about packet capture session. |
Packet |
The storage location for a packet capture session. |
Packet |
Target type of the resource provided. |
Pc |
Protocol to be filtered on. |
Provisioning |
The current provisioning state. |
ErrorDetails
Common error details representation.
Name | Type | Description |
---|---|---|
code |
string |
Error code. |
message |
string |
Error message. |
target |
string |
Error target. |
ErrorResponse
The error object.
Name | Type | Description |
---|---|---|
error |
Error |
PacketCapture
Parameters that define the create packet capture operation.
Name | Type | Default Value | Description |
---|---|---|---|
properties.bytesToCapturePerPacket |
integer |
0 |
Number of bytes captured per packet, the remaining bytes are truncated. |
properties.filters |
A list of packet capture filters. |
||
properties.scope |
A list of AzureVMSS instances which can be included or excluded to run packet capture. If both included and excluded are empty, then the packet capture will run on all instances of AzureVMSS. |
||
properties.storageLocation |
The storage location for a packet capture session. |
||
properties.target |
string |
The ID of the targeted resource, only AzureVM and AzureVMSS as target type are currently supported. |
|
properties.targetType |
Target type of the resource provided. |
||
properties.timeLimitInSeconds |
integer |
18000 |
Maximum duration of the capture session in seconds. |
properties.totalBytesPerSession |
integer |
1073741824 |
Maximum size of the capture output. |
PacketCaptureFilter
Filter that is applied to packet capture request. Multiple filters can be applied.
Name | Type | Default Value | Description |
---|---|---|---|
localIPAddress |
string |
Local IP Address to be filtered on. Notation: "127.0.0.1" for single address entry. "127.0.0.1-127.0.0.255" for range. "127.0.0.1;127.0.0.5"? for multiple entries. Multiple ranges not currently supported. Mixing ranges with multiple entries not currently supported. Default = null. |
|
localPort |
string |
Local port to be filtered on. Notation: "80" for single port entry."80-85" for range. "80;443;" for multiple entries. Multiple ranges not currently supported. Mixing ranges with multiple entries not currently supported. Default = null. |
|
protocol | Any |
Protocol to be filtered on. |
|
remoteIPAddress |
string |
Local IP Address to be filtered on. Notation: "127.0.0.1" for single address entry. "127.0.0.1-127.0.0.255" for range. "127.0.0.1;127.0.0.5;" for multiple entries. Multiple ranges not currently supported. Mixing ranges with multiple entries not currently supported. Default = null. |
|
remotePort |
string |
Remote port to be filtered on. Notation: "80" for single port entry."80-85" for range. "80;443;" for multiple entries. Multiple ranges not currently supported. Mixing ranges with multiple entries not currently supported. Default = null. |
PacketCaptureMachineScope
A list of AzureVMSS instances which can be included or excluded to run packet capture. If both included and excluded are empty, then the packet capture will run on all instances of AzureVMSS.
Name | Type | Description |
---|---|---|
exclude |
string[] |
List of AzureVMSS instances which has to be excluded from the AzureVMSS from running packet capture. |
include |
string[] |
List of AzureVMSS instances to run packet capture on. |
PacketCaptureResult
Information about packet capture session.
Name | Type | Default Value | Description |
---|---|---|---|
etag |
string |
A unique read-only string that changes whenever the resource is updated. |
|
id |
string |
ID of the packet capture operation. |
|
name |
string |
Name of the packet capture session. |
|
properties.bytesToCapturePerPacket |
integer |
0 |
Number of bytes captured per packet, the remaining bytes are truncated. |
properties.filters |
A list of packet capture filters. |
||
properties.provisioningState |
The provisioning state of the packet capture session. |
||
properties.scope |
A list of AzureVMSS instances which can be included or excluded to run packet capture. If both included and excluded are empty, then the packet capture will run on all instances of AzureVMSS. |
||
properties.storageLocation |
The storage location for a packet capture session. |
||
properties.target |
string |
The ID of the targeted resource, only AzureVM and AzureVMSS as target type are currently supported. |
|
properties.targetType |
Target type of the resource provided. |
||
properties.timeLimitInSeconds |
integer |
18000 |
Maximum duration of the capture session in seconds. |
properties.totalBytesPerSession |
integer |
1073741824 |
Maximum size of the capture output. |
PacketCaptureStorageLocation
The storage location for a packet capture session.
Name | Type | Description |
---|---|---|
filePath |
string |
A valid local path on the targeting VM. Must include the name of the capture file (*.cap). For linux virtual machine it must start with /var/captures. Required if no storage ID is provided, otherwise optional. |
storageId |
string |
The ID of the storage account to save the packet capture session. Required if no local file path is provided. |
storagePath |
string |
The URI of the storage path to save the packet capture. Must be a well-formed URI describing the location to save the packet capture. |
PacketCaptureTargetType
Target type of the resource provided.
Name | Type | Description |
---|---|---|
AzureVM |
string |
|
AzureVMSS |
string |
PcProtocol
Protocol to be filtered on.
Name | Type | Description |
---|---|---|
Any |
string |
|
TCP |
string |
|
UDP |
string |
ProvisioningState
The current provisioning state.
Name | Type | Description |
---|---|---|
Deleting |
string |
|
Failed |
string |
|
Succeeded |
string |
|
Updating |
string |