Create a site-to-site VPN connection - shared key authentication - Azure CLI

  • Article

This article shows you how to use the Azure CLI to create a site-to-site (S2S) VPN gateway connection from your on-premises network to a virtual network. You can also create this configuration using a different deployment tool by selecting a different option from the following list:

Site-to-site VPN Gateway cross-premises connection diagram for CLI article.

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 your environment meets the following criteria before beginning configuration:

  • You have an Azure account with an active subscription. If you don't have one, you can create one for trial.

  • 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 routes to your on-premises location. None of the subnets of your on-premises network can overlap with the virtual network subnets that you want to connect to.

  • VPN devices:

    • Make sure you have a compatible VPN device and someone who can configure it. For more information about compatible VPN devices and device configuration, see About VPN devices.
    • Verify whether your VPN device supports active-active mode gateways. This article creates an active-active mode VPN gateway, which is recommended for highly available connectivity. Active-active mode specifies that both gateway VM instances are active. This mode requires two public IP addresses, one for each gateway VM instance. You configure your VPN device to connect to the IP address for each gateway VM instance.
      If your VPN device doesn't support this mode, don't enable this mode for your gateway. For more information, see Design highly available connectivity for cross-premises and VNet-to-VNet connections and About active-active mode VPN gateways.

  • Install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • Sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  • This article requires version 2.0 or later of the Azure CLI.

Connect to your subscription

Connect to your subscription.

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

az login

Note

Before you can use Azure CLI 2.0 in Azure China, please run az cloud set -n AzureChinaCloud first to change the cloud environment. If you want to switch back to Global Azure, run az cloud set -n AzureCloud again.

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>

Create a resource group

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

az group create --name TestRG1 --location chinanorth

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 virtual network 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 virtual network to another virtual network, the address space cannot overlap with other virtual network. Take care to plan your network configuration accordingly.

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

az network vnet create --name VNet1 --resource-group TestRG1 --address-prefix 10.1.0.0/16 --location chinanorth --subnet-name Subnet1 --subnet-prefix 10.1.0.0/24

Create the gateway subnet

Virtual network gateway resources are deployed to a specific subnet named GatewaySubnet. The gateway subnet is part of the virtual network IP address range that you specify when you configure your virtual network.

If you don't have a subnet named GatewaySubnet, when you create your VPN gateway, it fails. We recommend that you create a gateway subnet that uses a /27 (or larger). For example, /27 or /26. For more information, see VPN Gateway settings - Gateway Subnet.

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

az network vnet subnet create --address-prefix 10.1.255.0/27 --name GatewaySubnet --resource-group TestRG1 --vnet-name VNet1

Important

Network security groups (NSGs) on the gateway subnet are not supported. Associating a network security group to this subnet might cause your virtual network gateway (VPN and ExpressRoute gateways) to stop functioning as expected. For more information about network security groups, see What is a network security group?

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'll 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.
  • 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 203.0.133.8 --name Site1 --resource-group TestRG1 --local-address-prefixes 192.168.1.0/24 192.168.3.0/24

Request a public IP address

A VPN gateway must have a public IP address. If you want to create an active-active gateway (recommended), you must request two public IP addresses. You first request the IP address resource, and then refer to it when creating your virtual network gateway. The IP address is 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. If you want to create a VPN Gateway using the Basic gateway SKU, request a public IP address with the following values --allocation-method Dynamic --sku Basic.

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

az network public-ip create --name VNet1GWpip1 --resource-group TestRG1 --allocation-method Static --sku Standard --version IPv4 --zone 1 2 3

To create an active-active gateway (recommended), request a second public IP address:

az network public-ip create --name VNet1GWpip2 --resource-group TestRG1 --allocation-method Static --sku Standard --version IPv4 --zone 1 2 3

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.

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're implementing. For more information, see Gateway types.
  • The --vpn-type is RouteBased.
  • 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 45 minutes or more to create a gateway, depending on the SKU.

Active-active mode gateway

az network vnet-gateway create --name VNet1GW --public-ip-addresses VNet1GWpip1 VNet1GWpip2 --resource-group TestRG1 --vnet VNet1 --gateway-type Vpn --vpn-type RouteBased --sku VpnGw2AZ --vpn-gateway-generation Generation2 --no-wait

Active-standby mode gateway

az network vnet-gateway create --name VNet1GW --public-ip-addresses VNet1GWpip1 --resource-group TestRG1 --vnet VNet1 --gateway-type Vpn --vpn-type RouteBased --sku VpnGw2AZ --vpn-gateway-generation Generation2 --no-wait

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 you configure your VPN device, you need the following values:

  • Shared key: This shared key is the same one that you specify when you create your site-to-site VPN connection. In our examples, we use a simple shared key. We recommend that you generate a more complex key to use.

  • Public IP addresses of your virtual network gateway instances: Obtain the IP address for each VM instance. If your gateway is in active-active mode, you'll have an IP address for each gateway VM instance. Be sure to configure your device with both IP addresses, one for each active gateway VM. Active-standby mode gateways have only one IP address.

    Note

    For S2S connections with an active-active mode VPN gateway, ensure tunnels are established to each gateway VM instance. If you establish a tunnel to only one gateway VM instance, the connection will go down during maintenance. If your VPN device doesn't support this setup, configure your gateway for active-standby mode instead.

    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

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:

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. Create additional connections if you're creating a highly available gateway configuration such as active-active mode.

az network vpn-connection create --name VNet1toSite1 --resource-group TestRG1 --vnet-gateway1 VNet1GW -l chinanorth --shared-key abc123 --local-gateway2 Site1

After a short while, the connection will be established.

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'. Modify the following example with the values for your environment.

az network vpn-connection show --name <connection-name> --resource-group <resource-group-name>

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

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 want to add or remove IP address prefixes and your gateway doesn't have a connection yet, you can update the prefixes using az network local-gateway create. 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. You can also use this command to update the gateway IP address for the VPN device.

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 10.3.0.0/16

az network local-gateway create --gateway-ip-address 23.99.221.164 --name Site2 -g TestRG1 --local-address-prefixes 10.0.0.0/24 10.3.0.0/16

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.

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 10.3.0.0/16 are already present. We add the prefixes 10.5.0.0/16 and 10.6.0.0/16 and specify all 4 of the prefixes when updating.

az network local-gateway update --local-address-prefixes 10.0.0.0/24 10.3.0.0/16 10.5.0.0/16 10.6.0.0/16 --name VNet1toSite2 -g TestRG1

To modify the local network gateway 'gatewayIpAddress'

If you change the public IP address for your VPN device, you need to modify the local network gateway with the updated IP address. When modifying the gateway, be sure to specify 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 gateway information.

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 isn't, 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