Create a VNet with a Site-to-Site VPN connection using PowerShell

This article shows you how to use PowerShell to create a Site-to-Site VPN gateway connection from your on-premises network to the VNet. The steps in this article apply to the Resource Manager deployment model. You can also create this configuration using a different deployment tool or deployment model by selecting a different option from the following list:

A Site-to-Site VPN gateway connection is used to connect your on-premises network to an Azure virtual network over an IPsec/IKE (IKEv1 or IKEv2) VPN tunnel. This type of connection requires a VPN device located on-premises that has an externally facing public IP address assigned to it. For more information about VPN gateways, see About VPN gateway.

Site-to-Site VPN Gateway cross-premises connection diagram

Before you begin

Verify that you have met the following criteria before beginning your configuration:

  • Make sure you have a compatible VPN device and someone who is able to configure it. For more information about compatible VPN devices and device configuration, see About VPN Devices.
  • Verify that you have an externally facing public IPv4 address for your VPN device. This IP address cannot be located behind a NAT.
  • If you are unfamiliar with the IP address ranges located in your on-premises network configuration, you need to coordinate with someone who can provide those details for you. When you create this configuration, you must specify the IP address range prefixes that Azure will route to your on-premises location. None of the subnets of your on-premises network can over lap with the virtual network subnets that you want to connect to.
  • Install the latest version of the Azure Resource Manager PowerShell cmdlets. PowerShell cmdlets are updated frequently and you will typically need to update your PowerShell cmdlets to get the latest feature functionality. If you don't update your PowerShell cmdlets, the values specified may fail. See How to install and configure Azure PowerShell for more information about downloading and installing PowerShell cmdlets.

Example values

The examples in this article use the following values. You can use these values to create a test environment, or refer to them to better understand the examples in this article.

#Example values

VnetName                = TestVNet1
ResourceGroup           = TestRG1
Location                = East US 
AddressSpace            = 10.11.0.0/16 
SubnetName              = Subnet1 
Subnet                  = 10.11.1.0/28 
GatewaySubnet           = 10.11.0.0/27
LocalNetworkGatewayName = Site2
LNG Public IP           = <VPN device IP address> 
Local Address Prefixes  = 10.0.0.0/24, 20.0.0.0/24
Gateway Name            = VNet1GW
PublicIP                = VNet1GWIP
Gateway IP Config       = gwipconfig1 
VPNType                 = RouteBased 
GatewayType             = Vpn 
ConnectionName          = VNet1toSite2

1. Connect to your subscription

Before beginning this configuration, you must log in to your Azure account. The cmdlet prompts you for the login credentials for your Azure account. After logging in, it downloads your account settings so they are available to Azure PowerShell. For more information, see Using Windows PowerShell with Resource Manager.

To log in, open your PowerShell console with elevated privileges, and connect to your account. Use the following example to help you connect:

Login-AzureRmAccount

If you have multiple Azure subscriptions, check the subscriptions for the account.

Get-AzureRmSubscription

Specify the subscription that you want to use.

Select-AzureRmSubscription -SubscriptionName "Replace_with_your_subscription_name"

2. Create a virtual network and a gateway subnet

If you don't already have a virtual network, create one. When creating a virtual network, make sure that the address spaces you specify don't overlap any of the address spaces that you have on your on-premises network.

Note

In order for this VNet to connect to an on-premises location, you need to coordinate with your on-premises network administrator to carve out an IP address range that you can use specifically for this virtual network. If a duplicate address range exists on both sides of the VPN connection, traffic does not route the way you may expect it to. Additionally, if you want to connect this VNet to another VNet, the address space cannot overlap with other VNet. Take care to plan your network configuration accordingly.

About the gateway subnet

The virtual network gateway uses specific subnet called the 'gateway subnet'. You must always create a gateway subnet if you want to create a VPN gateway connection. The IP addresses that are specified in the gateway subnet are part of the virtual network IP address range that you specify when configuring your virtual network. Some of the resources and services that are used by the VPN gateway require IP addresses. Gateway subnet IP addresses are allocated to these gateway services. For this reason, never deploy anything directly to the gateway subnet, such as VMs or any other resources.

