Client Installation Guide

RingQ Secure Tunnel

Configuration Guide

Server (RingQ PBX portal) setup and client (branch/site) installation walkthrough

The RingQ Secure Tunnel lets a remote site run its entire phone system over a single outbound connection. Instead of opening separate ports for signalling, management, and audio, RingQ encapsulates all three inside one persistent connection on TCP port 6010.

The connection is always initiated outbound, from the Tunnel Client at the remote site to the RingQ cloud PBX. On the PBX side, the only requirement is one inbound allowance for TCP 6010 — no other ports (8443, 7443, etc.) need to be opened for the tunnel to function.

How the tunnel is established

1. Client initiates — the Tunnel Client opens an outbound TCP 6010 connection to the RingQ cloud PBX.
2. Token exchange — the client presents its authentication token (auth key); the cloud validates it before allowing anything else through.
3. Tunnel established — once authenticated, a single persistent, encrypted connection is held open between client and cloud.
4. Everything rides inside it — signalling, management traffic, and media (audio) all travel through that same authenticated connection.

Note: Because the token is validated before the tunnel is trusted, an unauthenticated connection attempt on TCP 6010 gets nowhere — the port being open does not by itself grant access.

Why this is secure

• No inbound exposure beyond one port — 8443, 7443, and all other management/API ports stay closed on the cloud PBX side.
• Token-gated, not just port-gated — reaching the port is not enough; the connection must authenticate before it's trusted.
• Persistent, not repeatedly negotiated — the tunnel stays up as one long-lived connection rather than opening new ports per call.
• NAT / firewall friendly by design — since the client always initiates outbound, most branch firewalls need no inbound rules at all.

Bottom line: Open only TCP 6010 outbound from the client / inbound on the PBX side. All media streams are encapsulated inside this one connection — no other ports, no added complexity.

Applies to every endpoint

Whatever is registered behind the Tunnel Client — physical desk phones or software clients — reaches the cloud PBX through the same authenticated TCP 6010 connection. Each branch or remote site runs its own Tunnel Client, so multiple sites can connect to the same cloud PBX, each over its own single-port tunnel.

2. Prerequisites

3. Server-Side Setup — Generate a Tunnel Auth Key

Before installing anything on the client, create a tunnel entry in the RingQ portal. This generates the auth key that pairs the remote device with your PBX server.

1. In the RingQ portal, open Tunnel Connections.
2. Click Add Tunnel.
3. Enter a Tunnel name that identifies the site or device (e.g. “Branch Office”).
4. The portal auto-generates an Auth key. Click Save.
5. Copy the Auth key — you'll paste it into the client installer in Section 4.

Add Tunnel dialog — name the tunnel and the portal generates the auth key.

Each row on the Tunnel Connections page represents one paired device, showing its auth key, device details, last-seen time, and online/offline status. Total, online, and offline counts appear at the top of the page.

4. Client-Side Installation

On the remote machine that will host the Tunnel Client, run the installer with root privileges.

curl -fsSL https://raw.githubusercontent.com/Cal4Care-Developers/proxytunnel/master/install.sh -o /tmp/install.sh

chmod +x /tmp/install.sh

sudo /tmp/install.sh

The installer runs a system check (OS, architecture, device ID, LAN IP, and public IP are auto-detected), then prompts for two values — everything else is filled in automatically:

• PBX Domain — your RingQ PBX hostname (e.g. yourcompany.ringq.ai)
• Tunnel Auth Key — the key generated in Section 3, from the RingQ portal

Tunnel installer — system check followed by the PBX Domain and Auth Key prompts.

Tip: The Auth Key entered here must exactly match the one generated for this tunnel in the portal (Section 3) — that's what pairs this device with your PBX.

Confirm the configuration

After the PBX Domain and Auth Key are entered, the installer echoes back the full configuration it derived — API URL, tunnel endpoint, LAN/public IP, and the phone signaling ports — before it changes anything on the system.

Configuration summary — review the derived values, then confirm to proceed.

• Review the PBX Domain, PBX Tunnel endpoint (tcp://<domain>:6010), and Device ID for accuracy.
• Type Y (or press Enter) at the Proceed with installation? prompt to continue.

Installation complete

Once confirmed, the installer finishes and prints a summary with the service name, config file location, and the commands used to manage the tunnel going forward.

RingQ NX Device Proxy installed successfully — service, logs, and status commands.

Key paths and commands from this summary:

5. Installer Command Reference

The same install script supports re-running for maintenance, without needing to repeat the full setup each time.

6. Checking Tunnel Status

Once installed, use the ringqtunnel-status command on the client to confirm the tunnel is connected.

ringqtunnel-status # one-shot status (service, auth, IPs, last active)

ringqtunnel-status --watch # live refresh every 5s

ringqtunnel-status --json # JSON output, for portal/monitoring integration

You can cross-check the same connection from the portal side: on the Tunnel Connections page, the tunnel's row should show Status: Online and a recent Last Seen time.

Tunnel Connections page — “Branch Office” now shows Status: Online, with its Device ID, Public IP, and Local IP populated.

Bottom line: Matching Public IP / Local IP values between this page and the client's system-check output (Section 4) confirm the correct device paired successfully.

7. Uninstalling the Tunnel Client

To remove the Tunnel Client from a device:

curl -fsSL https://raw.githubusercontent.com/Cal4Care-Developers/proxytunnel/master/uninstall.sh -o /tmp/uninstall.sh

chmod +x /tmp/uninstall.sh

sudo /tmp/uninstall.sh

8. Troubleshooting Checklist

• Tunnel shows Offline in the portal — confirm outbound TCP 6010 to the PBX domain isn't blocked by a local or upstream firewall.
• Installer rejects the auth key — re-copy it from the portal (Section 3); keys are tied to a single tunnel entry.
• Need to change the PBX domain or key — re-run the installer with --reconfigure rather than uninstalling.
• Upgrading the Go runtime or refreshing the client code — use --reinstall.
• No other inbound ports (8443, 7443, etc.) are required on either side — if something else is being opened, it isn't needed for the tunnel itself.