19. Network Gateways

Network gateways connect SDN Private Networks to external IP networks. Gateways have VPN and NAT functionalities that can be enabled either separately or at the same time. The VPN functionality offers a way to establish encrypted connections using site-to-site IPSec VPN connections between SDN Private Networks and remote networks. The NAT gateway functionality enables outbound Internet connections from Cloud Servers in SDN Private Networks.

The network gateway service is attached to an SDN router. It can be utilized by one or more SDN private networks attached to the same router. For traffic to land on the network gateway your servers must have the SDN router as their next hop for any destinations you wish to route through the network gateway service.

Available features

Feature	Description
nat	NAT gateway is a Network Address Translation (NAT) service that offers a way for cloud servers in SDN private networks to connect to the Internet through the public IP assigned to the network gateway service
vpn	VPN gateway is a Virtual Private Network (VPN) service used to establish an encrypted network connection when using public networks

List plans

Returns a list of available gateway plans.

Request

GET /1.3/gateway/plans HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "name": "advanced",
    "per_gateway_bandwidth_mbps": 10000,
    "per_gateway_max_connections": 100000,
    "server_number": 2,
    "supported_features": [
        "nat",
        "vpn"
    ],
    "vpn_tunnel_amount": 10
  },
  {
    "name": "development",
    "per_gateway_bandwidth_mbps": 10,
    "per_gateway_max_connections": 10000,
    "server_number": 1,
    "supported_features": [
        "nat"
    ],
    "vpn_tunnel_amount": 0
  },
  {
    "name": "production",
    "per_gateway_bandwidth_mbps": 1000,
    "per_gateway_max_connections": 50000,
    "server_number": 2,
    "supported_features": [
        "nat",
        "vpn"
    ],
    "vpn_tunnel_amount": 2
  },
  {
    "name": "standard",
    "per_gateway_bandwidth_mbps": 500,
    "per_gateway_max_connections": 20000,
    "server_number": 2,
    "supported_features": [
        "nat"
    ],
    "vpn_tunnel_amount": 0
  }
]

Get plan details

Returns gateway plan details by given {name}.

Request

GET /1.3/gateway/plans/{name} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "name": "advanced",
  "per_gateway_bandwidth_mbps": 10000,
  "per_gateway_max_connections": 100000,
  "server_number": 2,
  "supported_features": [
      "nat",
      "vpn"
  ],
  "vpn_tunnel_amount": 10
}

List services

Returns a list of network gateway services.

Request

GET /1.3/gateway HTTP/1.1

Query parameters

Attribute	Accepted value	Default value	Required	Description
limit	0-100	10	no	Number of entries to receive at most.
offset	>= 0	0	no	Offset for retrieved results.
label	String representation of a label.		no	Filter by label. See labels usage.

Normal response

HTTP/1.1 200 OK

[
  {
    "addresses": [
      {
        "address": "100.127.0.241",
        "name": "public-ip-1"
      }
    ],
    "configured_status": "started",
    "created_at": "2022-12-01T09:04:08.529138Z",
    "features": [
      "nat", "vpn"
    ],
    "connections": [
      {
        "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
        "name": "example-connection",
        "type": "ipsec",
        "local_routes": [
          {
            "name": "upcloud-example-route",
            "type": "static",
            "static_network": "10.0.0.0/24"
          }
        ],
        "remote_routes": [
          {
            "name": "remote-example-route",
            "type": "static",
            "static_network": "10.0.1.0/24"
          }
        ],
        "tunnels": [
          {
            "local_address": {
              "name": "public-ip-1"
            },
            "name": "example-tunnel-1",
            "uuid": "1085d477-8d8f-4c97-9bef-731933187777",
            "remote_address": {
              "address": "100.10.0.111"
            },
            "ipsec": {
              "authentication": {
                  "authentication": "psk"
              },
              "child_rekey_time": 1440,
              "dpd_delay": 30,
              "dpd_timeout": 120,
              "ike_lifetime": 86400,
              "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
              "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
              "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
              "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
              "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
              "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
              "rekey_time": 14400
            },
            "tunnel_healthy": true,
            "tunnel_up": true,
            "tunnel_internal_ip": "169.254.17.1",
            "internal_peer_ping_interval": 0,
            "operational_state": "established",
            "created_at": "2022-12-01T09:04:08.529138Z",
            "updated_at": "2022-12-01T19:04:08.529138Z"
          }
        ],
        "created_at": "2022-12-01T09:04:08.529138Z",
        "updated_at": "2022-12-01T19:04:08.529138Z"
      }
    ],
    "name": "example-gateway",
    "operational_state": "running",
    "plan": "production",
    "routers": [
      {
        "created_at": "2022-12-01T09:04:08.529138Z",
        "uuid": "1085d477-8d8f-4c97-9bef-731933187538"
      }
    ],
    "labels": [
      {
        "key":"env",
        "value":"testing"
      }
    ],
    "automatic_tunnel_internal_ip_allocation": true,
    "updated_at": "2022-12-01T19:04:08.529138Z",
    "uuid": "10c153e0-12e4-4dea-8748-4f34850ff55d",
    "zone": "fi-hel1"
  }
]

