Adding connections to a VPN gateway

Adding a connection in the UI

To add a VPN connection to an existing VPN gateway, follow these steps:

1. Highlight the row of the gateway you want to work with in the VPN gateways table, then click New connection from the Actions menu .

   Alternatively, on the gateway's details page, you can click Create in the VPN connections section.

2. Define a connection between this gateway and a network outside your VPC by specifying the following information:

   • VPN connection name - Enter a name for the connection, such as my-connection.

   • Peer gateway address - Specify the IP address of the VPN gateway for the network outside your VPC.

     After you provision the VPN connection, you cannot change the peer gateway address type from IP address to FQDN, or from FQDN to IP address.

   • Establish mode - Select either Bidirectional or Peer only.

     • Bidirectional mode initiates IKE protocol negotiations (or rekeying processes) from either side of the VPN gateway.
     • Peer only mode allows the peer to initiate IKE protocol negotiations for this VPN gateway connection. The peer is also responsible for initiating the rekeying process after the connection is established.

     If your peer device is behind a NAT device and doesn't have a public IP address, make sure to specify Peer only.

   • Preshared key - Specify the authentication key of the VPN gateway for the network outside your VPC. The preshared key is a string of hexadecimal digits, or a passphrase of printable ASCII characters. To be compatible with most peer gateway types, this string must follow these rules:

     • Can be a combination of digits, lower or uppercase characters, or the following special characters: - + & ! @ # $ % ^ * ( ) . , :
     • The length of the string must be 6 - 128 characters.
     • Cannot start with 0x or 0s.

   • Distribute traffic (Route-based VPN only) - Enable to distribute traffic between the Up tunnels of the VPN gateway connection when a VPC route's next hop is the VPN connection. If this checkbox is not selected, the VPN gateway uses the tunnel with the small public IP as the primary egress path, and only when the primary egress path is disabled, does traffic go through the secondary path. For more information, see Use case 4: Distributing traffic for a route-based VPN.

   • Local IBM CIDRs (Policy-based VPN only) - Specify one or more CIDRs in the VPC that you want to connect through the VPN tunnel.

   • Peer CIDRs (Policy-based VPN only) - Specify one or more CIDRs in the other network that you want to connect through the VPN tunnel. Subnet range overlap between local and peer subnets is not allowed.

3. To configure how the VPN gateway sends messages to check that the peer gateway is active, specify the following information in the Dead peer detection section.

   • Action - The action to take if a peer gateway stops responding. For example, select Restart if you want the gateway to immediately renegotiate the connection.
   • Interval (secs) - How often to check that the peer gateway is active. By default, messages are sent every 2 seconds.
   • Timeout (secs) - How long to wait for a response from the peer gateway. By default, a peer gateway is considered inactive if a response isn't received within 10 seconds.

4. In the Policies section, specify the Internet Key Exchange (IKE) and Internet Protocol Security (IPsec) options to use for Phase 1 and Phase 2 negotiation of the connection.

   • Select Auto if you want the gateway to try to automatically establish the connection.
   • Select or create custom policies if you need to enforce particular security requirements, or if the VPN gateway for the other network doesn't support the security proposals that are tried by auto-negotiation.

5. In the Advanced options section, you can customize local and peer IKE identities instead of using the default IKE identity. One peer IKE identity can be specified at most.

   For policy-based VPN gateways, you can configure one local IKE identity at most. For route-based VPN gateways, if you want to configure a local IKE identity, you must provide two. You can provide values for the members or leave the input fields empty.

   • Local IKE identities - Select a type for the local IKE identity, then enter its value. For example, you can enter a single 4 octe IPv4 address (9.168.3.4), a FQDN (my-vpn.example.com), hostname (my-host), or base64-encoded key ID (MTIzNA==).

     • Static route mode consists of two members in active-active mode, where the first identity applies to the first member and the second identity applies to the second member. If you do not specify local IKE identities, then the type is an IPv4 address, and the value is the public IP address of the member’s VPN connection tunnel.

     • Policy mode consists of two members in active-standby mode. The local IKE identity applies to the active member. If you do not specify a value, then the local IKE identity is the public IP address of the VPN gateway.

   • Peer IKE identity - Select a type for the peer IKE identity, then enter its value. For example, you can enter an IPv4 address (9.168.3.4), a FQDN (my-vpn.example.com), hostname (my-host), or base64-encoded key ID (MTIzNA==).

     The peer IKE identity applies to the active member. If you do not specify a value, then use the peer gateway's IPv4 address or FQDN.

