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.

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.
• If you're 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.

Azure PowerShell

You can install and run the Azure PowerShell cmdlets locally on your computer. PowerShell cmdlets are updated frequently. If you haven't installed the latest version, the values specified in the instructions may fail. To find the versions of Azure PowerShell installed on your computer, use the Get-Module -ListAvailable Az cmdlet. To install or update, see Install the Azure PowerShell module.

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                = VNet1
ResourceGroup           = TestRG1
Location                = China North
AddressSpace            = 10.1.0.0/16 
SubnetName              = Frontend 
Subnet                  = 10.1.0.0/24 
GatewaySubnet           = 10.1.255.0/27
LocalNetworkGatewayName = Site1
LNG Public IP           = <On-premises VPN device IP address> 
Local Address Prefixes  = 10.0.0.0/24, 20.0.0.0/24
Gateway Name            = VNet1GW
PublicIP                = VNet1GWPIP
Gateway IP Config       = gwipconfig1 
VPNType                 = RouteBased 
GatewayType             = Vpn 
ConnectionName          = VNet1toSite1

1. 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.

About the gateway subnet

The virtual network gateway uses specific subnet called the gateway subnet. The gateway subnet is part of the virtual network IP address range that you specify when configuring your virtual network. It contains the IP addresses that the virtual network gateway resources and services use. The subnet must be named 'GatewaySubnet' in order for Azure to deploy the gateway resources. You can't specify a different subnet to deploy the gateway resources to. If you don't have a subnet named 'GatewaySubnet', when you create your VPN gateway, it will fail.

When you create the gateway subnet, you specify the number of IP addresses that the subnet contains. The number of IP addresses needed depends on the VPN gateway configuration that you want to create. Some configurations require more IP addresses than others. We recommend that you create a gateway subnet that uses a /27 or /28.

If you see an error that specifies that the address space overlaps with a subnet, or that the subnet is not contained within the address space for your virtual network, check your VNet address range. You may not have enough IP addresses available in the address range you created for your virtual network. For example, if your default subnet encompasses the entire address range, there are no IP addresses left to create additional subnets. You can either adjust your subnets within the existing address space to free up IP addresses, or specify an additional address range and create the gateway subnet there.

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-AzResourceGroup -Name TestRG1 -Location 'China North'

Create your virtual network.

1. Set the variables.

   $subnet1 = New-AzVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -AddressPrefix 10.1.255.0/27
   $subnet2 = New-AzVirtualNetworkSubnetConfig -Name 'Frontend' -AddressPrefix 10.1.0.0/24
   

2. Create the VNet.

   New-AzVirtualNetwork -Name VNet1 -ResourceGroupName TestRG1 `
   -Location 'China North' -AddressPrefix 10.1.0.0/16 -Subnet $subnet1, $subnet2
   

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

Use the steps in this section if you already have a virtual network, but need to add a gateway subnet.

1. Set the variables.

   $vnet = Get-AzVirtualNetwork -ResourceGroupName TestRG1 -Name VNet1
   

2. Create the gateway subnet.

   Add-AzVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -AddressPrefix 10.1.255.0/27 -VirtualNetwork $vnet
   

3. Set the configuration.

   Set-AzVirtualNetwork -VirtualNetwork $vnet
   

2. Create the local network gateway

The local network gateway (LNG) typically refers to your on-premises location. It isn't the same as a virtual network gateway. 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.

Select one of the following examples. The values used in the examples are:

• The GatewayIPAddress is the IP address of your on-premises VPN device.
• The AddressPrefix is your on-premises address space.

Single address prefix example

New-AzLocalNetworkGateway -Name Site1 -ResourceGroupName TestRG1 `
-Location 'China North' -GatewayIpAddress '23.99.221.164' -AddressPrefix '10.0.0.0/24'

Multiple address prefix example