When you create a gateway subnet, you specify the number of IP addresses that the gateway subnet contains. The size of the gateway subnet that you specify depends on the VPN gateway configuration that you want to create. Some configurations require more IP addresses than others. The instructions in the article specify when a certain sized gateway subnet is required. While it is technically possible to create a gateway subnet as small as /29, we recommend that in general, you create a larger subnet that includes more addresses by selecting /27 or /28. Using a larger gateway subnet allows for enough IP addresses to be allocated to the gateway services to accommodate possible future configurations.

When you create a gateway subnet, it must be named 'GatewaySubnet'. Naming subnet 'GatewaySubnet' tells Azure where to create the gateway services. If you name the subnet something else, your VPN gateway configuration will fail.

Important

When working with gateway subnets, avoid associating a network security group (NSG) to the gateway subnet. Associating a network security group to this subnet may cause your VPN gateway to stop functioning as expected. For more information about network security groups, see What is a network security group?

To create a virtual network and a gateway subnet

This example creates a virtual network and a gateway subnet. If you already have a virtual network that you need to add a gateway subnet to, see To add a gateway subnet to a virtual network you have already created.

Create a resource group:

New-AzureRmResourceGroup -Name TestRG1 -Location 'East US'

Create your virtual network.

  1. Set the variables.

    $subnet1 = New-AzureRmVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -AddressPrefix 10.11.0.0/27
    $subnet2 = New-AzureRmVirtualNetworkSubnetConfig -Name 'Subnet1' -AddressPrefix 10.11.1.0/28
    
  2. Create the VNet.

    New-AzureRmVirtualNetwork -Name TestVNet1 -ResourceGroupName TestRG1 `
    -Location 'East US' -AddressPrefix 10.11.0.0/16 -Subnet $subnet1, $subnet2
    

To add a gateway subnet to a virtual network you have already created

  1. Set the variables.

    $vnet = Get-AzureRmVirtualNetwork -ResourceGroupName TestRG1 -Name TestVet1
    
  2. Create the gateway subnet.

    Add-AzureRmVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -AddressPrefix 10.11.0.0/27 -VirtualNetwork $vnet
    
  3. Set the configuration.

    Set-AzureRmVirtualNetwork -VirtualNetwork $vnet
    

3. Create the local network gateway

The local network gateway typically refers to your on-premises location. You give the site a name by which Azure can refer to it, then specify the IP address of the on-premises VPN device to which you will create a connection. You also specify the IP address prefixes that will be routed through the VPN gateway to the VPN device. The address prefixes you specify are the prefixes located on your on-premises network. If your on-premises network changes, you can easily update the prefixes.

Use the following values:

  • The GatewayIPAddress is the IP address of your on-premises VPN device. Your VPN device cannot be located behind a NAT.
  • The AddressPrefix is your on-premises address space.

To add a local network gateway with a single address prefix:

New-AzureRmLocalNetworkGateway -Name Site2 -ResourceGroupName TestRG1 `
-Location 'East US' -GatewayIpAddress '23.99.221.164' -AddressPrefix '10.0.0.0/24'

To add a local network gateway with multiple address prefixes:

New-AzureRmLocalNetworkGateway -Name Site2 -ResourceGroupName TestRG1 `
-Location 'East US' -GatewayIpAddress '23.99.221.164' -AddressPrefix @('10.0.0.0/24','20.0.0.0/24')

To modify IP address prefixes for your local network gateway:
Sometimes your local network gateway prefixes change. The steps you take to modify your IP address prefixes depend on whether you have created a VPN gateway connection. See the Modify IP address prefixes for a local network gateway section of this article.

4. Request a Public IP address

A VPN gateway must have a Public IP address. You first request the IP address resource, and then refer to it when creating your virtual network gateway. The IP address is dynamically assigned to the resource when the VPN gateway is created. VPN Gateway currently only supports Dynamic Public IP address allocation. You cannot request a Static Public IP address assignment. However, this does not mean that the IP address changes after it has been assigned to your VPN gateway. The only time the Public IP address changes is when the gateway is deleted and re-created. It doesn't change across resizing, resetting, or other internal maintenance/upgrades of your VPN gateway.

Request a Public IP address that will be assigned to your virtual network VPN gateway.

$gwpip= New-AzureRmPublicIpAddress -Name gwpip -ResourceGroupName TestRG1 -Location 'East US' -AllocationMethod Dynamic

5. Create the gateway IP addressing configuration

The gateway configuration defines the subnet and the public IP address to use. Use the following example to create your gateway configuration:

$vnet = Get-AzureRmVirtualNetwork -Name TestVNet1 -ResourceGroupName TestRG1
$subnet = Get-AzureRmVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -VirtualNetwork $vnet
$gwipconfig = New-AzureRmVirtualNetworkGatewayIpConfig -Name gwipconfig1 -SubnetId $subnet.Id -PublicIpAddressId $gwpip.Id

6. Create the VPN gateway

Create the virtual network VPN gateway. Creating a VPN gateway can take up to 45 minutes or more to complete.

Use the following values:

  • The -GatewayType for a Site-to-Site configuration is Vpn. The gateway type is always specific to the configuration that you are implementing. For example, other gateway configurations may require -GatewayType ExpressRoute.
  • The -VpnType can be RouteBased (referred to as a Dynamic Gateway in some documentation), or PolicyBased (referred to as a Static Gateway in some documentation). For more information about VPN gateway types, see About VPN Gateway.
  • Select the Gateway SKU that you want to use. There are configuration limitations for certain SKUs. For more information, see Gateway SKUs. If you get an error when creating the VPN gateway regarding the -GatewaySku, verify that you have installed the latest version of the PowerShell cmdlets.
New-AzureRmVirtualNetworkGateway -Name VNet1GW -ResourceGroupName TestRG1 `
-Location 'East US' -IpConfigurations $gwipconfig -GatewayType Vpn `
-VpnType RouteBased -GatewaySku VpnGw1

7. Configure your VPN device

Site-to-Site connections to an on-premises network require a VPN device. In this step, you configure your VPN device. When configuring your VPN device, you need the following:

  • A shared key. This is the same shared key that you specify when creating your Site-to-Site VPN connection. In our examples, we use a basic shared key. We recommend that you generate a more complex key to use.
  • The Public IP address of your virtual network gateway. You can view the public IP address by using the Azure portal, PowerShell, or CLI. To find the Public IP address of your virtual network gateway using PowerShell, use the following example:

    Get-AzureRmPublicIpAddress -Name GW1PublicIP -ResourceGroupName TestRG1
    

See the following links for configuration information:

8. Create the VPN connection

Next, create the Site-to-Site VPN connection between your virtual network gateway and your VPN device. Be sure to replace the values with your own. The shared key must match the value you used for your VPN device configuration. Notice that the '-ConnectionType' for Site-to-Site is IPsec.

  1. Set the variables.

    $gateway1 = Get-AzureRmVirtualNetworkGateway -Name VNet1GW -ResourceGroupName TestRG1
    $local = Get-AzureRmLocalNetworkGateway -Name Site2 -ResourceGroupName TestRG1
    
  2. Create the connection.

    New-AzureRmVirtualNetworkGatewayConnection -Name VNet1toSite2 -ResourceGroupName TestRG1 `
    -Location 'East US' -VirtualNetworkGateway1 $gateway1 -LocalNetworkGateway2 $local `
    -ConnectionType IPsec -RoutingWeight 10 -SharedKey 'abc123'
    

After a short while, the connection will be established.

9. Verify the VPN connection

There are a few different ways to verify your VPN connection.

You can verify that your connection succeeded by using the 'Get-AzureRmVirtualNetworkGatewayConnection' cmdlet, with or without '-Debug'.

  1. Use the following cmdlet example, configuring the values to match your own. If prompted, select 'A' in order to run 'All'. In the example, '-Name' refers to the name of the connection that you want to test.

    Get-AzureRmVirtualNetworkGatewayConnection -Name MyGWConnection -ResourceGroupName MyRG
    
  2. After the cmdlet has finished, view the values. In the example below, the connection status shows as 'Connected' and you can see ingress and egress bytes.

    "connectionStatus": "Connected",
    "ingressBytesTransferred": 33509044,
    "egressBytesTransferred": 4142431
    

To connect to a virtual machine

You can connect to a VM that is deployed to your VNet by creating a Remote Desktop Connection to your VM. The best way to initially verify that you can connect to your VM is to connect by using its private IP address, rather than computer name. That way, you are testing to see if you can connect, not whether name resolution is configured properly.

  1. Locate the private IP address. You can find the private IP address of a VM in multiple ways. Below, we show the steps for the Azure portal and for PowerShell.

    • Azure portal - Locate your virtual machine in the Azure portal. View the properties for the VM. The private IP address is listed.

    • PowerShell - Use the example to view a list of VMs and private IP addresses from your resource groups. You don't need to modify this example before using it.

      $VMs = Get-AzureRmVM
      $Nics = Get-AzureRmNetworkInterface | Where VirtualMachine -ne $null
      
      foreach($Nic in $Nics)
      {
       $VM = $VMs | Where-Object -Property Id -eq $Nic.VirtualMachine.Id
       $Prv = $Nic.IpConfigurations | Select-Object -ExpandProperty PrivateIpAddress
       $Alloc = $Nic.IpConfigurations | Select-Object -ExpandProperty PrivateIpAllocationMethod
       Write-Output "$($VM.Name): $Prv,$Alloc"
      }
      
  2. Verify that you are connected to your VNet using the VPN connection.

  3. Open Remote Desktop Connection by typing "RDP" or "Remote Desktop Connection" in the search box on the taskbar, then select Remote Desktop Connection. You can also open Remote Desktop Connection using the 'mstsc' command in PowerShell.
  4. In Remote Desktop Connection, enter the private IP address of the VM. You can click "Show Options" to adjust additional settings, then connect.

To troubleshoot an RDP connection to a VM

If you are having trouble connecting to a virtual machine over your VPN connection, check the following:

  • Verify that your VPN connection is successful.
  • Verify that you are connecting to the private IP address for the VM.
  • If you can connect to the VM using the private IP address, but not the computer name, verify that you have configured DNS properly. For more information about how name resolution works for VMs, see Name Resolution for VMs.
  • For more information about RDP connections, see Troubleshoot Remote Desktop connections to a VM.

Modify IP address prefixes for a local network gateway

If the IP address prefixes that you want routed to your on-premises location change, you can modify the local network gateway. Two sets of instructions are provided. The instructions you choose depend on whether you have already created your gateway connection.

To modify local network gateway IP address prefixes - no gateway connection

To add additional address prefixes:

$local = Get-AzureRmLocalNetworkGateway -Name MyLocalNetworkGWName -ResourceGroupName MyRGName `
Set-AzureRmLocalNetworkGateway -LocalNetworkGateway $local `
-AddressPrefix @('10.0.0.0/24','20.0.0.0/24','30.0.0.0/24')

To remove address prefixes:
Leave out the prefixes that you no longer need. In this example, we no longer need prefix 20.0.0.0/24 (from the previous example), so we update the local network gateway, excluding that prefix.

$local = Get-AzureRmLocalNetworkGateway -Name MyLocalNetworkGWName -ResourceGroupName MyRGName `
Set-AzureRmLocalNetworkGateway -LocalNetworkGateway $local `
-AddressPrefix @('10.0.0.0/24','30.0.0.0/24')

To modify local network gateway IP address prefixes - existing gateway connection

If you have a gateway connection and want to add or remove the IP address prefixes contained in your local network gateway, you need to do the following steps, in order. This results in some downtime for your VPN connection. When modifying IP address prefixes, you don't need to delete the VPN gateway. You only need to remove the connection.

  1. Remove the connection.

    Remove-AzureRmVirtualNetworkGatewayConnection -Name MyGWConnectionName -ResourceGroupName MyRGName
    
  2. Modify the address prefixes for your local network gateway.

    Set the variable for the LocalNetworkGateway.

    $local = Get-AzureRmLocalNetworkGateway -Name MyLocalNetworkGWName -ResourceGroupName MyRGName
    

    Modify the prefixes.

    Set-AzureRmLocalNetworkGateway -LocalNetworkGateway $local `
    -AddressPrefix @('10.0.0.0/24','20.0.0.0/24','30.0.0.0/24')
    
  3. Create the connection. In this example, we configure an IPsec connection type. When you recreate your connection, use the connection type that is specified for your configuration. For additional connection types, see the PowerShell cmdlet page.

    Set the variable for the VirtualNetworkGateway.

    $gateway1 = Get-AzureRmVirtualNetworkGateway -Name RMGateway  -ResourceGroupName MyRGName
    

    Create the connection. This example uses the variable $local that you set in step 2.

    New-AzureRmVirtualNetworkGatewayConnection -Name MyGWConnectionName `
    -ResourceGroupName MyRGName -Location 'West US' `
    -VirtualNetworkGateway1 $gateway1 -LocalNetworkGateway2 $local `
    -ConnectionType IPsec `
    -RoutingWeight 10 -SharedKey 'abc123'
    