Notes:

• {connections} are only available for VPN gateways. Please see connections for more.
• {authentication} PSK (Pre-Shared Key) value is not readable after it's creation. Please see IPSec authentication for more.
• Please see service configured statuses and operational states description.

Label

A label is structured as K/V pair with both the key and value as strings. Label Key (printable ASCII, range 0x20-0x7E except must not start with an underscore, 2-32 characters) Label Value (0-255 characters)

Get service details

Returns network gateway service by given {service_uuid}.

Request

GET /1.3/gateway/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "addresses": [
    {
      "address": "100.127.0.241",
      "name": "public-ip-1"
    }
  ],
  "configured_status": "started",
  "created_at": "2022-12-01T09:04:08.529138Z",
  "features": [
    "nat", "vpn"
  ],
  "connections": [
    {
      "name": "example-connection",
      "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
      "type": "ipsec",
      "local_routes": [
        {
          "name": "upcloud-example-route",
          "type": "static",
          "static_network": "10.0.0.0/24"
        }
      ],
      "remote_routes": [
        {
          "name": "remote-example-route",
          "type": "static",
          "static_network": "10.0.1.0/24"
        }
      ],
      "tunnels": [
        {
          "local_address": {
            "name": "public-ip-1"
          },
          "name": "example-tunnel-1",
          "uuid": "1085d477-8d8f-4c97-9bef-731933187777",
          "remote_address": {
            "address": "100.10.0.111"
          },
          "ipsec": {
            "authentication": {
                "authentication": "psk"
            },
            "child_rekey_time": 1440,
            "dpd_delay": 30,
            "dpd_timeout": 120,
            "ike_lifetime": 86400,
            "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
            "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
            "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
            "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
            "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
            "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
            "rekey_time": 14400
          },
          "tunnel_healthy": true,
          "tunnel_up": true,
          "tunnel_internal_ip": "169.254.17.1",
          "internal_peer_ping_interval": 0,
          "operational_state": "established",
          "created_at": "2022-12-01T09:04:08.529138Z",
          "updated_at": "2022-12-01T19:04:08.529138Z"
        }
      ],
      "created_at": "2022-12-01T09:04:08.529138Z",
      "updated_at": "2022-12-01T19:04:08.529138Z"
    }
  ],
  "name": "example-gateway",
  "operational_state": "running",
  "plan": "production",
  "routers": [
    {
      "created_at": "2022-12-01T09:04:08.529138Z",
      "uuid": "1085d477-8d8f-4c97-9bef-731933187538"
    }
  ],
  "labels": [
    {
      "key":"env",
      "value":"testing"
    }
  ],
  "automatic_tunnel_internal_ip_allocation": true,
  "updated_at": "2022-12-01T19:04:08.529138Z",
  "uuid": "10c153e0-12e4-4dea-8748-4f34850ff55d",
  "zone": "fi-hel1"
}

Notes:

• {connections} are only available for VPN gateways. Please see connections for more.
• {authentication} PSK (Pre-Shared Key) value is not readable after it's creation. Please see IPSec authentication for more.
• Please see service configured statuses and operational states description.

Create service

Creates a new network gateway service.

Request

POST /1.3/gateway HTTP/1.1

