# OpenVPN Integration

OpenVPN is a widely‑used SSL/TLS VPN solution that supports a built‑in **management interface** and periodic **status logfile** exports. Xitogent can consume either source to expose key metrics directly inside the Xitoring app.

# 1. Prepare OpenVPN for metrics collection

Choose **one** of the following methods and reload OpenVPN before proceeding.

## 1.1 Method A: Enable the management plugin

Add a `management` directive to your server configuration file (e.g. `/etc/openvpn/server.conf`). You may expose the interface via **TCP/IP** _or_ a **UNIX domain socket**.

### TCP example

```conf
# Listen only on localhost, TCP port 7505
management 127.0.0.1 7505
```

### UNIX socket example

```conf
# Create a local socket at /run/openvpn/server.mgmt
management /run/openvpn/server.mgmt unix
```

> **Security tip:** Restrict access with the optional `management-client-user` directive or file‑based ACLs on the socket.

## 1.2 Method B: Enable the rotating status logfile

Add or modify the `status` directive:

```conf
# Export status every 30 seconds
status /var/log/openvpn/server-status.log 30
```

Ensure the logfile is readable by the `xitogent` user (e.g. via group membership or ACL).

## 1.3 Reload OpenVPN

```bash
sudo systemctl reload openvpn-server@server.service
```

Verify the chosen endpoint:

```bash
# TCP method
nc -z localhost 7505 && echo "Management port responsive"
# UNIX method
test -S /run/openvpn/server.mgmt && echo "Socket present"
# Logfile method
head /var/log/openvpn/server-status.log
```

# 2. Enable OpenVPN integration in Xitogent

Run:

```bash
xitogent integrate
```

Select **OpenVPN**. Xitogent will create `/etc/xitogent/integrations/openvpn_integration.conf`.

# 3. Metrics collected

| Metric                         | Type   | Description                                            |
|--------------------------------|--------|--------------------------------------------------------|
| connected_clients              | Gauge  | Current number of established VPN sessions.            |
| total_rx_bytes                 | Counter| Aggregate bytes received by the OpenVPN server since start.  |
| total_tx_bytes                 | Counter| Aggregate bytes transmitted by the OpenVPN server since start. |
| rx_bytes_per_sec              | Gauge  | Instantaneous receive throughput (bytes/s).            |
| tx_bytes_per_sec              | Gauge  | Instantaneous transmit throughput (bytes/s).           |
| clients.*.bytes_received       | Counter| Per‑client total bytes pulled from server.             |
| clients.*.bytes_sent          | Counter| Per‑client total bytes pushed to server.               |
| clients.*.rx_bytes_per_sec    | Gauge  | Per‑client receive rate.                               |
| clients.*.tx_bytes_per_sec    | Gauge  | Per‑client transmit rate.                              |

> **Note** Counters reset when the OpenVPN daemon restarts.

# 4. Setup Triggers for OpenVPN integration

| Use‑case        | Condition                         | Severity |
|------------------|-----------------------------------|----------|
| **Client surge** | `connected_clients > 200` for 5 min | WARNING  |
| **High bandwidth** | `rx_bytes_per_sec > 50 MB/s` for 2 min | MAJOR    |

# 5. Troubleshooting

| Symptom                           | Resolution                                                                                     |
|-----------------------------------|-----------------------------------------------------------------------------------------------|
| _No metrics_                     | Confirm the `mode` and endpoint in `openvpn_integration.conf` match your OpenVPN configuration. Tail `/var/log/xitogent/xitogent.log` for parsing or connection errors. |
| _Permission denied to UNIX socket_ | Adjust socket permissions (e.g., `chmod 660`).                                                     |
| _Stale logfile data_            | Ensure the `status` interval is ≤ 60 seconds and that log rotation doesn’t purge the file prematurely. |

# 6. Next steps

- Combine OpenVPN metrics with PING/TCP checks to monitor uplink quality.
- Build dashboards that chart bandwidth trends against connected client counts during peak hours.