Diagnose Azure Virtual Network VPN connectivity issues with PowerShell

Azure Virtual Network Gateways provide a great solution for quickly building secure cross-premises network connectivity for a Hybrid Cloud via IPsec site-to-site VPN tunnels. However, VPN tunnels can sometimes be a bit tricky to configure with certain on-premises VPN gateways.  When the VPN tunnel isn't able to connect between Azure and your on-premises gateway device due to configuration or networking issues, you'll see a broken connection displayed in the Azure Management Portal for that Virtual Network Gateway.

Click to zoom in ...
Azure Virtual Network - Disconnected

Until recently, the only options for diagnosing VPN connection problems were to either troubleshoot via logs from the on-premises VPN gateway, or open an Azure support ticket for assistance with troubleshooting from the Azure side of this VPN tunnel. With the latest Azure PowerShell module, we now have the ability to directly troubleshoot VPN connections from Azure with three new PowerShell cmdlets:

  • Start-AzureVNetGatewayDiagnostics,
  • Stop-AzureVnetGatewayDiagnostics, and
  • Get-AzureVNetGatewayDiagnostics

In this article, we'll step through leveraging these new Azure PowerShell cmdlets to diagnose a site-to-site VPN gateway connection issue.

Getting Started

Before stepping through this article, you'll need to first setup a few items:

  1. An active Microsoft Azure subscription. If you don't current have an active Azure subscription, activate one using our Free Trial program.
  2. Azure PowerShell Module. Be sure to download and install the latest version of the Azure PowerShell Module.
  3. Azure Virtual Network and Gateway. If you don't currently have an Azure Virtual Network setup with a Gateway, follow this step-by-step article or this guided lab to complete this process.
  4. Azure Storage Account. Azure Virtual Network Gateway diagnostics logs are stored in an Azure Storage Account.  You can create a new Storage Account by following this step-by-step article.

and Select Azure Subscription

To work with any Azure resources via PowerShell, you'll first need to authenticate and select the Azure subscription in which your virtual network is provisioned.

# Authenticate to Azure with Azure AD credentials


# Select Azure Subscription

$subscriptionName = (Get-AzureSubscription).SubscriptionName | Out-GridView -Title "Select Azure Subscription" -PassThru

Select-AzureSubscription -SubscriptionName $subscriptionName

Select Azure Storage Account

Next, select the Azure Storage Account that you've created for storing the diagnostic logs that your Virtual Network Gateway will be generating.

# Select Azure storage account for storing diagnostics logs

$storageAccountName = (Get-AzureStorageAccount).StorageAccountName | Out-GridView -Title "Select Azure Storage Account" -PassThru

$storageAccountKey = (Get-AzureStorageKey -StorageAccountName $storageAccountName).Primary

$storageContext = New-AzureStorageContext -StorageAccountName $storageAccountName -StorageAccountKey $storageAccountKey

Select Azure Virtual Network

You'll also need to select the Azure Virtual Network on which the Gateway that you'll be diagnosing is provisioned.

# Select Azure VNet for which to capture diagnostics logs
$azureVNet = (Get-AzureVNetSite).Name | Out-GridView -Title "Select Azure VNet" -PassThru

Start Capturing Diagnostics Logs

When you're ready to capture diagnostic logs from your Virtual Network Gateway, you can use the Start-AzureVNetGatewayDiagnostics cmdlet to begin the capture process. When using this cmdlet, you must specify a capture duration in seconds, which can be up to 300 seconds (5 minutes).

# Start capturing diagnostic logs - up to 300 seconds

$captureDuration = 60

Start-AzureVNetGatewayDiagnostics -VNetName $azureVNet -StorageContext $storageContext -CaptureDurationInSeconds $captureDuration

After capturing has been started, you may wish to try clicking the "Connect" button in the Azure Management Portal to force the Gateway to attempt to connect and establish the tunnel. 


If the tunnel is connected, but not routing traffic, you may alternatively wish to try sending traffic across the tunnel from each side with the Test-NetConnection cmdlet.

# Test network connection
Test-NetConnection -ComputerName -CommonTCPPort RDP

These last two steps may help to force the Gateway to communicate during the capturing duration and generate additional log messages that could be helpful diagnosing the issue.

Now, let's wait for the remainder of the capture duration.

# Wait for diagnostics capturing to complete

Sleep -Seconds $captureDuration

After the capture duration has concluded, diagnostics logged will automatically stop and the log stored within Azure storage will be closed.

Save and Review Diagnostics Log

To determine the URL for the saved log, use the Get-AzureVNetGatewayDiagnostics cmdlet.  After you've stored the URL in a variable, you can use the Invoke-WebRequest cmdlet to save the log locally on your PC for review.

# Save diagnostics log locally

$logUrl = (Get-AzureVNetGatewayDiagnostics -VNetName $azureVNet).DiagnosticsUrl

$logContent = (Invoke-WebRequest -Uri $logUrl).RawContent

$logContent | Out-File -FilePath vpnlog.txt

After saving the log file locally, open it in Notepad to review the captured log messages and diagnose your connection issue.

Downloadable Script

To make it easy to use these new diagnostics cmdlets for troubleshooting Virtual Network Gateway connectivity, Adam Conkle, a Senior Support Escalation Engineer on our Azure Support team, has recently released a script on the TechNet Script Center repository that helps to automate these steps. Be sure to grab a copy for your own use!