{
  "name": "example-gateway",
  "zone": "fi-hel1",
  "features": [
    "nat", "vpn"
  ],
  "plan": "production",
  "routers": [
    {
      "uuid": "1085d477-8d8f-4c97-9bef-731933187538"
    }
  ],
  "addresses": [
    {
      "name": "my-public-ip"
    }
  ],
  "connections": [
    {
      "name": "example-connection",
      "type": "ipsec",
      "local_routes": [
        {
          "name": "upcloud-example-route",
          "type": "static",
          "static_network": "10.0.0.0/24"
        }
      ],
      "remote_routes": [
        {
          "name": "remote-example-route",
          "type": "static",
          "static_network": "10.0.1.0/24"
        }
      ],
      "tunnels": [
        {
          "name": "example-tunnel-1",
          "local_address": {
            "name": "public-ip-1"
          },
          "remote_address": {
            "address": "100.10.0.111"
          },
          "ipsec": {
            "authentication": {
                "authentication": "psk",
                "psk": "{your PSK}"
            }
          },
          "tunnel_internal_ip": "169.254.17.1",
          "internal_peer_ping_interval": 5
        }
      ]
    }
  ],
  "labels": [
    {
      "key":"env",
      "value":"testing"
    }
  ],
  "configured_status": "started",
  "automatic_tunnel_internal_ip_allocation": false
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	The name of the service must be unique within customer account.
features	An array of 1 or more gateway features.	yes	See Available features for supported features.
zone	A valid zone identifier, e.g. fi-hel1	yes	Zone in which the service will be hosted, e.g. fi-hel1. Only public zones are supported currently.
plan	A valid plan name, e.g. production	no	Plan which the service will have, see plans. Default plan only supports NAT feature.
routers	An array of 1 router object.	yes	Attached Routers from where traffic is routed towards the network gateway service.
configured_status	started / stopped	yes	Service status managed by the customer.
connections	An array of 1 or more connections	no	See create connections
addresses	An array of 1 address object.	no	Gateway public IP addresses.
labels	An array of 1 or more label	no	See Label
automatic_tunnel_internal_ip_allocation	true / false	no	Automatically assign tunnel internal IPs (true if omitted on creation).

NOTE: Only one router and one address per network gateway is currently supported.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
409 Conflict	DUPLICATE_RESOURCE	Service for router already exists.
400 Bad Request	INVALID_REQUEST	Duplicate address name.

Replace service

Replaces an existing network gateway service by given {service_uuid}

Request

PUT /1.3/gateway/{service_uuid} HTTP/1.1

{
  "name": "example-gateway",
  "configured_status": "started"
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	The name of the service must be unique within customer account.
configured_status	started / stopped	yes	Service status managed by the customer.
labels	An array of 1 or more label	no	See Label

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.
409 Conflict	DUPLICATE_RESOURCE	Service for router already exists.

Modify service

Modifies an existing network gateway service by given {service_uuid}.

Request

PATCH /1.3/gateway/{service_uuid} HTTP/1.1

{
  "name": "example-gateway",
  "configured_status": "started",
  "labels": [
    {
      "key": "env",
      "value": "testing"
    }
  ]
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	no	The name of the service must be unique within customer account.
configured_status	started / stopped	no	Service status managed by the customer.
labels	An array of 1 or more label	no	See Label
features	An array of 1 or more gateway features.	no	See Available features for supported features.
plan	A valid plan name, e.g. production	no	Plan which the service will have, see plans.
connections	An array of 1 or more connections	no	See create connections
automatic_tunnel_internal_ip_allocation	true / false	no	Automatically assign tunnel internal IPs.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.

Delete service

Deletes an existing network gateway service by given {service_uuid}.

Request

DELETE /1.3/gateway/{service_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.

Create service label

Creates a new label by given {service_uuid}.

Labels used for service filtering.

Service labels usage examples

Below are some examples of what certain GET requests might look like.

• exact match: GET /1.3/gateway?label=env%3Dstaging
• existence: GET /1.3/gateway?label=env
• multiple: GET /1.3/gateway?label=env&label=foo%3Dbar

POST /1.3/gateway/{service_uuid}/labels HTTP/1.1

{
    "key": "foo",
    "value": "bar"
}

Attributes

Attribute	Accepted value	Required	Description
key	2-32 printable ASCII characters (range 0x20-0x7E), must not start with _	yes	Represents the label identifier. The key is unique within a service.
value	0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z	yes	Represents the label value.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.

List service labels

Returns a list of available service labels by given {service_uuid}.

Request

GET /1.3/gateway/{service_uuid}/labels HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
    {
        "key": "env",
        "value": "staging"
    },
    {
        "key": "foo",
        "value": "bar"
    }
]

Get service label details

Returns label details by given {service_uuid} and {key}.

Request

GET /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
    "key": "env",
    "value": "staging"  
}

Modify service label

Modifies existing label by given {service_uuid} and {key}.

Request

PATCH /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

{
    "key": "env",
    "value": "production"
}

Attributes

Attribute	Accepted value	Required	Description
key	2-32 printable ASCII characters (range 0x20-0x7E), must not start with _	no	Represents the label identifier. The key is unique within a service.
value	0-255 characters, regexp pattern \A[\p{L}\p{N}\p{P}\p{S}\p{M}\p{Z}]*\z / null	no	Represents the label value.

Normal response

HTTP/1.1 200 OK

Delete service label

Deletes existing label by given {service_uuid} and {key}.

Request

DELETE /1.3/gateway/{service_uuid}/labels/{key} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	Resource not found.

Routers

List of router objects should be provided on service create and cannot be changed later.

Currently, only one router per network gateway is supported.

Attributes

Attribute	Accepted value	Required	Description
uuid	A valid router identifier in UUID format	yes	Router that will be attached to this network gateway service.

Addresses

List of address objects. Currently supports only one address. Address can be provided on service creation and cannot be changed later.

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	Public IP address name. Used for referencing vpn gateway tunnel {local_address}

Service configured status

The service configured status indicates the service's current intended status. Managed by the customer.

Status	Description
started	The service is running.
stopped	The service is stopped.

Service operational state

The service operational state indicates the service's current operational, effective state. Managed by the system.

State	Description
pending	Indicates newly created service or started reconfiguration.
setup-agent	Configuring management tool.
setup-link-network	Configuring the networking between router and gateway.
setup-server	Configuring gateway nodes.
setup-network	Configuring network.
setup-gw	Configuring gateway.
setup-dns	Updating DNS records.
checkup	Verifying the gateway is correctly configured and running.
running	Indicates service up and running.
delete-dns	Removing DNS records.
delete-network	Reconfiguring network.
delete-server	Deleting gateway nodes.
delete-link-network	Deleting the networking between router and gateway.
delete-service	Deleting the service.

List connections

Returns a list of network gateway connections.

Request

GET /1.3/gateway/{service_uuid}/connections HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "name": "example-connection",
    "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
    "type": "ipsec",
    "local_routes": [
      {
        "name": "upcloud-example-route",
        "type": "static",
        "static_network": "10.0.0.0/24"
      }
    ],
    "remote_routes": [
      {
        "name": "remote-example-route",
        "type": "static",
        "static_network": "10.0.1.0/24"
      }
    ],
    "tunnels": [
      {
        "local_address": {
          "name": "public-ip-1"
        },
        "name": "example-tunnel-1",
        "uuid": "1085d477-8d8f-4c97-9bef-731933187777",
        "remote_address": {
          "address": "100.10.0.111"
        },
        "ipsec": {
          "authentication": {
              "authentication": "psk"
          },
          "child_rekey_time": 1440,
          "dpd_delay": 30,
          "dpd_timeout": 120,
          "ike_lifetime": 86400,
          "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
          "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
          "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
          "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
          "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
          "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
          "rekey_time": 14400
        },
        "tunnel_healthy": true,
        "tunnel_up": true,
        "tunnel_internal_ip": "169.254.17.1",
        "internal_peer_ping_interval": 0,
        "operational_state": "established",
        "created_at": "2022-12-01T09:04:08.529138Z",
        "updated_at": "2022-12-01T19:04:08.529138Z"
      }
    ],
    "created_at": "2022-12-01T09:04:08.529138Z",
    "updated_at": "2022-12-01T19:04:08.529138Z"
  }
]