6. Review the Summary panel, then click Create VPN connection.

Adding a connection from the CLI

Before you begin, set up your CLI environment.

To create a VPN connection from the CLI, enter the following command:

ibmcloud is vpn-gateway-connection-create CONNECTION_NAME VPN_GATEWAY PEER PRESHARED_KEY
[--vpc VPC] [--admin-state-up true | false] [--dead-peer-detection-action restart | clear | hold | none]
[--distribute-traffic true | false]
[--dead-peer-detection-interval INTERVAL] [--dead-peer-detection-timeout TIMEOUT] [--ike-policy IKE_POLICY_ID]
[--ipsec-policy IPSEC_POLICY_ID] [--peer-cidr CIDR1 --peer-cidr CIDR2 ... --local-cidr CIDR1 --local-cidr CIDR2 ...]
[[--local-ike-identity-type fqdn | hostname | ipv4_address | key_id --local-ike-identity-value VALUE] |
[--local-ike-identities LISTENER_POLICIES_JSON | @LISTENER_POLICIES_JSON_FILE]]
[--peer-ike-identity-type fqdn | hostname | ipv4_address | key_id --peer-ike-identity-value VALUE]
[--establish-mode bidirectional | peer_only] [--output JSON] [-q, --quiet]
ibmcloud is vpn-gateway-connection-create CONNECTION_NAME VPN_GATEWAY PEER PRESHARED_KEY

Where:

CONNECTION_NAME

The name of the connection.

VPN_GATEWAY

The ID of the VPN gateway.

PEER

The IP address or FQDN of the peer VPN gateway.

PRESHARED_KEY

The preshared key.

--vpc

The ID or name of the VPC. This is only required to specify the unique resource by its name inside this VPC.

--admin-state-up

If set to false, the VPN gateway connection is shut down. This can be either true or false.

--dead-peer-detection-action

The dead peer detection action. This can be either restart, clear, hold, or none. (default: restart).

--dead-peer-detection-interval

The dead peer detection interval in seconds (default: 2).

--dead-peer-detection-timeout

The dead peer detection timeout in seconds (default: 10).

--distribute-traffic

Set to true to distribute traffic between the Up tunnels of the VPN gateway connection when a VPC route's next hop is the VPN connection.This can be either true or false. For more information, see Distributing traffic for a route-based VPN.

--ike-policy

The ID of the IKE policy.

--ipsec-policy

The ID of the IPsec policy.

--local-ike-identity-type

The type of local IKE identity. This can be either fqdn, hostname, ipv4_address or key_id.

--local-ike-identity-value

The value of the local IKE identity.

--local-ike-identities

The ID of the local IKE identity. LOCAL_IKE_IDENTITIES_JSON | @LOCAL_IKE_IDENTITIES_JSON_FILE in JSON or a JSON file.

-peer-cidr

The peer CIDRs for the resource.

-local-cidr

The local CIDR for the resource.

-peer-ike-identity-type

The type of peer IKE identity. This can be either ipv4_address, fqdn, hostname, or key_id.

--peer-ike-identity-value

The value of the peer IKE identity.

Policy-based VPN gateways can only have one local IKE identity.

If a route-based VPN gateway has local IKE identities specified, then there must be at least two; the first identity applies to the first member of the VPN gateway, and the second identity applies to the second member.

--establish-mode

This can be either bidirectional or peer_only. Bidirectional mode initiates IKE protocol negotiations (or rekeying processes) from either side of the VPN gateway. Peer only mode allows the peer to initiate IKE protocol negotiations for this VPN gateway connection. The peer is also responsible for initiating the rekeying process after the connection is established. If rekeying doesn't occur, the VPN gateway connection is removed after its lifetime expires.

-output

Specifies that the output will be in JSON format.

