Skip to content

Connect a Customer Router to the Astradial VPN (WireGuard)

This guide walks an operator through bringing a customer site's WireGuard tunnel up against the Astradial cloud — both first-time setup and recovery when an existing tunnel drops (e.g. someone changed the WAN interface and the peer got deleted).

It uses a Grandstream GWN router managed in GDMS (gdms.cloud/gwn) as the worked example, because that's what our current customers (V7 Tirupathur, etc.) run. The values are the same for any WireGuard client.

For the why behind tunnels, isolation, and subnet allocation, see Customer Tunnels (WireGuard). This page is the hands-on "make it connect" procedure.

How the two sides fit together

A tunnel has two ends:

Side Where it's configured What it holds
Cloud (server) Editor → org → Trunks → Network Tunnels The org's tunnel record. Created once during onboarding. Holds the customer's public key and allocates the /30. Survives WAN flaps.
Customer (client) The site router — GDMS → Settings → VPN → WireGuard The router's WireGuard interface (its own keys + local tunnel IP) and the peer entry that points back at the cloud.

The customer router initiates the tunnel (it dials out to the cloud endpoint; the cloud waits). Authentication is by cryptographic key, not IP — so when the customer's public IP rotates (CGNAT) or a WAN fails over, the tunnel re-handshakes and survives. See customer-tunnels.md → roaming.

You always need both halves present for traffic to flow. The most common support call is a tunnel that's up on the cloud side but the peer on the router got deleted — see Recovery.

What you need before you start

Get these from the Editor: org → Trunks → Network Tunnels → ⋮ → View customer config (the "Customer-side [Peer] block" modal).

Value Example (V7 Tirupathur — prod) Notes
Cloud public key 0Dfkqmj3UFLCN4mmG+Cp2j7VfP4J75iOyA+AZUxKQng= Same for every customer on this VPS (it's the server's wg1 key).
Pre-shared key (PSK) (per-tunnel — copy from the modal) A credential. Share only over a secure channel.
Cloud endpoint 147.93.168.216:51821 Prod (Mumbai) VPS, wg1 port.
Cloud tunnel IP 10.20.0.1 The customer's Allowed IP. /32 only — never the public IP.
Customer tunnel IP 10.20.0.2 The router's local tunnel address (/32).
Persistent keepalive 25 Keeps the NAT pinhole open.

Allowed IP is the cloud tunnel IP, not the public IP

