---
title: "OpenVPN Client Module Documentation"
description: "Documentation for OpenVPN Client"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
10. [Common Scenarios & Examples](#6-common-scenarios--examples)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the OpenVPN Client module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Administration**.
3. Under **Network**, click **OpenVPN Client** (`/admin/network/openvpn-client`).
4. Upload OpenVPN client configuration files (`.ovpn`), monitor real-time tunnel link status, verify assigned virtual IPs, and inspect bidirectional network traffic.

---

## Screenshots & Visual Interface

### Site-to-Site OpenVPN Client Gateway
Operational tunnel interface presenting active connection state, remote carrier VPN endpoint (`vpn.carrier-connect.net:1194`), local VPN IP assignment (`10.8.0.25`), gateway routing, connection uptime, and bidirectional byte counters (Bytes In / Bytes Out).
![OpenVPN Client Connection Status](/screenshots/admin/network/openvpn-client-form.png)

---

## 🎯 User Roles & Key Capabilities

| Role | Access Level | Responsibilities & Capabilities |
| :--- | :--- | :--- |
| **PBX Super Administrator** | Full Access (`RW`) | Upload site-to-site `.ovpn` configuration profiles, manage systemd tunnel services (`openvpn-client@site-to-site`), and initiate connect/disconnect requests. |
| **Network & Security Engineer** | Full Operations (`RW`) | Verify cryptographic handshake parameters, check MTU fragmentation, review remote carrier routes, and inspect IP routing tables. |
| **DevOps & Cloud Operator** | Monitoring (`RO`) | Monitor tunnel connection uptime, detect automatic reconnect loops, and alert on traffic volume drops. |
| **AI Platform Copilot / MCP Agent** | Diagnostic & Telemetry (`RO`) | Execute `get_openvpn_client_status` to evaluate site-to-site tunnel health, transfer metrics, and gateway reachability. |

---

## 1. Module Overview (Technical)

### What Is OpenVPN Client?

OpenVPN Client is a **site-to-site VPN module** that connects the PBX server to another network via VPN. This enables secure connectivity between data centers, branch offices, or cloud environments.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│              OpenVPN Client Architecture                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Local PBX Server                                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                                                          │   │
│  │  OpenVPN Client                                          │   │
│  │  ┌────────────────────────────────────────────────────┐  │   │
│  │  │                                                    │  │   │
│  │  │  .ovpn Configuration File                          │  │   │
│  │  │  ├─ Remote Host: vpn.datacenter.com               │  │   │
│  │  │  ├─ Remote Port: 1194                             │  │   │
│  │  │  ├─ Protocol: UDP                                 │  │   │
│  │  │  └─ Certificates embedded                         │  │   │
│  │  │                                                    │  │   │
│  │  └────────────────────────────────────────────────────┘  │   │
│  │                                                          │   │
│  │  Status: ● Connected                                     │   │
│  │  Local IP: 10.8.0.5                                      │   │
│  │  Remote IP: 10.8.0.1                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       │ Encrypted VPN Tunnel                                   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Remote Network / Data Center                      │   │
│  │                                                          │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │   │
│  │  │ VPN Server  │  │ SIP Trunk   │  │ Database    │      │   │
│  │  │ 10.8.0.1    │  │ 10.0.0.10   │  │ 10.0.0.20   │      │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘      │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

OpenVPN Client provides **secure site connectivity**:

| Without Site VPN | With Site VPN |
|------------------|---------------|
| Public internet | Private tunnel |
| Exposed services | Secured access |
| Complex routing | Simple tunnel |
| Multiple configs | Single connection |

### Use Cases

1. **Data Center Connection**
   - Connect to main DC
   - Access internal services

2. **Branch Office Link**
   - Site-to-site tunnel
   - Unified network

3. **Cloud Integration**
   - AWS/Azure VPN
   - Hybrid deployment

4. **Trunk Security**
   - SIP over VPN
   - Secure voice

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **.ovpn Upload** | Easy configuration |
| **One-Click Connect** | Simple control |
| **Status Monitoring** | Connection visibility |
| **Traffic Stats** | Bandwidth tracking |
| **Auto-Reconnect** | Reliable connection |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- Upload .ovpn configuration file
- Connect/disconnect VPN
- Monitor connection status
- View traffic statistics
- See connection details
- Delete configuration

### OpenVPN Client Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              OpenVPN Client                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Site-to-site VPN connection to another server                 │
│                                                                 │
│  ▼ Configuration                                                │
│    Upload your .ovpn configuration file                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                                                             ││
│  │  Connection Name: datacenter-vpn                           ││
│  │                                                             ││
│  │  Configuration: ● Loaded                                   ││
│  │                                                             ││
│  │  [Connect]  [Delete Configuration]                         ││
│  │                                                             ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
│  ▼ Connection Status                                            │
│    Current VPN connection details                               │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                                                             ││
│  │  Status: ● Connected                                       ││
│  │                                                             ││
│  │  Remote Host: vpn.datacenter.com                           ││
│  │  Remote Port: 1194                                          ││
│  │                                                             ││
│  │  ─────────────────────────────────────────────              ││
│  │                                                             ││
│  │  IP Addresses:                                              ││
│  │    Local IP: 10.8.0.5                                      ││
│  │    Remote IP: 10.8.0.1                                     ││
│  │                                                             ││
│  │  ─────────────────────────────────────────────              ││
│  │                                                             ││
│  │  Data Transfer:                                             ││
│  │    Bytes Received: 1.2 GB                                  ││
│  │    Bytes Sent: 456 MB                                      ││
│  │                                                             ││
│  │  Connected Since: 2024-01-15 08:30:00                      ││
│  │  Last Checked: 2024-01-16 14:22:15                         ││
│  │                                                             ││
│  │  [Disconnect]  [Refresh Status]                            ││
│  │                                                             ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### No Configuration State

```
┌─────────────────────────────────────────────────────────────────┐
│              OpenVPN Client                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Site-to-site VPN connection to another server                 │
│                                                                 │
│  ▼ Configuration                                                │
│    Upload your .ovpn configuration file                        │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                                                             ││
│  │            ⚠️ No configuration uploaded                     ││
│  │                                                             ││
│  │  Upload an .ovpn file to configure the site-to-site       ││
│  │  VPN connection                                             ││
│  │                                                             ││
│  │  [Upload Configuration]                                     ││
│  │                                                             ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Upload Configuration Modal

```
┌─────────────────────────────────────────────────────────────────┐
│              Upload .ovpn File                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Select or drag and drop your OpenVPN configuration file       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                                                             ││
│  │                  📁                                         ││
│  │                                                             ││
│  │     Drop .ovpn file here or click to browse                ││
│  │                                                             ││
│  └─────────────────────────────────────────────────────────────┘│
│                                                                 │
│  Selected file: datacenter.ovpn                                │
│                                                                 │
│  [Upload and Save] [Cancel]                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Complete .ovpn**: Ensure certificates are embedded in the file.

> [!TIP]
> **Refresh Status**: Click to update connection stats.

> [!WARNING]
> **Delete**: Deleting config will disconnect active connection.

---

## 4. Configuration Sections

### Configuration Section

| Field | Description |
|-------|-------------|
| **Connection Name** | VPN connection identifier |
| **Configuration** | Loaded status |
| **Upload** | .ovpn file upload |
| **Delete** | Remove configuration |

### Status Section

| Field | Description |
|-------|-------------|
| **Status** | Connected/Disconnected |
| **Remote Host** | VPN server address |
| **Remote Port** | VPN port |
| **Local IP** | Assigned VPN IP |
| **Remote IP** | Server tunnel IP |
| **Bytes Received** | Download traffic |
| **Bytes Sent** | Upload traffic |
| **Connected Since** | Connection start time |
| **Last Checked** | Last status update |

---

## 5. Settings Reference

### Connection States

| Status | Icon | Description |
|--------|------|-------------|
| **Connected** | ● | Active VPN tunnel |
| **Disconnected** | ○ | No connection |
| **Connecting** | ◐ | Establishing tunnel |
| **Error** | ⊘ | Connection failed |

### .ovpn File Requirements

| Component | Required | Notes |
|-----------|----------|-------|
| Remote host | Yes | Server address |
| Remote port | Yes | Usually 1194 |
| Certificates | Yes | CA, cert, key |
| Protocol | Yes | UDP or TCP |

### Example .ovpn Structure

```
client
dev tun
proto udp
remote vpn.datacenter.com 1194
resolv-retry infinite
nobind
persist-key
persist-tun
ca [inline]
cert [inline]
key [inline]
cipher AES-256-GCM
auth SHA256
verb 3

<ca>
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
</ca>

<cert>
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
</cert>

<key>
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
</key>
```

---

## Model Context Protocol (MCP) AI Integration

The OpenVPN Client module exposes programmatic status diagnostics to the **Model Context Protocol (MCP)**, allowing operators and autonomous NOC assistants to continuously audit site-to-site VPN link health.

### Available MCP Tools

| Tool Name | Scope | Description |
| :--- | :--- | :--- |
| `get_openvpn_client_status` | Tunnel Telemetry (`RO`) | Queries the status of the site-to-site OpenVPN Client connection, remote gateway endpoint, tunnel IP, and traffic counters. |

### Tool Schemas & Payloads

#### `get_openvpn_client_status`
```json
{
  "name": "get_openvpn_client_status",
  "description": "Queries the status of the site-to-site OpenVPN Client connection, remote gateway endpoint, tunnel IP, and traffic counters.",
  "parameters": {
    "type": "object",
    "properties": {}
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "client": {
      "name": "Site-to-Site Carrier VPN",
      "serviceRunning": true,
      "connectionState": "connected",
      "remoteHost": "vpn.carrier-connect.net",
      "remotePort": 1194,
      "localIp": "10.8.0.25",
      "remoteIp": "10.8.0.1",
      "bytesReceived": 15849200,
      "bytesSent": 12493020,
      "connectedSince": "2026-09-08T08:15:00Z",
      "lastChecked": "2026-09-08T10:45:00Z"
    }
  }
}
```

### Bilingual Natural Language Prompt Examples

#### English Prompts
- *"Copilot, check if the site-to-site OpenVPN client tunnel is connected and show the assigned local IP."*
- *"What is the remote gateway address and current byte transfer count for the OpenVPN client?"*
- *"Verify if the OpenVPN client systemd service is active or reported disconnected."*

#### Spanish Prompts
- *"Copilot, comprueba si el túnel cliente OpenVPN está conectado y qué IP virtual tiene asignada."*
- *"¿Cuál es la dirección del host remoto y cuántos bytes se han transferido por la VPN?"*
- *"Verifica si el servicio cliente de OpenVPN se encuentra en estado connected o disconnected."*

### Enterprise Safeguards & Execution Boundaries
1. **Tenant-Scoped Connection State:** Tunnel metadata is stored in `public.openvpn_connection` isolated by `tenant_id`. Sub-tenant assistants cannot inspect site-to-site links belonging to other tenants.
2. **Read-Only Inspection Safety:** `get_openvpn_client_status` queries systemd status (`systemctl is-active openvpn-client@site-to-site`) and database counters without interrupting ongoing VoIP audio RTP sessions passing through the tunnel.
3. **Controlled Tunnel Lifecycle:** Tunnel disconnects and reconnections require explicit administrative write access via the Web UI or authenticated API routes.

---

## 6. Common Scenarios & Examples

### Scenario 1: Upload Configuration

1. Click Upload Configuration
2. Drag .ovpn file or click to browse
3. Select file
4. Click Upload and Save
5. Configuration now loaded

### Scenario 2: Connect to VPN

1. Ensure configuration is loaded
2. Click Connect
3. Wait for connection
4. Status shows "Connected"
5. View assigned IP addresses

### Scenario 3: Monitor Connection

1. View Connection Status section
2. Check Remote Host and Port
3. View Local/Remote IPs
4. Check Data Transfer stats
5. Click Refresh Status for updates

### Scenario 4: Replace Configuration

1. Click Delete Configuration
2. Confirm deletion
3. Connection disconnects
4. Upload new .ovpn file
5. Connect with new config

---

## 7. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Single Connection**: Only one VPN client connection.

> [!NOTE]
> **Embedded Certs**: Certificates must be embedded in .ovpn.

> [!WARNING]
> **Delete Disconnects**: Deleting config terminates connection.

### Best Practices

1. **Complete Config**: Use .ovpn with embedded certificates
2. **Test First**: Verify .ovpn works before uploading
3. **Monitor Status**: Check connection regularly
4. **Secure File**: Protect .ovpn file (contains private key)
5. **Backup Config**: Keep copy of working .ovpn

### .ovpn File Tips

| Tip | Description |
|-----|-------------|
| Inline certs | Use `<ca>`, `<cert>`, `<key>` sections |
| Single file | All config in one .ovpn |
| Test locally | Verify with OpenVPN client first |
| Absolute paths | Avoid external file references |

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| Upload fails | Invalid format | Check .ovpn structure |
| Can't connect | Wrong server | Verify remote host |
| Connection drops | Network issue | Check internet |
| Error state | Bad certificates | Regenerate .ovpn |

### Check VPN Status

```bash
# Check OpenVPN client service
systemctl status openvpn@client

# View client log
tail -f /var/log/openvpn/client.log

# Check tunnel interface
ip addr show tun0

# Test connectivity
ping 10.8.0.1
```

### Verify Configuration

```bash
# Test .ovpn file locally
openvpn --config client.ovpn --verb 4

# Check for syntax errors
openvpn --config client.ovpn --show-tls
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **.ovpn** | OpenVPN config file |
| **Site-to-Site** | Network-to-network VPN |
| **Tunnel** | Encrypted connection |
| **TUN** | Network tunnel device |
| **Client** | VPN initiator |
| **Remote** | VPN server side |

---

*Documentation last updated: January 2026*