---
title: "WireGuard VPN Kernel Interconnect & Site-to-Site Tunneling"
description: "Documentation for WireGuard"
---

## Table of Contents
1. [Overview & Architecture](#1-overview--architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & WireGuard Parameters](#5-field-reference--wireguard-parameters)
6. [Kernel-Space Cryptographic Architecture & Handshake Engine](#6-kernel-space-cryptographic-architecture--handshake-engine)
7. [Telecom Interconnect Deployment Patterns](#7-telecom-interconnect-deployment-patterns)
8. [Verification & Diagnostics](#8-verification--diagnostics)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Architecture

In **Ring2All SBC**, the **WireGuard** module provides high-performance, kernel-level Virtual Private Network (VPN) tunneling designed for telecommunications backbones. Unlike legacy userspace VPN protocols (OpenVPN, IPsec/IKEv2), WireGuard executes directly inside the Linux kernel (`wg0` interface), delivering line-rate packet throughput, minimal CPU overhead, and microsecond-level latency critical for real-time SIP and RTP traffic.

```
          ┌────────────────────────────────────────────────────────┐
          │               RING2ALL SBC (10.9.0.1/24)               │
          │             Kernel Network Namespace (wg0)             │
          └───────────────────────────┬────────────────────────────┘
                                      │
                   UDP Encapsulation (Port 51820)
                   ChaCha20-Poly1305 / Curve25519
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        ▼                             ▼                             ▼
┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
│ NYC-Interconnect │        │ Dallas-PBX-Core  │        │ NOC-Remote-Admin │
│ (10.9.0.2/32)    │        │ (10.9.0.3/32)    │        │ (10.9.0.4/32)    │
├──────────────────┤        ├──────────────────┤        ├──────────────────┤
│ Carrier SIP      │        │ Core Telephony Server  │        │ Operations &     │
│ Trunk Gateway    │        │ Media Cluster    │        │ Telemetry Link   │
└──────────────────┘        └──────────────────┘        └──────────────────┘
```

The module maintains server parameters in `sbc_admin.wg_server_config` and registered client nodes in `sbc_admin.wg_peers`, coordinating with the host WireGuard kernel module via Netlink sockets for instant, non-disruptive peer synchronization.

---

## 2. Business & Operational Significance

* **Ultra-Low Latency VoIP Interconnects**: Kernel-space packet processing reduces jitter and packet serialization delays, ensuring voice calls traversing private tunnels maintain high MOS (> 4.2).
* **Zero-Trust Trunk Security**: All peering relationships require mutual public key authentication (`Curve25519`). Unauthenticated or forged SIP packets are silently discarded at the network interface layer before reaching user space.
* **NAT Traversal & Dynamic Roaming**: WireGuard's stateful endpoint tracking automatically adapts to roaming IP addresses and behind-NAT gateways without dropping active audio sessions.
* **Streamlined Multi-DC PBX Bridging**: Connects geo-distributed Ring2All PBX nodes across cloud providers (AWS, Azure, DigitalOcean) and private datacenters without requiring expensive dedicated MPLS circuits.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Administrative Permissions | Operational Responsibilities |
| :--- | :--- | :--- |
| **Network Infrastructure Engineer** | Full Read & Write | Manages server keys, configures subnet routing, defines MTU parameters, and monitors handshake timers. |
| **Telecom Security Specialist** | Read & Write | Provisions peer cryptographic keys, enforces AllowedIPs access policies, and revokes compromised peers. |
| **NOC Operations Specialist** | Read-Only | Audits peer handshake status, monitors transfer counters, and reports packet loss on tunnel interfaces. |
| **AI VPN & Secure Tunnel Copilot** | Autonomous Monitoring & Toggling | Evaluates peer handshake liveness, audits encrypted transfer metrics, and toggles peer connectivity programmatically via MCP. |

---

## 4. Visual Interface & Layout

### WireGuard Peers Inventory
The main dashboard provides real-time visibility into all configured peer endpoints, status metrics, and control toggles:

![WireGuard Peers List View](/screenshots/sbc/admin/wireguard/wireguard-list.png)

* **Toolbar Controls**: Quick search, items-per-page selector, server start/stop toggle, server settings button, and Add Peer action.
* **Peer Table**: Displays Peer Name, assigned VPN IP, connection status badge (`Active` / `Offline`), and timestamp of the latest cryptographic handshake.
* **Action Icons**: Download peer configuration file (`.conf`), enable/disable peer toggle, and delete peer.

### Add Peer Modal
The creation dialog simplifies onboarding new telecom nodes and gateways:

![WireGuard Add Peer Modal](/screenshots/sbc/admin/wireguard/wireguard-peer-modal.png)

* Allows operators to specify a friendly name, description, client public key, and assigned tunnel IP address.
* Generates client configuration templates on demand with pre-filled endpoint addresses, DNS, and keepalive directives.

### WireGuard Server Configuration
The settings panel governs the host's tunnel parameters:

![WireGuard Server Settings](/screenshots/sbc/admin/wireguard/wireguard-settings.png)

---

## 5. Field Reference & WireGuard Parameters

### Server Settings Reference
| Parameter | Default | Validation | Description |
| :--- | :---: | :--- | :--- |
| **Listen Port** | `51820` | UDP port (1–65535) | External UDP port on which the WireGuard kernel interface listens for incoming encapsulation. |
| **VPN Network** | `10.9.0.0/24` | Valid CIDR | IPv4 subnet allocated for the private WireGuard overlay network. |
| **Server VPN IP** | `10.9.0.1` | Valid IPv4 | Local tunnel gateway IP assigned directly to the `wg0` network interface. |
| **MTU** | `1420` | Bytes (1280–1500) | Maximum Transmission Unit. Set to `1420` to prevent RTP packet fragmentation over WAN uplinks. |
| **Server Public Key** | Auto | Base64 Curve25519 | Public key distributed to peer nodes to authenticate the Ring2All SBC server. |

### Peer Configuration Reference
| Parameter | Type | Constraints | Description |
| :--- | :---: | :--- | :--- |
| **Peer Name** | `string` | 3–255 characters | Unique descriptive identifier for the connecting node (e.g., `NYC-Interconnect-GW`). |
| **Public Key** | `string` | 44-character Base64 | The client's Curve25519 public key. Private keys are never stored on the server. |
| **VPN IP** | `string` | IP or `/32` CIDR | Static tunnel IP address assigned to this specific peer node within the VPN network. |
| **Allowed IPs** | `string` | Comma-separated CIDRs | Subnets routed through this peer tunnel (e.g., `10.9.0.2/32, 192.168.20.0/24`). |
| **Persistent Keepalive** | `integer` | Seconds (e.g., `25`) | Interval for sending empty packets to maintain stateful NAT firewall mappings. |

---

## 6. Kernel-Space Cryptographic Architecture & Handshake Engine

WireGuard utilizes a modern cryptographic suite:
* **Curve25519**: Elliptic-curve Diffie-Hellman (ECDH) for initial key exchange.
* **ChaCha20**: High-speed symmetric stream cipher for bulk packet encryption.
* **Poly1305**: Authenticator guaranteeing packet integrity and authentication.
* **BLAKE2s**: Cryptographic hashing and key derivation.
* **SipHash24**: Hash-table lookup protection against denial-of-service attacks.

### Handshake State Machine
* Handshakes occur automatically every **120 seconds** (re-keying).
* If no traffic flows for more than **180 seconds**, the connection transitions to an idle state.
* The UI calculates the peer state based on `last_handshake`: handshakes within 180 seconds indicate an **Active** peer, while older handshakes denote an **Offline** peer.

---

## 7. Telecom Interconnect Deployment Patterns

### Pattern A: Core PBX to SBC Interconnect
Connects remote Telephony Server or Ring2All PBX clusters over public cloud environments directly to the SBC. SIP signaling is sent to `10.9.0.1:5060` across `wg0`, bypassing WAN firewall exposure entirely.

### Pattern B: Branch Office Gateway
Connects remote branch office Session Border Controllers or VoIP gateways located behind symmetric enterprise NATs. Configuring `PersistentKeepalive = 25` guarantees bidirectional SIP trunk connectivity without port forwarding.

### Pattern C: Secure NOC & SIP Telemetry Link
Enables network engineers to securely access administrative RPC consoles, Kamailio diagnostic sockets, and Prometheus metrics endpoints without exposing management ports to the open internet.

---

## 8. Verification & Diagnostics

Administrators can evaluate WireGuard interface statistics, verify peer cryptographic status, and inspect live packet counters using Linux CLI commands:

```bash
# 1. Inspect live WireGuard interface and peer status
wg show wg0

# 2. Verify IP link state and MTU assignment
ip -d link show wg0

# 3. Check active routing table entries for the VPN subnet
ip route show dev wg0

# 4. Live capture of decrypted SIP traffic traversing the tunnel
tcpdump -n -i wg0 port 5060

# 5. Send ICMP diagnostic ping across the private overlay
ping -c 3 10.9.0.2
```

---

## 9. Model Context Protocol (MCP) AI Integration

The **WireGuard VPN** module is integrated into the Ring2All SBC Model Context Protocol (MCP) server, equipping autonomous AI assistants and NOC copilots to monitor kernel interface statuses, audit peer handshake latencies, and dynamically control peer connections.

### 9.1 MCP Tool Summary

| Tool Name | Action | Risk Level | Purpose |
| :--- | :--- | :--- | :--- |
| `get_sbc_wireguard_status` | Read | `read` | Retrieve WireGuard interface status, listen port, public endpoint, and aggregate transfer bytes. |
| `list_sbc_wireguard_peers` | Read | `read` | List all registered VPN peers with handshake timestamps, assigned tunnel IPs, and online states. |
| `toggle_sbc_wireguard_peer` | Write | `operational` | Enable or disable a WireGuard peer tunnel connection without restarting the server interface. |

### 9.2 Tool Schemas & Input Parameters

#### Schema: `get_sbc_wireguard_status`
```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

#### Schema: `list_sbc_wireguard_peers`
```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

#### Schema: `toggle_sbc_wireguard_peer`
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "Unique integer ID of the WireGuard peer"
    },
    "enabled": {
      "type": "boolean",
      "description": "True to enable peer tunnel; false to disable"
    }
  },
  "required": ["id", "enabled"],
  "additionalProperties": false
}
```

### 9.3 Sample Tool Execution Payloads

#### Example 1: Retrieving WireGuard Interface Status
**Request Payload:**
```json
{
  "tool": "get_sbc_wireguard_status",
  "parameters": {}
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "interface": "wg0",
    "interfaceUp": true,
    "listenPort": 51820,
    "vpnNetwork": "10.9.0.0/24",
    "serverVpnIp": "10.9.0.1",
    "serverPublicKey": "yK1+V9QfR4E9g8oN4mB6uC1d2E3f4G5h6I7j8K9l0M=",
    "publicEndpointIp": "198.51.100.25",
    "peersOnline": 3,
    "peersTotal": 4,
    "bytesReceived": 104857600,
    "bytesSent": 209715200,
    "enabled": true
  }
}
```

#### Example 2: Toggling Peer Administrative State
**Request Payload:**
```json
{
  "tool": "toggle_sbc_wireguard_peer",
  "parameters": {
    "id": 2,
    "enabled": false
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "message": "WireGuard peer 'Dallas-PBX-Core' updated to disabled",
    "peerId": 2,
    "enabled": false
  }
}
```

### 9.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"Check if the WireGuard VPN interface wg0 is running and report how many peers are currently online."*
  → Agent invokes `get_sbc_wireguard_status()`.
* *"List all WireGuard peers and identify any peer that has not completed a handshake in over 10 minutes."*
  → Agent invokes `list_sbc_wireguard_peers()`.
* *"Temporarily disable WireGuard peer ID 2 while maintenance is performed on the Dallas PBX core."*
  → Agent invokes `toggle_sbc_wireguard_peer({"id": 2, "enabled": false})`.

#### Spanish Prompts (Español)
* *"Verifica si la interfaz wg0 de WireGuard está activa e infórmame cuántos peers están conectados."*
  → Agente invoca `get_sbc_wireguard_status()`.
* *"Lista todos los peers de WireGuard e identifica aquellos cuyo último handshake supere los 10 minutos."*
  → Agente invoca `list_sbc_wireguard_peers()`.
* *"Deshabilita temporalmente el peer ID 2 de WireGuard mientras se realiza mantenimiento en el núcleo de Dallas."*
  → Agente invoca `toggle_sbc_wireguard_peer({"id": 2, "enabled": false})`.

### 9.5 Enterprise Security & Execution Safeguards

1. **Kernel-Level Netlink Isolation**: Toggling peers executes non-blocking atomic Netlink IPC calls (`wg set wg0 peer <pubkey> remove/add`), preventing network interface drops for existing active calls on other tunnels.
2. **Private Key Omission**: Private keys are generated strictly client-side or during initial provisioning and never stored in PostgreSQL or returned by any MCP tool.
3. **Audit Trail Logging**: All peer status mutations trigger structured event logs in `sbc_admin.audit_logs`, capturing operator credentials and IP address.

---

## 10. Glossary

* **ChaCha20-Poly1305**: Authenticated encryption algorithm combining ChaCha20 stream cipher with Poly1305 authenticator.
* **Curve25519**: Elliptic curve offering 128 bits of security designed for ECDH key agreements.
* **Kernel-Space**: Privileged memory space where core operating system functions and device drivers execute at line-rate.
* **PersistentKeepalive**: Periodic heartbeat packet ensuring stateful NAT firewalls keep UDP translation bindings open.
* **Model Context Protocol (MCP)**: An open architectural standard allowing AI copilots to programmatically audit VPN health and manage secure tunneling overlays.