Notes:

• connection {local_routes} and {remote_routes} routes currently support only static type.

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.

Get connection details

Returns network gateway connection for {service_uuid} gateway by given {connection_uuid}.

Request

GET /1.3/gateway/{service_uuid}/connections/{connection_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "name": "example-connection",
  "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
  "type": "ipsec",
  "local_routes": [
    {
      "name": "upcloud-example-route",
      "type": "static",
      "static_network": "10.0.0.0/24"
    }
  ],
  "remote_routes": [
    {
      "name": "remote-example-route",
      "type": "static",
      "static_network": "10.0.1.0/24"
    }
  ],
  "tunnels": [
    {
      "local_address": {
        "name": "public-ip-1"
      },
      "name": "example-tunnel-1",
      "uuid": "1085d477-8d8f-4c97-9bef-731933187777",
      "remote_address": {
        "address": "100.10.0.111"
      },
      "ipsec": {
        "authentication": {
            "authentication": "psk"
        },
        "child_rekey_time": 1440,
        "dpd_delay": 30,
        "dpd_timeout": 120,
        "ike_lifetime": 86400,
        "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
        "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
        "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
        "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
        "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
        "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
        "rekey_time": 14400
      },
      "tunnel_healthy": true,
      "tunnel_up": true,
      "tunnel_internal_ip": "169.254.17.1",
      "internal_peer_ping_interval": 0,
      "operational_state": "established",
      "created_at": "2022-12-01T09:04:08.529138Z",
      "updated_at": "2022-12-01T19:04:08.529138Z"
    }
  ],
  "created_at": "2022-12-01T09:04:08.529138Z",
  "updated_at": "2022-12-01T19:04:08.529138Z"
}

Notes:

• connection {local_routes} and {remote_routes} routes currently support only static type.

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.

Create connection

Creates a new connection to network gateway.

Request

POST /1.3/gateway/{service_uuid}/connections HTTP/1.1

{
  "name": "example-connection",
  "type": "ipsec",
  "local_routes": [
    {
      "name": "upcloud-example-route",
      "type": "static",
      "static_network": "10.0.0.0/24"
    }
  ],
  "remote_routes": [
    {
      "name": "remote-example-route",
      "type": "static",
      "static_network": "10.0.1.0/24"
    }
  ],
  "tunnels": [
    {
      "name": "example-tunnel-1",
      "local_address": {
        "name": "public-ip-1"
      },
      "remote_address": {
        "address": "100.10.0.111"
      },
      "ipsec": {
        "authentication": {
            "authentication": "psk",
            "psk": "{your PSK}"
        }
      },
      "tunnel_internal_ip": "169.254.17.1",
      "internal_peer_ping_interval": 0
    }
  ]
}

