Provision a Grandstream ATA onto the VPN¶

Step-by-step for putting a Grandstream GXW-series FXS gateway (e.g. GXW4216V2) onto the OpenVPN ATA tunnel. Worked example: Mithra Scan (mithra-gxw01 → 10.21.0.17), provisioned 2026-06-15.

Architecture, security model, and the IP/cert registry live in the feature doc. This page is the "how to do it" runbook.

Prerequisites¶

• SSH to the cloud host: ssh root@147.93.168.216
• The OpenVPN server is already up (one-time; see feature doc). Check: systemctl is-active openvpn-server@astradial-ata → active.
• A free /28 and tunnel IP picked from the registry. Update that table when you allocate.

Step 1 — Provision the device (server side)¶

One command generates the per-device cert, pins its static tunnel IP, and stages the three upload files:

ssh root@147.93.168.216 \
  '/usr/local/sbin/ovpn-add-client.sh <customer-slug> <device-slug> <tunnel-ip>'

# worked example:
# /usr/local/sbin/ovpn-add-client.sh mithra-scan mithra-gxw01 10.21.0.17

It prints the exact ATA settings and the scp line to fetch the files. One device = one cert = one IP. Do not reuse a cert across devices or customers.

Step 2 — Fetch the three files to your Mac¶

# run FROM your Mac
scp root@147.93.168.216:/etc/openvpn/clients/<customer-slug>/{ca.crt,<device-slug>.crt,<device-slug>.key} ~/Downloads/

# worked example:
scp root@147.93.168.216:/etc/openvpn/clients/mithra-scan/{ca.crt,mithra-gxw01.crt,mithra-gxw01.key} ~/Downloads/

Step 3 — Enter settings in the GXW web UI¶