-q, --quiet

Suppresses verbose output.

Adding a local CIDR to a VPN gateway connection from the CLI

Before you begin, set up your CLI environment.

To add a local CIDR to a VPN gateway connection from the CLI, enter the following command:

This command is only supported by policy mode VPN gateways.

ibmcloud is vpn-gateway-connection-local-cidr-add VPN_GATEWAY CONNECTION PREFIX_ADDRESS PREFIX_LENGTH [--vpc VPC] [--output JSON] [-q, --quiet]

Where:

VPN_GATEWAY

The ID of the VPN gateway.

CONNECTION

The ID or name of the VPN connection.

PREFIX_ADDRESS

The prefix address part of the CIDR.

PREFIX_LENGTH

The prefix length part of the CIDR.

--output value

The output in JSON format.

-q, --quiet

Suppresses verbose output.

Adding a peer CIDR to a VPN gateway connection from the CLI

Before you begin, set up your CLI environment.

To add a peer CIDR to a VPN gateway connection from the CLI, enter the following command:

This command is only supported by policy mode VPN gateway.

ibmcloud is vpn-gateway-connection-peer-cidr-add VPN_GATEWAY CONNECTION PREFIX_ADDRESS PREFIX_LENGTH [--vpc VPC] [--output JSON] [-q, --quiet]

Where:

VPN_GATEWAY

ID of the VPN gateway.

CONNECTION

ID or name of the VPN connection.

PREFIX_ADDRESS

Prefix address part of the CIDR.

PREFIX_LENGTH

Prefix length part of the CIDR.

--output value

Output in JSON format.

-q, --quiet

Suppress verbose output.

Adding a connection with the API

To create a VPN connection with the API, follow these steps:

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   • vpnGatewayId - The VPN gateway identifier.

     export vpnGatewayId=<your_vpn_gateway_id>
     

   • ikePolicyId - The unique identifier for this IKE policy.

     export ikePolicyId=<your_ike_policy_id>
     

   • ipsecPolicyId - The unique identifier for this IPsec policy.

     export ipsecPolicyId=<your_ipsec_policy_id>
     

3. When all variables are initiated, create the VPN gateway connection. For example:

      curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpnGatewayId/connections?version=$api_version&generation=2" \
        -H "Authorization: $iam_token" \
        -d '{
            "name": "my-vpn-connection",
            "psk": "'$psk'",
            "dead_peer_detection": {
                "action": "restart",
                "interval": 2,
                "timeout": 10
            },
            "local": {
                "cidrs": "'$localCidrs'"
            },
            "peer": {
                "cidrs": "'$remoteCidrs'",
                "address": "7.8.9.10"
            }
            "ike_policy": {
                "id": "'$ikePolicyId'"
            },
            "ipsec_policy": {
                "id": "'$ipsecPolicyId'"
            }
        }'
   

4. (Optional) To create a connection using advanced configuration options:

   curl -X POST "$vpc_api_endpoint/v1/vpn_gateways/$vpnGatewayId/connections?version=$api_version&generation=2"  \
         -H "Authorization: $iam_token"      -d '{  \
         "name": "my-advanced-vpn-connection",
         "establish_mode": "peer_only",
         "psk": "'$psk'",
         "dead_peer_detection": {
             "action": "restart",
             "interval": 2,
             "timeout": 10
         },
         "local": {
             "cidrs": "'$localCidrs'",
             "ike_identities": [
                 {
                     "type": "key_id",
                     "value": "dGVzdGtleQ=="
                 }
             ]
         },
         "peer": {
             "cidrs": "'$remoteCidrs'",
             "ike_identity": {
                 "type": "hostname",
                 "value": "cisco-asa"
             },
             "fqdn": "on-prem.test.com"
         }
         "ike_policy": {
             "id": "'$ikePolicyId'"
         },
         "ipsec_policy": {
             "id": "'$ipsecPolicyId'"
         },
         "distribute_traffic":true
     }'
   

Adding a local CIDR to a VPN gateway connection with the API

To add a local CIDR to a VPN gateway connection with the API, follow these steps:

This API is only supported by policy mode VPN gateways.

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   • vpnGatewayId - The VPN gateway identifier.

     export vpnGatewayId=<your_vpn_gateway_id>
     

   • connectionId - The unique identifier for this VPN connection.

     export connectionId=<your_connection_id>
     

   • cidr_prefix - The prefix address part of the CIDR.

     export cidr_prefix=<your_cidr_prefix>
     

   • prefix_length - The prefix length part of the CIDR.

     export prefix_length=<your_prefix_length>
     

3. When all variables are initiated, add a local CIDR to a VPN gateway connection. For example:

      curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpnGatewayId/connections/$connectionId/local_cidrs/${cidr_prefix}/${prefix_length}?version=$api_version&generation=2" \
        -H "Authorization: $iam_token"
   

Adding a peer CIDR to a VPN gateway connection with the API

To add a peer CIDR to a VPN gateway connection with the API, follow these steps:

This API is only supported by policy mode VPN gateways.

1. Set up your API environment with the right variables.

2. Store any additional variables to be used in the API commands, for example:

   • vpnGatewayId - The VPN gateway identifier

     export vpnGatewayId=<your_vpn_gateway_id>
     

   • connectionId - The unique identifier for this VPN connection

     export connectionId=<your_connection_id>
     

   • cidr_prefix - The prefix address part of the CIDR

     export cidr_prefix=<your_cidr_prefix>
     

   • prefix_length - The prefix length part of the CIDR.

     export prefix_length=<your_prefix_length>
     

3. When all variables are initiated, add a peer CIDR to a VPN gateway connection. For example:

      curl -X PUT "$vpc_api_endpoint/v1/vpn_gateways/$vpnGatewayId/connections/$connectionId/peer_cidrs/${cidr_prefix}/${prefix_length}?version=$api_version&generation=2" \
        -H "Authorization: $iam_token"
   

Adding a connection by using Terraform

To add a connection by using Terraform, run the following command:

   resource "ibm_is_vpn_gateway_connection" "is_vpn_gateway_connection" {
     name                 = "my-vpn-gateway-connection"
     vpn_gateway    = ibm_is_vpn_gateway.is_vpn_gateway.id
     peer_address   =  "7.8.9.10"
     preshared_key = var.presharedkey
     local_cidrs        = [var.localCIDR]
     peer_cidrs        = [var.peerCIDR]
   }

The following Terraform example creates a VPN gateway connection:

resource "ibm_is_vpn_gateway_connection" "is_vpn_gateway_connection" {
  name           = "my-vpn-gateway-connection"
  vpn_gateway    = ibm_is_vpn_gateway.is_vpn_gateway.id
  preshared_key  = "VPNDemoPassword"
  establish_mode = "bidirectional"
  peer {
    cidrs   = [var.peerCIDR]
    address = "7.8.9.10"
  }
  local {
    cidrs = [var.localCIDR]
  }
  ike_policy   = ibm_is_ike_policy.is_ike_policy.id
  ipsec_policy = ibm_is_ipsec_policy.is_ipsec_policy.id
}

The following Terraform example creates a VPN connection for a route-based VPN gateway with the distribute traffic feature enabled:

resource "ibm_is_vpn_gateway_connection" "test_VPNGatewayConnection1" {
    name = "example-vpn-gateway-connection"
    vpn_gateway = "${ibm_is_vpn_gateway.example.id}"
    peer_address = "${ibm_is_vpn_gateway.example.public_ip_address}"
    preshared_key = "VPNDemoPassword"
    distribute-traffic = true
}

The following Terraform example creates a VPN connection using advanced configuration options:

resource "ibm_is_vpn_gateway_connection" "is_vpn_gateway_connection" {
  name           = "to-prem"
  vpn_gateway    = ibm_is_vpn_gateway.is_vpn_gateway.id
  preshared_key  = "test123"
  establish_mode = "peer_only"
  peer {
    cidrs   = ["192.168.0.0/24"]
    ike_identity {
      type  = "ipv4_address"
      value = "192.168.0.1"
    }
    fqdn = "on-prem.test.com"
  }
  local {
    cidrs = ["10.10.20.0/28"]
  }
}

For more information, see the Terraform registry.