Attributes

Attribute	Accepted value	Required	Description
uuid	Valid UUID	no	The uuid of the connection.
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	The name of the connection must be unique within gateway.
type	ipsec	yes	Currently only ipsec type connections are supported.
local_routes	An array of 1 or more local routes	no	Defining Upcloud side of networks to be routed. See routes.
remote_routes	An array of 1 or more remote routes	no	Defining remote peer networks to be routed. See routes.
tunnels	An array of 1 or more tunnels	no	See tunnels.

NOTE: Necessary to provide at least either one local_routes, remote_routes or tunnels to create connection.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
400 Bad Request	INVALID_REQUEST	Vpn feature is required for connections.
400 Bad Request	INVALID_REQUEST	Service with plan {plan_name} can have up to {plan_vpn_tunnel_amount} connections.
400 Bad Request	INVALID_REQUEST	Duplicate connection name.
400 Bad Request	INVALID_REQUEST	Unknown connection type.
400 Bad Request	INVALID_REQUEST	Invalid local route: {local_route}.
400 Bad Request	INVALID_REQUEST	Invalid remote route: {remote_route}.

Modify service

Modifies network gateway connection for {service_uuid} gateway by given {connection_uuid}.

Request

PATCH /1.3/gateway/{service_uuid}/connections/{connection_uuid} HTTP/1.1

{
  "local_routes": [
    {
      "name": "modified-routes",
      "type": "static",
      "static_network": "10.0.22.0/24"
    }
  ]
}

Attributes

Attribute	Accepted value	Required	Description
local_routes	An array of 1 or more local routes	no	Defining Upcloud side of networks to be routed. See routes.
remote_routes	An array of 1 or more remote routes	no	Defining remote peer networks to be routed. See routes.
tunnels	An array of 1 or more tunnels	no	See tunnels.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	Service with provided UUID not found.

Delete connection

Deletes network gateway connection for {service_uuid} with name {connection_uuid}.

Request

DELETE /1.3/gateway/{service_uuid}/connections/{connection_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.

Routes

List of route objects for local_routes and remote_routes. local_routes are used for defining Upcloud side of network to be routed.
remote_routes are used for defining remote peer network where traffic will be routed to.
Only type static routes are supported currently.

Attributes

Attribute	Accepted value	Required	Description
type	static	yes	Routing type. Only type static routes are supported currently.
static_network	Valid IPv4 prefix prefix	yes	Destination prefix of the route.
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	Unique name for the route.

List tunnels

Returns a list of network gateway connection tunnels.

Request

GET /1.3/gateway/{service_uuid}/connections/{connection_uuid}/tunnels HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "local_address": {
      "name": "public-ip-1"
    },
    "name": "example-tunnel-1",
    "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
    "remote_address": {
      "address": "100.10.0.111"
    },
    "ipsec": {
      "authentication": {
          "authentication": "psk"
      },
      "child_rekey_time": 1440,
      "dpd_delay": 30,
      "dpd_timeout": 120,
      "ike_lifetime": 86400,
      "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
      "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
      "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
      "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
      "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
      "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
      "rekey_time": 14400
    },
    "tunnel_healthy": true,
    "tunnel_up": true,
    "tunnel_internal_ip": "169.254.17.1",
    "internal_peer_ping_interval": 0,
    "operational_state": "established",
    "created_at": "2022-12-01T09:04:08.529138Z",
    "updated_at": "2022-12-01T19:04:08.529138Z"
  }
]

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.

Get tunnel details

Returns network gateway connection tunnel by given {tunnel_uuid}.

Request

GET /1.3/gateway/{service_uuid}/connections/{connection_uuid}/tunnels/{tunnels_uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "local_address": {
    "name": "public-ip-1"
  },
  "name": "example-tunnel-1",
  "uuid": "1085d477-8d8f-4c97-9bef-731933187538",
  "remote_address": {
    "address": "100.10.0.111"
  },
  "ipsec": {
    "authentication": {
        "authentication": "psk"
    },
    "child_rekey_time": 1440,
    "dpd_delay": 30,
    "dpd_timeout": 120,
    "ike_lifetime": 86400,
    "phase1_algorithms": ["aes128gcm128", "aes256gcm128"],
    "phase1_dh_group_numbers": [14, 16, 18, 19, 20, 21],
    "phase1_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
    "phase2_algorithms": ["aes128gcm128", "aes256gcm128"],
    "phase2_dh_group_numbers": [14, 16, 18, 19, 20, 21],
    "phase2_integrity_algorithms": ["aes128gmac", "aes256gmac", "sha256", "sha384", "sha512"],
    "rekey_time": 14400
  },
  "tunnel_healthy": true,
  "tunnel_up": true,
  "tunnel_internal_ip": "169.254.17.1",
  "internal_peer_ping_interval": 0,
  "operational_state": "established",
  "created_at": "2022-12-01T09:04:08.529138Z",
  "updated_at": "2022-12-01T19:04:08.529138Z"
}

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.
404 Not Found	RESOURCE_NOT_FOUND	Tunnel not found.