Maintenance → VPN → OpenVPN Settings (#page:maintenance_openvpn)

⚠️ The handover brief said LZO = Yes; we run no compression, so set LZO = No. This is the one place the live config differs from that brief.

HT8xx (HandyTone) ATAs — same server, different UI¶

The HT8xx HandyTone series (HT814, HT813, etc.) speaks the same OpenVPN and uses the same per-device cert flow, but the web UI differs from the GXW:

Everything else (server 147.93.168.216:1194 UDP, AES-256-CBC, SHA256, Comp-LZO No, the three uploaded files) is identical. Worked example: Paavai Hospital (paavai-ht814 → 10.21.0.33), provisioned 2026-06-17.

Dinstar DAG (FXS) gateways — single .ovpn, HTTPS web UI¶

Dinstar DAG-series analog gateways speak the same OpenVPN to the same server, but differ from Grandstream in two ways that matter operationally:

Crypto is identical (UDP 1194, AES-256-CBC, SHA256, no compression, no tls-auth). Worked example: DCNet (dcnet-dag01 → 10.21.0.81), provisioned & live 2026-06-30. The .ovpn was built by inlining the three staged files and mirroring astradial-ata.conf's directives (cipher AES-256-CBC, auth SHA256, remote-cert-tls server, no comp-lzo).

The web UI cert is self-signed — the browser warns; click Advanced → Proceed. HTTP 000 on the status check almost always means you probed :80 on a device whose UI is on :443.

⚠️ This is not Dinstar-only. Some HT8xx firmware also serves the admin UI over HTTPS/:443 with HTTP/:80 closed (seen on Thangavelu thangavelu-hospitals-ata01, 2026-07-04). When the Details/status check shows ⛔ HTTP 000 — not reachable but ping/VPN are fine, the device is up — the checker probed the wrong port/scheme. Per-customer .command fix: set DEVICE_PORT=443, use an https:// URL, curl -k, and accept 302 as reachable (the login redirect) — not just 200/401. The provision-client.sh generator now emits this (302 accepted); older generated folders need the manual edit.

Save and Apply → Reboot.

Then point the device's SIP Profile at the PBX over the tunnel:

ssh root@147.93.168.216 'asterisk -rx "pjsip show contacts" | grep <ext-prefix>'

Step 4 — Verify the tunnel & registration¶

# Server side — watch the device connect:
ssh root@147.93.168.216 'journalctl -u openvpn-server@astradial-ata -f'
#   look for: "<device-slug>" ... "Peer Connection Initiated"

# Connected clients + their tunnel IPs:
ssh root@147.93.168.216 'cat /var/log/openvpn/astradial-ata-status.log'
#   the device should hold its static IP (e.g. 10.21.0.17)

# SIP registration landed:
ssh root@147.93.168.216 'asterisk -rx "pjsip show contacts" | grep <ext-or-ip>'

On the GXW Status page: VPN shows connected with tunnel IP 10.21.0.x; FXS ports show Registered.

Management-access-only devices (e.g. Mithra Scan) won't have SIP registrations — skip the pjsip show contacts check. For those, "working" = the device's tunnel IP pings and its web UI answers (next section).

Step 5 — Reach the device's web UI over the tunnel¶

The device's admin UI is only on its LAN side; reach it from your Mac by forwarding a local port through the server to the device's tunnel IP:

ssh -L 8080:10.21.0.17:80 root@147.93.168.216     # leave running
# then open  http://localhost:8080  in the browser

Use http:// explicitly and prefer an Incognito window — Chrome otherwise auto-upgrades localhost to HTTPS and the GXW (plain HTTP) returns ERR_SSL_PROTOCOL_ERROR.

Helper tool (recommended)¶

Instead of the raw ssh -L, use gxw-tunnel.sh (kept with the per-customer cert folder on the operator's Mac, e.g. ~/AstradialDevelopment/OpenVPN/). It opens the forward, launches Chrome in incognito, and reports status:

./gxw-tunnel.sh start  <device-ip> [local-port]   # open tunnel + incognito Chrome
./gxw-tunnel.sh status <device-ip>                # connected? reachable? web UI? 
./gxw-tunnel.sh stop   <device-ip> [local-port]   # close tunnel

# Mithra Scan example:
./gxw-tunnel.sh start  10.21.0.17

Pass a distinct local-port (e.g. 8081) to manage two devices at once. Per-customer double-clickable .command shortcuts (Start / Stop / Details) wrap the same logic for non-CLI use; copy a customer folder and change DEVICE_IP at the top for a new device.

These helper scripts live alongside the device's private key in a git-ignored folder — never commit that folder (key material).

Retrieving configs & credentials¶

🔒 No secret values are written in this wiki. This section says where each lives and how to fetch it. Never paste a key, secret, or password into these docs — store them in the team password manager under the customer's entry (e.g. Mithra Scan — GXW4216V2).

Decommission / replace a device¶

ssh root@147.93.168.216
cd /etc/openvpn/easy-rsa
./easyrsa revoke <device-slug>      # invalidate the one device's cert
./easyrsa gen-crl                    # regenerate the revocation list
rm -f /etc/openvpn/ccd/<device-slug> # free its static IP
rm -rf /etc/openvpn/clients/<customer>/   # if the whole customer is leaving

If you start using the CRL for live enforcement, add crl-verify /etc/openvpn/easy-rsa/pki/crl.pem to astradial-ata.conf and restart the service. Not enabled yet (no revocations to date).

Troubleshooting¶

Audio tuning — volume, echo, and the Save-and-Apply blip¶

Two independent knobs, don't swap them (Audio Settings → Analog Line Settings):

• RX Gain = level the ATA feeds the handset earpiece → "staff can't hear the caller." Default -6 dB (attenuating).
• TX Gain = level from the handset mic toward the network → "the caller can't hear staff." Default -4 dB.
• SLIC = impedance/hybrid balance → sets echo (and shifts loudness as a side effect). Use it for echo, not for volume.

To raise volume (worked example: ACR, 2026-07-18, raised in steps to +6 dB):

1. Raise RX Gain in steps (-6 → 0 → +3 → +6; +6 is the ceiling). Save and Apply between steps.
2. After each raise, test the FAR end for echo/distortion — call in from a mobile and confirm the caller doesn't hear their own voice echoing and that loud speech isn't crackly. ACR staff won't notice echo; only the far party will, because higher RX leaks back through the hybrid into TX (USA 1 impedance + the enabled Line Echo Canceller mitigate, but +6 pushes hard). If echo/distortion appears, drop back one step.
3. +6 is the last stop the ATA can offer. Still too quiet? Use the handset's own earpiece volume or an amplified/HAC handset — not more ATA gain.

See also¶

• OpenVPN ATA Tunnels — architecture & security model
• Connect a Customer Router to the VPN (WireGuard) — the sibling flow for site routers
• Troubleshooting → Error 95: Alphion ONT FXS gateway — fake busy (SIP ALG), can't-dial-out (P/T switch + stuck channel), enable call waiting