IPsec VPN tunnels
IPsec connects your CloudSigma networks to another site. Configure complementary peer identities, security settings and protected networks at both ends.
Read capabilities
GET /virtual_routers/{uuid}/ipsec/capabilities/ returns supported native IKE/ESP choices allowed
for this router and subscription.
curl --fail-with-body --user "$CS_USER" -H 'Accept: application/json' \
"$API_URL/virtual_routers/$VR_UUID/ipsec/capabilities/"
Use offered ike_versions, ike_proposals, esp_proposals and lifetime defaults. An
unavailable catalogue returns 503 IPSEC_CAPABILITIES_UNAVAILABLE.
Creating a policy-based tunnel
Send this body to POST /virtual_routers/{uuid}/action/?do=add_ipsec_tunnel:
{
"name": "office-link",
"peer": "198.51.100.20",
"local_identity": "203.0.113.10",
"remote_identity": "198.51.100.20",
"local_networks": [
"192.168.10.0/24"
],
"remote_networks": [
"192.168.20.0/24"
],
"pre_shared_key": "<replace-with-a-unique-secret>",
"active": true,
"start_action": "start"
}
Replace addresses and the secret. Local identity must match the primary WAN; remote identity must match the peer. Each network array contains exactly one network. Names use 3–64 characters beginning with a letter, followed by letters, digits, dots, underscores or hyphens. Keys are 12–256 characters without control characters.
curl --fail-with-body --user "$CS_USER" -H 'Content-Type: application/json' \
-X POST --data-binary @ipsec-tunnel.json \
"$API_URL/virtual_routers/$VR_UUID/action/?do=add_ipsec_tunnel"
Start actions are start and trap. A new scoped tunnel without security uses IKEv2
AES256/SHA256/modp2048 with 28800/3600-second IKE/child lifetimes. Obtain target capabilities before
selecting explicit native security.
Native security
{
"ike_version": "2",
"ike_proposals": [
"aes128-sha256-modp2048"
],
"esp_proposals": [
"aes128-sha256-modp2048"
],
"ike_lifetime": 14400,
"child_lifetime": 1800
}
This is the object shape, not a guaranteed allowed catalogue. Proposal arrays form a negotiation set, not a guaranteed priority order. Lifetimes are non-negative integer seconds subject to native validation.
Editing and deleting
To edit security or the start action without resubmitting the key, use do=edit_ipsec_tunnel:
{
"name": "office-link",
"security": {
"ike_version": "2",
"ike_proposals": [
"aes128-sha256-modp2048"
],
"esp_proposals": [
"aes128-sha256-modp2048"
],
"ike_lifetime": 14400,
"child_lifetime": 1800
},
"start_action": "start"
}
This preserves the stored key, tunnel identity and sibling configuration. It does not change peer/selectors/key. The add action can update the same named tunnel for broader edits and requires the key; omitting security preserves an existing native selection.
Remove one tunnel with {"name": "office-link"} and do=remove_ipsec_tunnel. Wait for sync
after each action.
Route-based tunnels
For a VTI pair, replace the two network arrays in the add request with:
{
"local_networks": [
"10.254.0.1/30"
],
"remote_networks": [
"10.254.0.2/30"
]
}
These are distinct host endpoints on one point-to-point subnet. Preserve host bits and reverse the
endpoints at the other router. No extra top-level mode field is accepted.
Add a route for the remote LAN, such as 192.168.20.0/24 via 10.254.0.2. Configure the return
route through 10.254.0.1 at the peer.
Runtime status
GET /virtual_routers/{uuid}/ipsec/status/
curl --fail-with-body --user "$CS_USER" -H 'Accept: application/json' \
"$API_URL/virtual_routers/$VR_UUID/ipsec/status/"
Signal |
Meaning |
|---|---|
|
Desired configuration applied |
|
IKE establishment |
|
Encrypted child SA installation |
|
Packet/byte counts for the current SA |
|
Observation availability and freshness |
Tunnel |
Administrative/runtime state |
IKE can be established without an installed ESP child SA. Unavailable/stale observations mean unknown, not healthy. Counters may reset on rekey and are not lifetime billing totals. This endpoint has no durable last-change history.
Schema
Scoped add field |
Description |
|---|---|
|
Managed tunnel name |
|
Remote public address |
|
Primary WAN address |
|
Peer address |
|
One protected local network or local VTI endpoint |
|
One protected remote network or peer VTI endpoint |
|
Write-only shared secret |
|
Optional, defaults to true |
|
Optional |
|
Optional native IKE/ESP settings |
The full GET representation stores tunnels in configuration.vpn.tunnels using issued UUIDs,
tunnel_name, enabled state, peer, phase settings and optional native_security. Do not insert
scoped add bodies directly into that array. Prefer scoped actions and preserve returned aggregate
fields during unrelated Saves.
Verify the tunnel
Wait for sync, inspect IKE and ESP separately, then send real traffic and confirm counters increase in both directions. For VTI, verify routes and the return path. A saved active flag or established IKE alone does not prove payload traffic. Security changes can renegotiate and interrupt the tunnel.