VPN Tunnels

VPN tunnels are IPSec connections within a VPN connection that define the actual encrypted channel between endpoints. Each tunnel specifies local and remote addresses, IPSec configuration, and authentication settings.

GET/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels

List tunnels

Returns a list of tunnels for a VPN connection.

Request

GET

/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels

curl -X GET https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/connections/1085d477-8d8f-4c97-9bef-731933187538/tunnels \
  -u your_username:your_password

GET/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

Get tunnel details

Returns details of a specific tunnel including IPSec configuration and health status.

Tunnel operational states

State	Description
idle	Connection is idle
connecting	Connection is being initiated
established	Connection is fully established
destroying	Connection is being destroyed
unknown	Connection state is unknown

Request

GET

/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

curl -X GET https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/connections/1085d477-8d8f-4c97-9bef-731933187538/tunnels/1085d477-8d8f-4c97-9bef-731933187777 \
  -u your_username:your_password

POST/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels

Create tunnel

Creates a new IPSec tunnel for a VPN connection.

Attributes

Name
name
Type
string
Description
Tunnel name (1-64 chars). Must be unique within the gateway.
Name
local_address
Type
object
Description
Local address object with name referencing a gateway address.
Name
remote_address
Type
object
Description
Remote address object with address containing the peer IP.
Name
ipsec
Type
object
Description
IPSec configuration including authentication.
Name
tunnel_internal_ip
Type
string
Description
Tunnel link-local address for internal pinger (169.254.17.x/30).
Name
internal_peer_ping_interval
Type
integer
Description
Peer ping interval in seconds (0 = disabled, or >= 5).

IPSec authentication

Name
authentication
Type
string
Description
Authentication type. Currently only "psk" is supported.
Name
psk
Type
string
Description
Pre-shared key (8-64 chars). Required when creating.

Request

POST

/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels

curl -X POST https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/connections/1085d477-8d8f-4c97-9bef-731933187538/tunnels \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secondary-tunnel",
    "local_address": {
      "name": "public-ip-1"
    },
    "remote_address": {
      "address": "203.0.113.100"
    },
    "ipsec": {
      "authentication": {
        "authentication": "psk",
        "psk": "your-secure-pre-shared-key"
      }
    },
    "tunnel_internal_ip": "169.254.17.5",
    "internal_peer_ping_interval": 10
  }'

PATCH/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

Modify tunnel

Modifies an existing IPSec tunnel configuration.

Attributes

Name
name
Type
string
Description
Updated tunnel name.
Name
local_address
Type
object
Description
Updated local address.
Name
remote_address
Type
object
Description
Updated remote address.
Name
ipsec
Type
object
Description
Updated IPSec configuration.
Name
tunnel_internal_ip
Type
string
Description
Updated tunnel internal IP.
Name
internal_peer_ping_interval
Type
integer
Description
Updated ping interval.

Request

PATCH

/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

curl -X PATCH https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/connections/1085d477-8d8f-4c97-9bef-731933187538/tunnels/1085d477-8d8f-4c97-9bef-731933187777 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "remote_address": {
      "address": "203.0.113.200"
    }
  }'

DELETE/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

Delete tunnel

Deletes a tunnel from a VPN connection.

Request

DELETE

/1.3/gateway/{uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid}

curl -X DELETE https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/connections/1085d477-8d8f-4c97-9bef-731933187538/tunnels/1085d477-8d8f-4c97-9bef-731933187777 \
  -u your_username:your_password

GET/1.3/gateway/{uuid}/metrics

Get metrics

Returns metrics for a network gateway including NAT gateway statistics and IPSec tunnel metrics.

Response attributes

Gateway metrics:

active_connections: Current active NAT connections
total_accepted_connections: Total connections accepted
total_rejected_connections: Total connections rejected

IPSec metrics:

ike_sas: IKE Security Association information
child_sas: Child SA traffic statistics (bytes, packets)
heuristic_state: Tunnel health and diagnostic info

Request

GET

/1.3/gateway/{uuid}/metrics

curl -X GET https://api.upcloud.com/1.3/gateway/04b87f79-1a17-4f64-ad8e-33bd4c3f5c1b/metrics \
  -u your_username:your_password