Tunnel operational state

The tunnel operational state indicates the tunnel's current operational, effective state. Managed by the system.

State	Description
idle	Connection is idle.
connecting	Connection is being initiated.
established	Connection is fully established and operating.
destroying	Connection is being destroyed.
unknown	Connection is in an unknown state.

Tunnel health

{tunnel_up} is true if the tunnel is "up", that is an IPSec SA has been established, false otherwise.

{tunnel_healthy} is true if there haven't been "bad" log messages for the tunnel in last five minutes, false otherwise.

Create tunnel

Creates a new tunnel to network gateway connection.

Request

POST /1.3/gateway/{service_uuid}/connections/{connection_uuid}/tunnels HTTP/1.1

{
  "name": "example-tunnel-2",
  "local_address": {
    "name": "public-ip-1"
  },
  "remote_address": {
    "address": "100.10.0.111"
  },
  "ipsec": {
    "authentication": {
        "authentication": "psk",
        "psk": "{your PSK}"
    }
  },
  "tunnel_internal_ip": "169.254.17.1",
  "internal_peer_ping_interval": 0
}

Attributes

Attribute	Default value	Accepted value	Required	Description
uuid		Valid UUID	no	The uuid of the tunnel.
name		1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	The name of the tunnel must be unique within gateway.
local_address		Local address name object	yes	See local address.
remote_address		Remote address object	yes	See remote address.
ipsec		IPSec object	yes	See IPSec for more information.
tunnel_internal_ip	""	IP address or "" (unconfigured)	no	Tunnel link-local address (inside tunnel IPv4 address). Used for example by the tunnel internal pinger feature.
internal_peer_ping_interval	0	Peer ping interval in seconds	no	See description below in Tunnel internal IP and the pinger.

Tunnel internal IP and the pinger

{tunnel_internal_ip}, when not empty, must be the second or third address in a /30 network in the 169.254.17.0/24 range and must not overlap with any other network of an IP configured on the service.

As an example for 169.254.17.100/30 link-local network:

• Possible values for {tunnel_internal_ip} are "169.254.17.101" and "169.254.17.102".
• Whichever is configured would consider the another as the peer (which for instance the pinger, if enabled, would ping).
• Using either of the addresses mentioned above in any of the other tunnels under the same service as {tunnel_internal_ip} would not be possible because they reside inside the same network.

If the service {automatic_tunnel_internal_ip_allocation} is true the {tunnel_internal_ip} is automatically allocated and can't be explicitly assigned.

{internal_peer_ping_interval} must have a value of 0 (disabled) or an integer greater or equal to 5. When it is non-zero and {tunnel_internal_ip} is not "", ICMP echo requests ("pings") from this address at this interval are sent to the peer IP in the /30 network. This is useful primarily for enhanced tunnel liveness and failure detection.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.
400 Bad Request	INVALID_REQUEST	Duplicate tunnel name.
400 Bad Request	INVALID_REQUEST	Invalid local address: {local_address.name} not found in service.
400 Bad Request	INVALID_REQUEST	Invalid remote address.
400 Bad Request	INVALID_REQUEST	Unknown authentication type.

Modify tunnel

Modifies network gateway connection tunnel for {tunnel_uuid}.

Request

PATCH /1.3/gateway/{service_uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid} HTTP/1.1