Put 10.20.0.1/32 in Allowed IPs. Putting the public endpoint (147.93.168.216/32) there causes a GWN7002 routing-loop rejection — this was a real onboarding bug (issue #2 in customer-tunnels.md).

Part 1 — First-time setup

A. Cloud side (Editor) — create the tunnel

Do this once per customer. Skip to Part 1B if the tunnel already exists in Trunks → Network Tunnels.

  1. On the customer router, generate a WireGuard key pair first (GDMS step B1 below has a One-Click Generation button) and copy the public key.
  2. Editor → customer org → Trunks → Network Tunnels → + Add Tunnel.
  3. Name it (e.g. astradial-cloud or <Site>_vpn), paste the router's public key, Save. The system allocates a /30, generates the PSK, and writes the cloud wg1 peer.
  4. If phones on the customer LAN need to be reachable from the cloud, open ⋮ → Edit Tunnel and set Customer LAN CIDR (e.g. 192.168.0.0/24). This is required for the cloud to route back to the LAN. See customer-tunnels.md issue #3/#4.
  5. ⋮ → View customer config and keep that modal open — you'll copy from it in Part 1C.

B. Customer side (GDMS) — create the WireGuard interface

GDMS → Settings → VPN → WireGuard → + Add.

Field Value
Name e.g. V7_Tirupathur
Status On
Router / Interface Pick the WAN this tunnel egresses (see Which WAN?).
Listening Port 51820 (default)
Local IP Address / Mask The customer tunnel IP, /32 — e.g. 10.20.0.2 / 32
Private Key One-Click Generation (then copy the Public Key it shows back into the Editor in Part 1A if you hadn't already)
MTU 1420

Save.

Keys must match across both sides

The public key GDMS shows here must be the exact one stored on the cloud tunnel record. If you regenerate keys on the router, you must update the pubkey on the Editor tunnel too, or the handshake silently fails.

C. Customer side (GDMS) — add the peer (points at the cloud)

GDMS → Settings → VPN → WireGuard → on the tunnel's row click the peer icon → Add (Add Type = Manual).

GDMS field Value (from the Editor "View customer config" modal)
Name anything, e.g. <Site>_vpn
Status On ← easy to miss; the peer is inactive if this is off
Public Key the cloud public key (0Dfkqmj3…KQng=)
Pre-shared Key the per-tunnel PSK
Allowed IP 10.20.0.1 / 32
Endpoint Address 147.93.168.216
Endpoint Port 51821
Connection Keep-alive Interval 25
Preferred DNS 8.8.8.8 (optional, harmless)

Save & Apply.

The Status toggle is the on/off switch

GDMS notes "Once disabled, the associated peer service will also be disabled." A peer saved with Status off exists but never connects. Make sure it's on before saving.

Part 2 — Verify the tunnel is up

Within ~10–30s of Save & Apply:

  • Editor → Trunks → Network Tunnels → the tunnel's Last handshake refreshes to seconds-ago, status Active.
  • Cloud (SSH), if you have access: 
    ssh root@147.93.168.216 'wg show wg1'
    The customer's peer should show a latest handshake within the last few seconds and rising transfer counters.
  • End-to-end: a phone on the customer LAN re-registers — e.g. reception ext 09 appears in pjsip show contacts registered from the customer tunnel IP.

If nothing handshakes, jump to Troubleshooting.

Recovery: peer vanished after a WAN change

Symptom: the tunnel was working, then VPN → Peer shows "No Data" and the customer's phones go unreachable. The Editor still shows the tunnel as Active with a stale "Last handshake".

Cause: someone edited the WireGuard tunnel in GDMS and changed the Interface (e.g. BSNL → Rail). GDMS warns "After changing the interface, the corresponding Peer will be deleted automatically" and deletes the peer. The interface (keys, local IP) survives; only the peer that points at the cloud is gone.

Fix — you only need to re-add the peer. Nothing changes on the cloud side (keys are unchanged, so it re-handshakes immediately):

  1. Settle the interface first. Each interface change deletes the peer again, so pick the WAN you want, Save, and don't flip it afterwards. See Which WAN?.
  2. Re-add the peer exactly as in Part 1C — including turning Status on.
  3. Verify per Part 2.

You do not need to recreate the tunnel in the Editor or regenerate any keys.

Which WAN interface should I bind to?

GDMS pins a WireGuard tunnel to one WAN. Pick the healthy primary (e.g. BSNL when the Internet Source policy is BSNL-Primary-Rail-Backup).

Internet-Source failover does NOT move the tunnel

The GDMS Internet Source failover (BSNL → Rail) reroutes general internet, but it does not re-bind the WireGuard interface. If the pinned WAN drops, the tunnel drops even though the router still has internet on the backup WAN. The manual workaround — switching the interface — deletes the peer every time (the exact footgun in Recovery). The durable fix is a static public IP from the ISP; see customer-tunnels.md → fixes ranked by impact.

Troubleshooting

Symptom Likely cause Fix
Peer saved but no handshake Peer Status toggle left off Edit the peer, turn Status on, Save & Apply
No handshake; keys look right Pubkey on router ≠ pubkey on Editor tunnel Re-copy the router's public key into the Editor tunnel record
Handshake OK but phones can't reach cloud / one-way audio Customer LAN CIDR not set on the Editor tunnel, or kernel route missing Set Customer LAN CIDR in Editor → Edit Tunnel; a no-op PATCH re-applies routes (see customer-tunnels.md recovery)
GWN rejects the peer / routing loop Allowed IP set to the public IP Set Allowed IP to 10.20.0.1/32 (cloud tunnel IP) only
Tunnel flaps several times a day, BLF goes amber ISP rotating the public IP Static IP (best) + user-failover; see observed failure modes
Phone registers but qualify fails / Unavailable Softphone on TCP, fail2ban ban, or wrong auth ID See softphone gotchas