Help Center/ Virtual Private Network/ API Reference/ API/ S2C VPN API/ VPN Connection/ Querying the VPN Connection List
Updated on 2024-12-03 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Querying the VPN Connection List

Function

This API is used to query the VPN connection list.

Calling Method

For details, see Calling APIs.

URI

GET /v5/{project_id}/vpn-connection

Table 1 Parameter description

Parameter

Type

Mandatory

Description

project_id

String

Yes

Specifies a project ID. You can obtain the project ID by referring to Obtaining the Project ID.
Table 2 Parameter in a query request

Parameter

Type

Mandatory

Description

vgw_ip

String

No

Specifies an EIP ID or private IP address of a VPN gateway.

vgw_id

String

No

Specifies a VPN gateway ID.

enterprise_project_id

Array

No

Specifies an enterprise project ID.

limit

Integer

No
  • Specifies the number of records returned on each page during pagination query.
  • The value ranges from 0 to 200.
  • The default value is 200.

marker

String

No
  • Specifies the start flag for querying the current page. If this parameter is left blank, the first page is queried. The marker for querying the next page is the next_marker in the page_info object returned on the current page.
  • This parameter must be used together with limit.

Request

  • Request parameters

    None

  • Example requests
    1. Query all VPN connections. 
      GET https://{Endpoint}/v5/{project_id}/vpn-connection
    2. Query VPN connections of a specified vgw_ip. 
      GET https://{Endpoint}/v5/{project_id}/vpn-connection?vgw_ip={vgw_ip}&limit={limit}&marker={marker}
    3. Query VPN connections of a specified VPN gateway instance. 
      GET https://{Endpoint}/v5/{project_id}/vpn-connection?vgw_id={vgw_id}&limit={limit}&marker={marker}