{
  "remote_address": {
    "address": "100.10.0.222"
  }
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	no	The name of the tunnel must be unique within gateway.
local_address	Local address name object	no	See local address.
remote_address	Remote address object	no	See remote address.
ipsec	IPSec object	no	See IPSec for more information.
tunnel_internal_ip	IP address or "" (unconfigured)	no	Tunnel link-local address for the pinger.
internal_peer_ping_interval	Peer ping interval in seconds	no	Tunnel peer ping interval.

Normal response

HTTP/1.1 200 OK

Error response

HTTP status	Error code	Description
400 Bad Request	INVALID_REQUEST	Validation error.
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.
404 Not Found	RESOURCE_NOT_FOUND	Tunnel not found.

Delete tunnel

Deletes a tunnel under network gateway connection {connection_uuid} with uuid {tunnel_uuid}.

Request

DELETE /1.3/gateway/{service_uuid}/connections/{connection_uuid}/tunnels/{tunnel_uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	The resource you requested does not exist.
404 Not Found	RESOURCE_NOT_FOUND	Connection not found.
404 Not Found	RESOURCE_NOT_FOUND	Tunnel not found.

Local address

Public (UpCloud) endpoint IP address of this tunnel.

Attributes

Attribute	Accepted value	Required	Description
name	The name of gateway addresses address	yes	Upcloud gateway public IP address. See addresses.

Remote address

Remote public IP address of the tunnel, that is the other IPSec endpoint.

Attributes

Attribute	Accepted value	Required	Description
address	IPv4 address	yes	Remote peer address VPN will connect to. Must be global non-private unicast IP address.

IPSec

Tunnel IPSec configuration object.

Attributes

Attribute	Default values	Accepted value	Required	Description
authentication	-	IPSec authentication object	yes	Required when creating a tunnel. See IPSec authentication.
phase1_algorithms	[aes128, aes256, aes128gcm128, aes256gcm128]	[aes128gcm16, aes128gcm128, aes192gcm16, aes192gcm128, aes256gcm16, aes256gcm128, aes128, aes192', aes256]	no	List of Phase 1: Proposal algorithms.
phase2_algorithms	[aes128,aes256,aes128gcm128, aes256gcm128]	[aes128gcm16, aes128gcm128, aes192gcm16, aes192gcm128, aes256gcm16, aes256gcm128, aes128, aes192', aes256]	no	List of Phase 2: Security Association algorithms.
phase1_integrity_algorithms	[sha256, sha384, sha512]	[aes128gmac, aes256gmac, sha1, sha256, sha384, sha512]	no	List of Phase 1 integrity algorithms.
phase2_integrity_algorithms	[sha256, sha384, sha512]	[aes128gmac, aes256gmac, sha1, sha256, sha384, sha512]	no	List of Phase 2 integrity algorithms.
phase1_dh_group_numbers	[14, 16, 18, 19, 20, 21]	[2, 5, 14, 15, 16, 18, 19, 20, 21, 24]	no	List of Phase 1 Diffie-Hellman group numbers.
phase2_dh_group_numbers	[14, 16, 18, 19, 20, 21]	[2, 5, 14, 15, 16, 18, 19, 20, 21, 24]	no	List of Phase 2 Diffie-Hellman group numbers.
child_rekey_time	1440	number (0 - 2147483647)	no	IKE child SA rekey time in seconds.
rekey_time	14400	number (0 - 2147483647)	no	IKE SA rekey time in seconds.
dpd_delay	30	number (0 - 2147483647)	no	Delay before sending Dead Peer Detection packets if no traffic is detected, in seconds.
dpd_timeout	120	number (0 - 2147483647)	no	Timeout period for DPD reply before considering the peer to be dead, in seconds.
ike_lifetime	86400	number (0 - 2147483647)	no	Maximum IKE SA lifetime in seconds.

IPSec authentication

Tunnel IPSec authentication object.

Attributes

Attribute	Accepted value	Required	Description
authentication	psk	yes	Authentication type. Only type static routes are supported currently.
psk	The PSK must be 8-64 characters in length. It cannot start with number zero (0). Alphanumeric characters, underscores (_) and periods (.) are allowed. Regexp pattern to validate is ^[a-zA-Z1-9_.][a-zA-Z0-9_.]+$.	no	The pre-shared key (PSK) value. Required when creating, can be omitted when modifying existing tunnel. The PSK value can not be viewed after creation, replace with new value to change it.

Get metrics

Returns metrics by given {service_uuid}.

Request

GET /1.3/gateway/{service_uuid}/metrics HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "gateways": [
    {
      "active_connections": 15,
      "created_at": "2024-01-11T13:16:05.161672Z",
      "name": "gateway1",
      "total_accepted_connections": 8773,
      "total_rejected_sessions": 3,
      "updated_at": "2024-01-17T10:25:13.393453Z"
    }
  ],
  "ipsec_metrics": {
    "ike_sas": [
      {
        "child_sas": [
          {
            "name": "example-connection/example-tunnel-1",
            "tunnel_id": 213,
            "unique_id": "389",
            "state": "installed",
            "spi_in": "c3d20761",
            "spi_out": "cec8f1bc",
            "bytes_in": 25537422,
            "bytes_out": 645540,
            "packets_in": 20353,
            "packets_out": 7685,
            "rekey_time": 1214,
            "life_time": 1445,
            "install_time": 139,
            "local_traffic_selectors": [
              "0.0.0.0/0",
              "::/0"
            ],
            "remote_traffic_selectors": [
              "0.0.0.0/0",
              "::/0"
            ],
            "created_at": "2024-01-11T13:19:10.077746Z",
            "updated_at": "2024-01-17T10:25:13.393453Z"
          }
        ],
        "created_at": "2024-01-11T13:18:55.056675Z",
        "established": 9286,
        "initator": true,
        "local_host": "100.127.0.241",
        "local_id": "100.127.0.241",
        "name": "example-connection/example-tunnel-1",
        "reauth_time": 0,
        "rekey_time": 4483,
        "remote_host": "100.10.0.111",
        "remote_id": "100.10.0.111",
        "operational_state": "established",
        "internal_state": "established",
        "tunnel_id": 213,
        "unique_id": "149",
        "updated_at": "2024-01-17T10:25:13.393453Z",
        "version": 2,
        "heuristic_state": {
          "tunnel_up": true,
          "tunnel_healthy": true,
          "last_down_message": "received AUTHENTICATION_FAILED notify error",
          "updated_at": "2024-01-17T10:25:13.393453Z",
          "last_down_message_updated_at": "2024-01-17T06:46:18.938719Z",
          "up_events": 5,
          "down_events": 4,
          "log_message_bad_events": 1
        }
      }
    ]
  }
}

Notes:

• gateways: contains a single-entry list of metrics for the NAT gateway.
• ike_sas: list of configured tunnels' IKE Security Associations (IKE SAs).
• child_sas: list of metrics for IKE SA related child Security Associations (child SAs).
• heuristic_state: health state and diagnostic information for an IKE SA or its predecessors.

Attributes

gateways attributes:

Attribute	Value	Description
name	1-64 characters	The Name of the object.
active_connections	>= 0	Current number of connections through the gateway.
total_accepted_connections	>= 0	Total number of accepted connections through the gateway.
total_rejected_connections	>= 0	Total number of rejected connections through the gateway.
created_at	datetime	Date and time when first metrics sample collected.
updated_at	datetime	Date and time when latest metrics sample collected.

ike_sas attributes:

Attribute	Value	Description
name	1-64 characters	The Name of the object, constructed from name of the connection and the tunnel.
tunnel_id	>= 0	Internal tunnel ID.
unique_id	>= 0	Internal unique ID.
operational_state	string	SA state. State names are the same as in tunnel operationa_state.
internal_state	string	Internal SA state.
reauth_time	>= 0	Remaining time until next IKE reauthentication, or zero if reauthentication is disabled.
rekey_time	>= 0	Remaining time until next IKE rekey in seconds.
life_time	>= 0	Remaining SA lifetime in seconds.
install_time	>= 0	Number of seconds since SA was installed.
established	>= 0	Number of seconds this SA has been operating.
initiator	boolean	True if this endpoint established the SA, false otherwise.
local_host	IP address	Address of the other endpoint of the SA.
local_id	string	Internal identifier of the other endpoint of the SA.
remote_host	IP address	Address of the other endpoint of the SA.
remote_id	string	Internal identifier of the other endpoint of the SA.
version	>= 1	IKE version.
created_at	datetime	Date and time when first metrics sample collected.
updated_at	datetime	Date and time when latest metrics sample collected.

child_sas attributes:

Attribute	Value	Description
name	1-64 characters	The Name of the object, constructed from name of the connection and the tunnel.
tunnel_id	>= 0	Internal tunnel ID.
unique_id	>= 0	Internal unique ID.
state	string	Child SA state.
spi_in	8 hexadecimal digits	Inbound IKE Security Parameter Index.
spi_out	8 hexadecimal digits	Outbound IKE Security Parameter Index.
bytes_in	>= 0	Total number of bytes received through IKE Child SA.
bytes_out	>= 0	Total number of bytes sent through IKE Child SA.
packets_in	>= 0	Total number of packets received through IKE Child SA.
packets_out	>= 0	Total number of packets sent through IKE Child SA.
rekey_time	>= 0	Remaining time until next IKE rekey in seconds.
life_time	>= 0	Remaining SA lifetime in seconds.
install_time	>= 0	Number of seconds since SA was installed.
local_traffic_selectors	list of networks	Local traffic selectors.
remote_traffic_selectors	list of networks	Remote traffic selectors.
created_at	datetime	Date and time when first metrics sample collected.
updated_at	datetime	Date and time when latest metrics sample collected.

heuristic_state attributes:

Attribute	Value	Description
tunnel_up	boolean	True if SA is established and tunnel is "up".
tunnel_healthy	boolean	True if no new {last_down_message}s have been seen in past 5 minutes.
last_down_message	string	Last log message heuristically considered to indicate the tunnel is unhealthy.
last_down_message_updated_at	datetime	Date and time when {last_down_message} was last updated.
up_events	>= 0	Number of seen tunnel up events for the connection-tunnel name.
down_events	>= 0	Number of seen tunnel down events for the connection-tunnel name.
log_message_bad_events	>= 0	Number of seen "bad" log messages for the connection-tunnel name.
updated_at	datetime	Date and time when {heuristic_state} was last changed.

SA internal state

The SA metrics internal state indicates the SA's current internal, effective state.

State	Description
uninitialized	Tunnel operational state hasn't been acquired yet.
created	IKE SA has been just created, but not yet initialized or responding.
connecting	Connection is being initiated.
established	Connection is fully established and operating.
rekeying	Connection is being rekeyed.
rekeyed	Connection rekeying has completed.
deleting	Connection is being deleted.
destroying	Connection is being destroyed.
unknown	Connection is in an unknown state.