Manage NSG flow logs using REST API

  • Article

Important

On September 30, 2027, network security group (NSG) flow logs will be retired. As part of this retirement, you'll no longer be able to create new NSG flow logs starting June 30, 2025. We recommend migrating to virtual network flow logs, which overcome the limitations of NSG flow logs. After the retirement date, traffic analytics enabled with NSG flow logs will no longer be supported, and existing NSG flow logs resources in your subscriptions will be deleted. However, NSG flow logs records won't be deleted and will continue to follow their respective retention policies. For more information, see the official announcement.

Network security group flow logging is a feature of Azure Network Watcher that allows you to log information about IP traffic flowing through a network security group. For more information about network security group flow logging, see NSG flow logs overview.

This article shows you how to use the REST API to enable, disable, and query flow logs using the REST API. You can learn how to manage an NSG flow log using the Azure portal, PowerShell, Azure CLI, or ARM template.

In this article, uou learn how to:

  • Enable flow logs (Version 2)
  • Disable flow logs
  • Query flow logs status

Prerequisites

  • An Azure account with an active subscription. Create a trial subscription.
  • ARMClient. ARMClient is a simple command line tool to invoke the Azure Resource Manager API. To install the tool, see ARMClient. For detailed specifications of NSG flow logs REST API, see Flow Logs - REST API

Important

When you make REST API calls to Network Watcher, the resource group name in the request URI refers to the resource group that contains the Network Watcher, not the resources you are performing the diagnostic actions on.

Sign in with ARMClient

Sign in to armclient with your Azure credentials.

$env:ARMCLIENT_ENV="MOONCAKE"
armclient login

Register Insights provider

Microsoft.Insights provider must be registered to successfully log traffic flowing through a network security group. If you aren't sure if the Microsoft.Insights provider is registered, use Providers - Register REST API to register it.

$subscriptionId = "00000000-0000-0000-0000-000000000000"
armclient post "https://management.chinacloudapi.cn//subscriptions/${subscriptionId}/providers/Microsoft.Insights/register?api-version=2021-04-01"

Enable NSG flow logs

The command to enable flow logs version 2 is shown in the following example. For version 1, replace the 'version' field with '1':

$subscriptionId = "00000000-0000-0000-0000-000000000000"
$targetUri = "" # example /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName/providers/Microsoft.Network/networkSecurityGroups/{nsgName}"
$storageId = "/subscriptions/00000000-0000-0000-0000-000000000000/{resourceGroupName/providers/Microsoft.Storage/storageAccounts/{saName}"
$resourceGroupName = "NetworkWatcherRG"
$networkWatcherName = "NetworkWatcher_chinaeast"
$requestBody = @"
{
    'targetResourceId': '${targetUri}',
    'properties': {
    'storageId': '${storageId}',
    'enabled': 'true',
    'retentionPolicy' : {
			days: 5,
			enabled: true
		},
    'format': {
        'type': 'JSON',
        'version': 2
    }
	}
}
"@

armclient post "https://management.chinacloudapi.cn/subscriptions/${subscriptionId}/ResourceGroups/${resourceGroupName}/providers/Microsoft.Network/networkWatchers/${networkWatcherName}/configureFlowLog?api-version=2022-11-01" $requestBody

The response returned from the preceding example is as follows:

{
  "targetResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/networkSecurityGroups/{nsgName}",
  "properties": {
    "storageId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{saName}",
    "enabled": true,
    "retentionPolicy": {
      "days": 5,
      "enabled": true
    },
    "format": {
    "type": "JSON",
    "version": 2
    }
  }
}

Note

Disable NSG flow logs

Use the following example to disable flow logs. The call is the same as enabling flow logs, except false is set for the enabled property.

$subscriptionId = "00000000-0000-0000-0000-000000000000"
$targetUri = "" # example /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName/providers/Microsoft.Network/networkSecurityGroups/{nsgName}"
$storageId = "/subscriptions/00000000-0000-0000-0000-000000000000/{resourceGroupName/providers/Microsoft.Storage/storageAccounts/{saName}"
$resourceGroupName = "NetworkWatcherRG"
$networkWatcherName = "NetworkWatcher_chinaeast"
$requestBody = @"
{
    'targetResourceId': '${targetUri}',
    'properties': {
    'storageId': '${storageId}',
    'enabled': 'false',
    'retentionPolicy' : {
			days: 5,
			enabled: true
		},
    'format': {
        'type': 'JSON',
        'version': 2
    }
	}
}
"@

armclient post "https://management.chinacloudapi.cn/subscriptions/${subscriptionId}/ResourceGroups/${resourceGroupName}/providers/Microsoft.Network/networkWatchers/${networkWatcherName}/configureFlowLog?api-version=2022-11-01" $requestBody

The response returned from the preceding example is as follows:

{
  "targetResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/networkSecurityGroups/{nsgName}",
  "properties": {
    "storageId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{saName}",
    "enabled": false,
    "retentionPolicy": {
      "days": 5,
      "enabled": true
    },
    "format": {
    "type": "JSON",
    "version": 2
    }
  }
}

Note

Query flow logs

The following REST call queries the status of flow logs on a network security group.

$subscriptionId = "00000000-0000-0000-0000-000000000000"
$targetUri = "" # example /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName/providers/Microsoft.Network/networkSecurityGroups/{nsgName}"
$resourceGroupName = "NetworkWatcherRG"
$networkWatcherName = "NetworkWatcher_chinaeast"
$requestBody = @"
{
    'targetResourceId': '${targetUri}',
}
"@

armclient post "https://management.chinacloudapi.cn/subscriptions/${subscriptionId}/ResourceGroups/${resourceGroupName}/providers/Microsoft.Network/networkWatchers/${networkWatcherName}/queryFlowLogStatus?api-version=2022-11-01" $requestBody

The following example shows the response returned:

{
  "targetResourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/networkSecurityGroups/{nsgName}",
  "properties": {
    "storageId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{saName}",
    "enabled": true,
   "retentionPolicy": {
      "days": 5,
      "enabled": true
    },
    "format": {
    "type": "JSON",
    "version": 2
    }
  }
}

Note

  • The Network Watchers - Get Flow Log Status REST API used in the previous example, requires an additional reader permission in the resource group of the network watcher. Additionally, this API is old and may soon be deprecated.
  • It is recommended to use the new Flow Logs - Get REST API to query flow logs.

Download a flow log

The storage location of a flow log is defined at creation. A convenient tool to access flow logs saved to a storage account is Azure Storage Explorer. Fore more information, see Get started with Storage Explorer.

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

https://{storageAccountName}.blob.core.chinacloudapi.cn/insights-logs-networksecuritygroupflowevent/resourceId=/SUBSCRIPTIONS/{subscriptionID}/RESOURCEGROUPS/{resourceGroupName}/PROVIDERS/MICROSOFT.NETWORK/NETWORKSECURITYGROUPS/{nsgName}/y={year}/m={month}/d={day}/h={hour}/m=00/macAddress={macAddress}/PT1H.json

Next steps