Create a virtual network with a Site-to-Site VPN connection using CLI

This article shows you how to use the Azure CLI 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:

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

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 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.
  • Verify that you have installed latest version of the CLI commands (2.0 or later). For information about installing the CLI commands, see Install Azure CLI 2.0 and Get Started with Azure CLI 2.0.

Example values

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

#Example values

VnetName                = TestVNet1 
ResourceGroup           = TestRG1 
Location                = eastus 
AddressSpace            = 10.11.0.0/16 
SubnetName              = Subnet1 
Subnet                  = 10.11.0.0/24 
GatewaySubnet           = 10.11.255.0/27 
LocalNetworkGatewayName = Site2 
LNG Public IP           = <VPN device IP address>
LocalAddrPrefix1        = 10.0.0.0/24
LocalAddrPrefix2        = 20.0.0.0/24   
GatewayName             = VNet1GW 
PublicIP                = VNet1GWIP 
VPNType                 = RouteBased 
GatewayType             = Vpn 
ConnectionName          = VNet1toSite2

1. Connect to your subscription

Log in to your Azure subscription with the az login command and follow the on-screen directions. For more information about logging in, see Get Started with Azure CLI 2.0.

az login

If you have more than one Azure subscription, list the subscriptions for the account.

az account list --all

Specify the subscription that you want to use.

az account set --subscription <replace_with_your_subscription_id>

2. Create a resource group

The following example creates a resource group named 'TestRG1' in the 'eastus' location. If you already have a resource group in the region that you want to create your VNet, you can use that one instead.

az group create --name TestRG1 --location eastus

3. Create a virtual network

If you don't already have a virtual network, create one using the az network vnet create command. 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. Otherwise, traffic will not route correctly if a duplicate address range exists on both sides of the VPN connection.

The following example creates a virtual network named 'TestVNet1' and a subnet, 'Subnet1'.

az network vnet create --name TestVNet1 --resource-group TestRG1 --address-prefix 10.11.0.0/16 --location eastus --subnet-name Subnet1 --subnet-prefix 10.11.0.0/24

4. Create the gateway subnet

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?

For this configuration, you also need a gateway subnet. The virtual network gateway uses a gateway subnet that contains the IP addresses that are used by the VPN gateway services. When you create a gateway subnet, it must be named 'GatewaySubnet'. If you name it something else, you create a subnet, but Azure won't treat it as a gateway subnet.

The size of the gateway subnet that you specify depends on the VPN gateway configuration that you want to create. While it is possible to create a gateway subnet as small as /29, we recommend that 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 accommodate possible future configurations.

Use the az network vnet subnet create command to create the gateway subnet.

az network vnet subnet create --address-prefix 10.11.255.0/27 --name GatewaySubnet --resource-group TestRG1 --vnet-name TestVNet1

5. 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 --gateway-ip-address is the IP address of your on-premises VPN device. Your VPN device cannot be located behind a NAT.
  • The --local-address-prefixes are your on-premises address spaces.

Use the az network local-gateway create command to add a local network gateway with multiple address prefixes:

az network local-gateway create --gateway-ip-address 23.99.221.164 --name Site2 --resource-group TestRG1 --local-address-prefixes 10.0.0.0/24 20.0.0.0/24

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

Use the az network public-ip create command to request a Dynamic Public IP address.

az network public-ip create --name VNet1GWIP --resource-group TestRG1 --allocation-method Dynamic

7. 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 --gateway-type for a Site-to-Site configuration is Vpn. The gateway type is always specific to the configuration that you are implementing. For more information, see Gateway types.
  • The --vpn-type can be RouteBased (referred to as a Dynamic Gateway in some documentation), or PolicyBased (referred to as a Static Gateway in some documentation). The setting is specific to requirements of the device that you are connecting to. For more information about VPN gateway types, see About VPN Gateway configuration settings.
  • Select the Gateway SKU that you want to use. There are configuration limitations for certain SKUs. For more information, see Gateway SKUs.