New-AzLocalNetworkGateway -Name Site1 -ResourceGroupName TestRG1 `
-Location 'China North' -GatewayIpAddress '23.99.221.164' -AddressPrefix @('20.0.0.0/24','10.0.0.0/24')

3. 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. 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 for your virtual network VPN gateway.

$gwpip= New-AzPublicIpAddress -Name VNet1GWPIP -ResourceGroupName TestRG1 -Location 'China North' -AllocationMethod Static -Sku Standard

4. Create the gateway IP addressing configuration

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

$vnet = Get-AzVirtualNetwork -Name VNet1 -ResourceGroupName TestRG1
$subnet = Get-AzVirtualNetworkSubnetConfig -Name 'GatewaySubnet' -VirtualNetwork $vnet
$gwipconfig = New-AzVirtualNetworkGatewayIpConfig -Name gwipconfig1 -SubnetId $subnet.Id -PublicIpAddressId $gwpip.Id

5. Create the VPN gateway

Create the virtual network VPN gateway. Creating a gateway can often take 45 minutes or more, depending on the selected gateway SKU. The following values are used in the example:

• The -GatewayType for a site-to-site configuration is Vpn. The gateway type is always specific to the configuration that you're implementing. For example, other gateway configurations might 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-AzVirtualNetworkGateway -Name VNet1GW -ResourceGroupName TestRG1 `
-Location 'China North' -IpConfigurations $gwipconfig -GatewayType Vpn `
-VpnType RouteBased -GatewaySku VpnGw2

6. 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 items:

• 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. In this example, VNet1GWPIP is the name of the public IP address resource that you created in an earlier step.

  Get-AzPublicIpAddress -Name VNet1GWPIP -ResourceGroupName TestRG1
  

Depending on the VPN device that you have, you might be able to download a VPN device configuration script. For more information, see Download VPN device configuration scripts.

The following links provide more configuration information:

• For information about compatible VPN devices, see About VPN devices.

• Before you configure your VPN device, check for any known device compatibility issues.

• For links to device configuration settings, see Validated VPN devices. We provide the device configuration links on a best-effort basis, but it's always best to check with your device manufacturer for the latest configuration information.

  The list shows the versions that we tested. If the OS version for your VPN device isn't on the list, it still might be compatible. Check with your device manufacturer.

• For basic information about VPN device configuration, see Overview of partner VPN device configurations.

• For information about editing device configuration samples, see Editing samples.

• For cryptographic requirements, see About cryptographic requirements and Azure VPN gateways.

• For information about parameters that you need to complete your configuration, see Default IPsec/IKE parameters. The information includes IKE version, Diffie-Hellman (DH) group, authentication method, encryption and hashing algorithms, security association (SA) lifetime, perfect forward secrecy (PFS), and Dead Peer Detection (DPD).

• For IPsec/IKE policy configuration steps, see Configure custom IPsec/IKE connection policies for S2S VPN and VNet-to-VNet.

• To connect multiple policy-based VPN devices, see Connect a VPN gateway to multiple on-premises policy-based VPN devices.

7. 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-AzVirtualNetworkGateway -Name VNet1GW -ResourceGroupName TestRG1
   $local = Get-AzLocalNetworkGateway -Name Site1 -ResourceGroupName TestRG1
   

2. Create the connection.

   New-AzVirtualNetworkGatewayConnection -Name VNet1toSite1 -ResourceGroupName TestRG1 `
   -Location 'China North' -VirtualNetworkGateway1 $gateway1 -LocalNetworkGateway2 $local `
   -ConnectionType IPsec -SharedKey 'abc123'
   

After a short while, the connection will be established.

8. 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-AzVirtualNetworkGatewayConnection' 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-AzVirtualNetworkGatewayConnection -Name VNet1toSite1 -ResourceGroupName TestRG1
   

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's deployed to your virtual network 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're 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 by either looking at the properties for the VM in the Azure portal or by using PowerShell.

   • Azure portal: Locate your VM 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-AzVM
     $Nics = Get-AzNetworkInterface | Where-Object 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're connected to your virtual network.

3. Open Remote Desktop Connection by entering RDP or Remote Desktop Connection in the search box on the taskbar. Then select Remote Desktop Connection. You can also open Remote Desktop Connection by using the mstsc command in PowerShell.

4. In Remote Desktop Connection, enter the private IP address of the VM. You can select Show Options to adjust other settings and then connect.

If you're having trouble connecting to a VM over your VPN connection, check the following points:

• Verify that your VPN connection is successful.
• Verify that you're connecting to the private IP address for the VM.
• If you can connect to the VM by using the private IP address but not the computer name, verify that you've 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.

To 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. When using these examples, modify the values to match your environment.

To add additional address prefixes:

1. Set the variable for the LocalNetworkGateway.

   $local = Get-AzLocalNetworkGateway -Name Site1 -ResourceGroupName TestRG1
   

2. Modify the prefixes. The values you specify overwrite the previous values.

   Set-AzLocalNetworkGateway -LocalNetworkGateway $local `
   -AddressPrefix @('10.101.0.0/24','10.101.1.0/24','10.101.2.0/24')
   

To remove address prefixes:

Leave out the prefixes that you no longer need. In this example, we no longer need prefix 10.101.2.0/24 (from the previous example), so we'll update the local network gateway and exclude that prefix.

1. Set the variable for the LocalNetworkGateway.

   $local = Get-AzLocalNetworkGateway -Name Site1 -ResourceGroupName TestRG1
   

2. Set the gateway with the updated prefixes.

   Set-AzLocalNetworkGateway -LocalNetworkGateway $local `
   -AddressPrefix @('10.101.0.0/24','10.101.1.0/24')
   

To modify the gateway IP address for a local network gateway

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. 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-AzLocalNetworkGateway -Name Site1 `
-Location "China North" -AddressPrefix @('10.101.0.0/24','10.101.1.0/24') `
-GatewayIpAddress "5.4.3.2" -ResourceGroupName TestRG1

To delete a gateway connection

If you don't know the name of your connection, you can find it by using the 'Get-AzVirtualNetworkGatewayConnection' cmdlet.

Remove-AzVirtualNetworkGatewayConnection -Name VNet1toSite1 `
-ResourceGroupName TestRG1

Next steps

• Once your connection is complete, you can add virtual machines to your virtual networks. For more information, see Virtual Machines.
• For information about BGP, see the BGP Overview and How to configure BGP.
• For information about creating a site-to-site VPN connection using Azure Resource Manager template, see Create a site-to-site VPN Connection.
• For information about creating a vnet-to-vnet VPN connection using Azure Resource Manager template, see Deploy HBase geo replication.