Response

  • Response parameters

    Returned status code 200: successful operation

    Table 3 Parameters in the response body

    Parameter

    Type

    Description

    vpn_connections

    Array of

    ResponseVpnConnection objects

    Specifies the VPN connection object.

    page_info

    PageInfo object

    Specifies pagination information.

    request_id

    String

    Specifies a request ID.

    total_count

    Long

    Specifies the total number of a tenant's connections.
    Table 4 ResponseVpnConnection

    Parameter

    Type

    Description

    id

    String
    • Specifies a VPN connection ID.
    • The value is a UUID containing 36 characters.

    name

    String
    • Specifies the name of a VPN connection.
    • The value is a string of 1 to 64 characters, which can contain digits, letters, underscores (_), hyphens (-), and periods (.).

    status

    String
    • Specifies the status of the VPN connection.
    • Value range:

      ERROR: abnormal

      ACTIVE: normal

      DOWN: not connected

      PENDING_CREATE: creating

      PENDING_UPDATE: updating

      PENDING_DELETE: deleting

      FREEZED: frozen

      UNKNOWN: unknown

    vgw_id

    String
    • Specifies a VPN gateway ID.
    • The value is a UUID containing 36 characters.

    vgw_ip

    String
    • Specifies an EIP ID or private IP address of the VPN gateway.
    • The value is a UUID containing 36 characters or an IPv4 address in dotted decimal notation (for example, 192.168.45.7).

    style

    String
    • Specifies the connection mode.
    • Value range:

      POLICY: policy-based mode

      STATIC: static routing mode

      BGP: BGP routing mode

      POLICY-TEMPLATE: policy template mode

    cgw_id

    String
    • Specifies a customer gateway ID.
    • The value is a UUID containing 36 characters.

    peer_subnets

    Array of String

    Specifies an IPv4 customer subnet. This parameter is not returned when attachment_type of the VPN gateway is set to ER and style is set to BGP or POLICY or when the IP protocol version of the VPN gateway is IPv6.

    peer_subnets_v6

    Array of String

    Specifies an IPv6 customer subnet. This parameter is not returned when attachment_type of the VPN gateway is set to ER and style is set to BGP or POLICY or when the IP protocol version of the VPN gateway is IPv4.

    tunnel_local_address

    String

    Specifies the tunnel interface address configured on the VPN gateway in route-based mode. This parameter is valid only when style is STATIC or BGP.

    tunnel_peer_address

    String

    Specifies the tunnel interface address configured on the customer gateway device in route-based mode. This parameter is valid only when style is STATIC or BGP.

    enable_nqa

    Boolean
    • Specifies whether NQA is enabled. This parameter is returned only when style is STATIC.
    • The value can be true or false.

    policy_rules

    Array of PolicyRule objects

    Specifies IPv4 policy rules, which are returned only when style is set to POLICY and ip_version of the VPN gateway is set to ipv4.

    policy_rules_v6

    Array of PolicyRule objects

    Specifies IPv6 policy rules, which are returned only when style is set to POLICY and ip_version of the VPN gateway is set to ipv6.

    ikepolicy

    IkePolicy object

    Specifies the IKE policy object.

    ipsecpolicy

    IpsecPolicy object

    Specifies the IPsec policy object.

    created_at

    String
    • Specifies the time when the VPN connection is created.
    • The UTC time format is yyyy-MM-ddTHH:mm:ssZ.

    updated_at

    String
    • Specifies the last update time.
    • The UTC time format is yyyy-MM-ddTHH:mm:ssZ.

    enterprise_project_id

    String
    • Specifies an enterprise project ID.
    • The value is a UUID containing 36 characters. The value must be the same as the enterprise project ID of the VPN gateway specified by vgw_id.

    connection_monitor_id

    String
    • Specifies the ID of a VPN connection monitor. This parameter is available only when a connection monitor is created for a VPN connection.
    • The value is a UUID containing 36 characters.

    ha_role

    String
    • For a VPN gateway in active-standby mode, master indicates the active connection, and slave indicates the standby connection. For a VPN gateway in active-active mode, the value of ha_role can only be master.
    • The default value is master.

    tags

    Array of VpnResourceTag objects

    Specifies a tag list.
    Table 5 PolicyRule

    Parameter

    Type

    Description

    rule_index

    Integer
    • Specifies a rule ID.
    • The value ranges from 0 to 50.

    source

    String

    Specifies a source CIDR block.

    destination

    Array of String

    Specifies a destination CIDR block. An example IPv4 CIDR block is 192.168.52.0/24. An example IPv6 CIDR block is 16af:cacc:1097::/48. A maximum of 50 destination CIDR blocks can be returned for each policy rule.
    Table 6 IkePolicy

    Parameter

    Type

    Description

    ike_version

    String
    • Specifies the IKE version.
    • The value can be v1 or v2.

    phase1_negotiation_mode

    String
    • Specifies the negotiation mode. This parameter is available only when the IKE version is v1.
    • Value range:
      • main: ensures high security during negotiation.
      • aggressive: ensures fast negotiation and a high negotiation success rate.

    authentication_algorithm

    String
    • Specifies an authentication algorithm.
    • The value can be sm3, sha2-512, sha2-384, sha2-256, sha1, or md5.

    encryption_algorithm

    String
    • Specifies an encryption algorithm.
    • The value can be sm4, aes-256-gcm-16, aes-128-gcm-16, aes-256, aes-192, aes-128, or 3des.

    dh_group

    String
    • Specifies the DH group used for key exchange in phase 1. This parameter is not available when flavor is set to GM for the VPN gateway.
    • The value can be group1, group2, group5, group14, group15, group16, group19, group20, or group21.

    authentication_method

    String
    • Specifies the authentication method used during IKE negotiation.
    • Value range:

      pre-share: pre-shared key

      digital-envelope-v2: SM digital envelope

    lifetime_seconds

    Integer
    • Specifies the SA lifetime. When the lifetime expires, an IKE SA is automatically updated.
    • The value ranges from 60 to 604800, in seconds.

    local_id_type

    String
    • Specifies the local ID type. This parameter is not available when flavor is set to GM for the VPN gateway.
    • Value range:
      • ip
      • fqdn

    local_id

    String

    Specifies the local ID. When local_id_type is set to ip, the VPN gateway IP address corresponding to the VPN connection is returned. When local_id_type is set to fqdn, the local ID specified during VPN connection creation or update is returned.

    This parameter is not available when flavor is set to GM for the VPN gateway.

    peer_id_type

    String
    • Specifies the peer ID type. This parameter is not available when flavor is set to GM for the VPN gateway.
    • Value range:
      • ip
      • fqdn

    peer_id

    String

    Specifies the peer ID. When peer_id_type is set to ip, the IP address of the customer gateway is returned. When peer_id_type is set to fqdn, the peer ID specified during VPN connection creation or update is returned.

    This parameter is not available when flavor is set to GM for the VPN gateway.

    dpd

    Dpd object

    Specifies the DPD object.
    Table 7 Dpd

    Parameter

    Type

    Description

    timeout

    Integer
    • Specifies the interval for retransmitting DPD packets.
    • The value ranges from 2 to 60, in seconds.

    interval

    Integer
    • Specifies the DPD idle timeout period.
    • The value ranges from 10 to 3600, in seconds.

    msg

    String
    • Specifies the format of DPD packets.
    • Value range:

      seq-hash-notify: indicates that the payload of DPD packets is in the sequence of hash-notify.

      seq-notify-hash: indicates that the payload of DPD packets is in the sequence of notify-hash.
    Table 8 IpsecPolicy

    Parameter

    Type

    Description

    authentication_algorithm

    String
    • Specifies an authentication algorithm.
    • The value can be sm3, sha2-512, sha2-384, sha2-256, sha1, or md5.

    encryption_algorithm

    String
    • Specifies an encryption algorithm.
    • The value can be sm4, aes-256-gcm-16, aes-128-gcm-16, aes-256, aes-192, aes-128, or 3des.

    pfs

    String
    • Specifies the DH key group used by PFS. This parameter is not available when flavor is set to GM for the VPN gateway.
    • The value can be group1, group2, group5, group14, group15, group16, group19, group20, group21, or disable.

    transform_protocol

    String
    • Specifies the transfer protocol.
    • Value range:

      esp: encapsulating security payload protocol

    lifetime_seconds

    Integer
    • Specifies the lifetime of a tunnel established over an IPsec connection.
    • The value ranges from 30 to 604800, in seconds.

    encapsulation_mode

    String
    • Specifies the packet encapsulation mode.
    • Value range:

      tunnel: encapsulates packets in tunnel mode.
    Table 9 VpnResourceTag

    Parameter

    Type

    Description

    key

    String
    • Specifies a tag key.
    • The value is a string of 1 to 128 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).

    value

    String
    • Specifies a tag value.
    • The value is a string of 0 to 255 characters that can contain digits, letters, Spanish characters, Portuguese characters, spaces, and special characters (_ . : = + - @).
    Table 10 PageInfo

    Parameter

    Type

    Description

    next_marker

    String

    Specifies the marker of the next page. The value is the time when the last resource in the last query response was created.

    current_count

    Integer

    Specifies the number of resources in the list. If the value of current_count is less than the value of limit in the query request, the current page is the last page.
  • Example responses
    1. Response to the request for querying all VPN connections 
      {
    "vpn_connections": [{
            "id": "228a68f0-demo-a8df-va86-a9919a3ea3de",
            "name": "vpn-56ea",
            "status": "DOWN",
            "vgw_id": "ba90819b-demo-a8df-va86-3a01622856a5",
            "vgw_ip": "3ea3b006-demo-a8df-va86-ae180ae07885",
            "style": "STATIC",
            "cgw_id": "537d9c26-demo-a8df-va86-99364a410f00",
            "peer_subnets": [
                "192.168.1.0/24"
            ],
            "tunnel_local_address": "169.254.149.2/30",
            "tunnel_peer_address": "169.254.149.1/30",
            "enable_nqa": true,
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 86400,
                "local_id_type": "ip",
                "local_id": "10.1.1.216",
                "peer_id_type": "ip",
                "peer_id": "10.0.1.67",
                "dpd": {
                    "timeout": 15,
                    "interval": 30,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-11T13:59:59.633Z",
            "updated_at": "2022-12-11T13:59:59.633Z",
            "enterprise_project_id": "0"
        },
        {
            "id": "a4df33ca-demo-a8df-va86-410a7dd6973f",
            "name": "vpn-15ea",
            "status": "DOWN",
            "vgw_id": "02217fb1-demo-a8df-va86-806ea291a8f2",
            "vgw_ip": "f5acac2c-demo-a8df-va86-72b819a5f525",
            "style": "POLICY",
            "cgw_id": "10a4496f-demo-a8df-va86-7510f4b2af33",
            "tunnel_local_address": "169.254.77.169/30",
            "tunnel_peer_address": "169.254.77.170/30",
            "policy_rules": [{
                "rule_index": 1,
                "source": "10.0.0.0/24",
                "destination": [
                    "192.168.44.0/24"
                ]
            }],
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 3600,
                "local_id_type": "ip",
                "local_id": "88.***.***.167",
                "peer_id_type": "ip",
                "peer_id": "10.***.***.21",
                "dpd": {
                    "interval": 30,
                    "timeout": 15,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-09T07:24:27.674Z",
            "updated_at": "2022-12-09T07:24:27.674Z",
            "enterprise_project_id": "0",
            "ha_role":"master"
        }
    ],
    "page_info": {
        "next_marker": "2022-12-09T07:24:27.674Z",
        "current_count": 2
    },
    "request_id": "1d94a4e8-fdc2-7bfd-943e-19bfa9b234ac",
    "total_count": 2
}
    2. Response to the request for querying VPN connections with a specified vgw_ip 
      {
    "vpn_connections": [
        {
            "id": "8fa335dd-demo-a8df-va86-78bb55a8bb04",
            "name": "vpn-2acd",
            "status": "DOWN",
            "vgw_id": "02217fb1-demo-a8df-va86-806ea291a8f2",
            "vgw_ip": "f5acac2c-demo-a8df-va86-72b819a5f525",
            "style": "STATIC",
            "cgw_id": "eba04567-demo-a8df-va86-5b0352f89af0",
            "peer_subnets": [
                "192.168.44.0/24"
            ],
            "tunnel_local_address": "169.254.58.225/30",
            "tunnel_peer_address": "169.254.58.226/30",
            "enable_nqa": false,
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 3600,
                "local_id_type": "ip",
                "local_id": "88.***.***.167",
                "peer_id_type": "ip",
                "peer_id": "10.***.***.9",
                "dpd": {
                    "timeout": 15,
                    "interval": 30,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-11T14:24:25.115Z",
            "updated_at": "2022-12-11T14:24:25.115Z",
            "enterprise_project_id": "0"
        },
        {
            "id": "a4df33ca-demo-a8df-va86-410a7dd6973f",
            "name": "vpn-15ea",
            "status": "DOWN",
            "vgw_id": "02217fb1-demo-a8df-va86-806ea291a8f2",
            "vgw_ip": "f5acac2c-demo-a8df-va86-72b819a5f525",
            "style": "POLICY",
            "cgw_id": "10a4496f-demo-a8df-va86-7510f4b2af33",
            "tunnel_local_address": "169.254.77.169/30",
            "tunnel_peer_address": "169.254.77.170/30",
            "policy_rules": [
                {
                    "rule_index": 1,
                    "source": "10.0.0.0/24",
                    "destination": [
                        "192.168.44.0/24"
                    ]
                }
            ],
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 3600,
                "local_id_type": "ip",
                "local_id": "88.***.***.167",
                "peer_id_type": "ip",
                "peer_id": "10.***.***.21",
                "dpd": {
                    "interval": 30,
                    "timeout": 15,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-11T13:59:59.633Z",
            "updated_at": "2022-12-11T13:59:59.633Z",
            "enterprise_project_id": "0",
            "ha_role":"master"
        }
    ],
    "page_info": {
        "next_marker": "2022-12-11T13:59:59.633Z",
        "current_count": 2
    },
    "request_id": "1d94a4e8-fdc2-7bfd-943e-19bfa9b234ac",
    "total_count": 12
}
    3. Response to the request for querying VPN connections of a specified VPN gateway instance 
      {
    "vpn_connections": [
        {
            "id": "8fa335dd-demo-a8df-va86-78bb55a8bb04",
            "name": "vpn-2acd",
            "status": "DOWN",
            "vgw_id": "02217fb1-demo-a8df-va86-806ea291a8f2",
            "vgw_ip": "f5acac2c-demo-a8df-va86-72b819a5f525",
            "style": "STATIC",
            "cgw_id": "eba04567-demo-a8df-va86-5b0352f89af0",
            "peer_subnets": [
                "192.168.44.0/24"
            ],
            "tunnel_local_address": "169.254.58.225/30",
            "tunnel_peer_address": "169.254.58.226/30",
            "enable_nqa": false,
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 3600,
                "local_id_type": "ip",
                "local_id": "88.***.***.167",
                "peer_id_type": "ip",
                "peer_id": "10.***.***.9",
                "dpd": {
                    "timeout": 15,
                    "interval": 30,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-11T14:24:25.115Z",
            "updated_at": "2022-12-11T14:24:25.115Z",
            "enterprise_project_id": "0",
            "ha_role":"master"
        },
        {
            "id": "a4df33ca-demo-a8df-va86-410a7dd6973f",
            "name": "vpn-15ea",
            "status": "DOWN",
            "vgw_id": "02217fb1-demo-a8df-va86-806ea291a8f2",
            "vgw_ip": "f5acac2c-demo-a8df-va86-72b819a5f525",
            "style": "POLICY",
            "cgw_id": "10a4496f-demo-a8df-va86-7510f4b2af33",
            "tunnel_local_address": "169.254.77.169/30",
            "tunnel_peer_address": "169.254.77.170/30",
            "policy_rules": [
                {
                    "rule_index": 1,
                    "source": "10.0.0.0/24",
                    "destination": [
                        "192.168.44.0/24"
                    ]
                }
            ],
            "ikepolicy": {
                "ike_version": "v2",
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "dh_group": "group15",
                "authentication_method": "pre-share",
                "lifetime_seconds": 3600,
                "local_id_type": "ip",
                "local_id": "88.***.***.167",
                "peer_id_type": "ip",
                "peer_id": "10.***.***.21",
                "dpd": {
                    "interval": 30,
                    "timeout": 15,
                    "msg": "seq-hash-notify"
                }
            },
            "ipsecpolicy": {
                "authentication_algorithm": "sha2-256",
                "encryption_algorithm": "aes-128",
                "pfs": "group15",
                "transform_protocol": "esp",
                "lifetime_seconds": 3600,
                "encapsulation_mode": "tunnel"
            },
            "created_at": "2022-12-11T13:59:59.633Z",
            "updated_at": "2022-12-11T13:59:59.633Z",
            "enterprise_project_id": "0",
            "ha_role":"master"
        }
    ],
    "page_info": {
        "next_marker": "2022-12-11T13:59:59.633Z",
        "current_count": 2
    },
    "request_id": "1d94a4e8-fdc2-7bfd-943e-19bfa9b234ac",
    "total_count": 12
}

Status Codes

For details, see Status Codes.

Parent topic: VPN Connection