Modify the gateway IP address for a local network gateway

To modify the local network gateway 'GatewayIpAddress' - no gateway connection

If the VPN device that you want to connect to has changed its public IP address, you need to modify the local network gateway to reflect that change. Use the example to modify a local network gateway that does not have a gateway connection.

When modifying this value, you can also modify the address prefixes at the same time. Be sure to use the existing name of your local network gateway in order to overwrite the current settings. If you use a different name, you create a new local network gateway, instead of overwriting the existing one.

New-AzureRmLocalNetworkGateway -Name MyLocalNetworkGWName `
-Location "West US" -AddressPrefix @('10.0.0.0/24','20.0.0.0/24','30.0.0.0/24') `
-GatewayIpAddress "5.4.3.2" -ResourceGroupName MyRGName

To modify the local network gateway 'GatewayIpAddress' - existing gateway connection

If the VPN device that you want to connect to has changed its public IP address, you need to modify the local network gateway to reflect that change. If a gateway connection already exists, you first need to remove the connection. After the connection is removed, you can modify the gateway IP address and recreate a new connection. You can also modify the address prefixes at the same time. This results in some downtime for your VPN connection. When modifying the gateway IP address, you don't need to delete the VPN gateway. You only need to remove the connection.

  1. Remove the connection. You can find the name of your connection by using the 'Get-AzureRmVirtualNetworkGatewayConnection' cmdlet.

    Remove-AzureRmVirtualNetworkGatewayConnection -Name MyGWConnectionName `
    -ResourceGroupName MyRGName
    
  2. Modify the 'GatewayIpAddress' value. You can also modify the address prefixes at the same time. Be sure to use the existing name of your local network gateway to overwrite the current settings. If you don't, you create a new local network gateway, instead of overwriting the existing one.

    New-AzureRmLocalNetworkGateway -Name MyLocalNetworkGWName `
    -Location "West US" -AddressPrefix @('10.0.0.0/24','20.0.0.0/24','30.0.0.0/24') `
    -GatewayIpAddress "104.40.81.124" -ResourceGroupName MyRGName
    
  3. Create the connection. In this example, we configure an IPsec connection type. When you recreate your connection, use the connection type that is specified for your configuration. For additional connection types, see the PowerShell cmdlet page. To obtain the VirtualNetworkGateway name, you can run the 'Get-AzureRmVirtualNetworkGateway' cmdlet.

    Set the variables.

    $local = Get-AzureRMLocalNetworkGateway -Name MyLocalNetworkGWName -ResourceGroupName MyRGName `
    $vnetgw = Get-AzureRmVirtualNetworkGateway -Name RMGateway -ResourceGroupName MyRGName
    

    Create the connection.

    New-AzureRmVirtualNetworkGatewayConnection -Name MyGWConnectionName -ResourceGroupName MyRGName `
    -Location "West US" `
    -VirtualNetworkGateway1 $vnetgw `
    -LocalNetworkGateway2 $local `
    -ConnectionType IPsec -RoutingWeight 10 -SharedKey 'abc123'
    

Next steps