Create the VPN gateway using the az network vnet-gateway create command. If you run this command using the '--no-wait' parameter, you don't see any feedback or output. This parameter allows the gateway to create in the background. It takes around 45 minutes to create a gateway.

az network vnet-gateway create --name VNet1GW --public-ip-address VNet1GWIP --resource-group TestRG1 --vnet TestVNet1 --gateway-type Vpn --vpn-type RouteBased --sku VpnGw1 --no-wait 

8. 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, use the az network public-ip list command. For easy reading, the output is formatted to display the list of public IPs in table format.

    az network public-ip list --resource-group TestRG1 --output table
    

See the following links for configuration information:

9. Create the VPN connection

Create the Site-to-Site VPN connection between your virtual network gateway and your on-premises VPN device. Pay particular attention to the shared key value, which must match the configured shared key value for your VPN device.

Create the connection using the az network vpn-connection create command.

az network vpn-connection create --name VNet1toSite2 -resource-group TestRG1 --vnet-gateway1 VNet1GW -l eastus --shared-key abc123 --local-gateway2 Site2

After a short while, the connection will be established.

10. Verify the VPN connection

You can verify that your connection succeeded by using the az network vpn-connection show command. In the example, '--name' refers to the name of the connection that you want to test. When the connection is in the process of being established, its connection status shows 'Connecting'. Once the connection is established, the status changes to 'Connected'.

az network vpn-connection show --name VNet1toSite2 --resource-group TestRG1

If you want to use another method to verify your connection, see Verify a VPN Gateway connection.

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.

Common tasks

This section contains common commands that are helpful when working with site-to-site configurations. For the full list of CLI networking commands, see Azure CLI - Networking.

To view local network gateways

To view a list of the local network gateways, use the az network local-gateway list command.

az network local-gateway list --resource-group TestRG1

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

If you don't have a gateway connection and you want to add or remove IP address prefixes, you use the same command that you use to create the local network gateway, az network local-gateway create. You can also use this command to update the gateway IP address for the VPN device. To overwrite the current settings, use the existing name of your local network gateway. If you use a different name, you create a new local network gateway, instead of overwriting the existing one.

Each time you make a change, the entire list of prefixes must be specified, not just the prefixes that you want to change. Specify only the prefixes that you want to keep. In this case, 10.0.0.0/24 and 20.0.0.0/24

az network local-gateway create --gateway-ip-address 23.99.221.164 --name Site2 -g TestRG1 --local-address-prefixes 10.0.0.0/24 20.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 IP address prefixes, you can update the prefixes using az network local-gateway update. This results in some downtime for your VPN connection. When modifying the IP address prefixes, you don't need to delete the VPN gateway.

Each time you make a change, the entire list of prefixes must be specified, not just the prefixes that you want to change. In this example, 10.0.0.0/24 and 20.0.0.0/24 are already present. We add the prefixes 30.0.0.0/24 and 40.0.0.0/24 and specify all 4 of the prefixes when updating.

az network local-gateway update --local-address-prefixes 10.0.0.0/24 20.0.0.0/24 30.0.0.0/24 40.0.0.0/24 --name VNet1toSite2 -g TestRG1

To modify the local network gateway 'gatewayIpAddress'

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. The gateway IP address can be changed without removing an existing VPN gateway connection (if you have one). To modify the gateway IP address, replace the values 'Site2' and 'TestRG1' with your own using the az network local-gateway update command.

az network local-gateway update --gateway-ip-address 23.99.222.170 --name Site2 --resource-group TestRG1

Verify that the IP address is correct in the output:

"gatewayIpAddress": "23.99.222.170",

To verify the shared key values

Verify that the shared key value is the same value that you used for your VPN device configuration. If it is not, either run the connection again using the value from the device, or update the device with the value from the return. The values must match. To view the shared key, use the az network vpn-connection-list.

az network vpn-connection shared-key show --connection-name VNet1toSite2 --resource-group TestRG1

To view the VPN gateway Public IP address

To find the public IP address of your virtual network gateway, use the az network public-ip list command. For easy reading, the output for this example is formatted to display the list of public IPs in table format.

az network public-ip list --resource-group TestRG1 --output table

Next steps