249 lines
6.2 KiB
Markdown
249 lines
6.2 KiB
Markdown
# OpenVPN Monitor UI & API
|
|
|
|
A modern, reactive dashboard for monitoring OpenVPN server status, traffic history, and certificate validity. Built with Vue.js 3 and Python (Flask).
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
* **Backend**: Python 3.9+ (`pip`, `venv`)
|
|
* **Frontend**: Node.js 18+ (for building only), any Web Server (Nginx/Apache) for production.
|
|
|
|
### 1. Backend Setup
|
|
Run the API and Data Gatherer.
|
|
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt update && sudo apt install python3-venv python3-pip
|
|
|
|
# Alpine
|
|
apk add python3 py3-pip
|
|
|
|
# Setup
|
|
cd /path/to/app/APP
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# Run (Manual testing)
|
|
python3 openvpn_api_v3.py &
|
|
python3 openvpn_gatherer_v3.py &
|
|
```
|
|
|
|
### 2. Frontend Setup
|
|
Build the SPA and deploy to your web server.
|
|
|
|
```bash
|
|
cd /path/to/app/UI/client
|
|
npm install
|
|
npm run build
|
|
|
|
# Deploy (Example)
|
|
sudo cp -r dist/* /var/www/html/
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠 Service Configuration
|
|
|
|
### Debian / Ubuntu (Systemd)
|
|
Create service files in `/etc/systemd/system/`.
|
|
|
|
**1. API Service (`/etc/systemd/system/ovpmon-api.service`)**
|
|
```ini
|
|
[Unit]
|
|
Description=OpenVPN Monitor API
|
|
After=network.target
|
|
|
|
[Service]
|
|
User=root
|
|
WorkingDirectory=/opt/ovpmon/APP
|
|
ExecStart=/opt/ovpmon/APP/venv/bin/python3 openvpn_api_v3.py
|
|
Restart=always
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
**2. Gatherer Service (`/etc/systemd/system/ovpmon-gatherer.service`)**
|
|
```ini
|
|
[Unit]
|
|
Description=OpenVPN Monitor Data Gatherer
|
|
After=network.target
|
|
|
|
[Service]
|
|
User=root
|
|
WorkingDirectory=/opt/ovpmon/APP
|
|
ExecStart=/opt/ovpmon/APP/venv/bin/python3 openvpn_gatherer_v3.py
|
|
Restart=always
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
**Enable & Start:**
|
|
```bash
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now ovpmon-api ovpmon-gatherer
|
|
```
|
|
|
|
### Alpine Linux (OpenRC)
|
|
For Alpine, create scripts in `/etc/init.d/` (e.g., `ovpmon-api`) using `openrc-run`.
|
|
```bash
|
|
#!/sbin/openrc-run
|
|
description="OpenVPN Monitor API"
|
|
command="/opt/ovpmon/APP/venv/bin/python3"
|
|
command_args="/opt/ovpmon/APP/openvpn_api_v3.py"
|
|
directory="/opt/ovpmon/APP"
|
|
command_background=true
|
|
pidfile="/run/ovpmon-api.pid"
|
|
```
|
|
Make executable (`chmod +x`) and start: `rc-service ovpmon-api start`.
|
|
|
|
---
|
|
|
|
## 🌐 Web Server Configuration
|
|
|
|
**Recommendation: Nginx** is preferred for its performance and simple SPA configuration (`try_files`).
|
|
|
|
### Nginx Config
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name vpn-monitor.local;
|
|
root /var/www/html;
|
|
index index.html;
|
|
|
|
# SPA Fallback
|
|
location / {
|
|
try_files $uri $uri/ /index.html;
|
|
}
|
|
|
|
# Proxy API requests (Optional, if not exposing 5001 directly)
|
|
location /api/ {
|
|
proxy_pass http://127.0.0.1:5001;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Apache Config
|
|
|
|
**Setup (Alpine Linux):**
|
|
```bash
|
|
apk add apache2 apache2-proxy
|
|
rc-service apache2 restart
|
|
```
|
|
|
|
**Setup (Debian/Ubuntu):**
|
|
```bash
|
|
sudo a2enmod rewrite proxy proxy_http
|
|
sudo systemctl restart apache2
|
|
```
|
|
|
|
Ensure `mod_rewrite`, `mod_proxy`, and `mod_proxy_http` are enabled.
|
|
|
|
**VirtualHost Config:**
|
|
```apache
|
|
<VirtualHost *:80>
|
|
DocumentRoot "/var/www/html"
|
|
<Directory "/var/www/html">
|
|
Options Indexes FollowSymLinks
|
|
AllowOverride All # CRITICAL for .htaccess
|
|
Require all granted
|
|
</Directory>
|
|
|
|
# Proxy API requests (Optional, if not exposing 5001 directly)
|
|
<Location "/api/">
|
|
ProxyPreserveHost On
|
|
ProxyPass "http://127.0.0.1:5001/api/"
|
|
ProxyPassReverse "http://127.0.0.1:5001/api/"
|
|
</Location>
|
|
</VirtualHost>
|
|
```
|
|
|
|
---
|
|
|
|
## 🧹 Database Management
|
|
|
|
### Resetting Statistics
|
|
To completely reset all traffic statistics and start fresh:
|
|
|
|
1. **Stop Services**:
|
|
```bash
|
|
# Systemd
|
|
sudo systemctl stop ovpmon-gatherer ovpmon-api
|
|
|
|
# OpenRC (Alpine)
|
|
rc-service ovpmon-gatherer stop
|
|
rc-service ovpmon-api stop
|
|
```
|
|
|
|
2. **Remove Database**:
|
|
Navigate to the application directory (e.g., `/opt/ovpmon/APP`) and delete or rename the database file:
|
|
```bash
|
|
rm openvpn_monitor.db
|
|
```
|
|
|
|
3. **Restart Services**:
|
|
The system will automatically recreate the database with a fresh schema.
|
|
```bash
|
|
# Systemd
|
|
sudo systemctl start ovpmon-gatherer ovpmon-api
|
|
|
|
# OpenRC (Alpine)
|
|
rc-service ovpmon-gatherer start
|
|
rc-service ovpmon-api start
|
|
```
|
|
|
|
### Advanced: Reset Stats (Keep Client List)
|
|
To reset counters but keep the known list of clients, run this SQL command:
|
|
```bash
|
|
sqlite3 openvpn_monitor.db "
|
|
DELETE FROM usage_history;
|
|
DELETE FROM stats_5min;
|
|
DELETE FROM stats_15min;
|
|
DELETE FROM stats_hourly;
|
|
DELETE FROM stats_6h;
|
|
DELETE FROM stats_daily;
|
|
DELETE FROM active_sessions;
|
|
UPDATE clients SET
|
|
total_bytes_received = 0,
|
|
total_bytes_sent = 0,
|
|
last_bytes_received = 0,
|
|
last_bytes_sent = 0,
|
|
status = 'Disconnected';
|
|
VACUUM;"
|
|
```
|
|
|
|
### Remove a Specific User
|
|
To completely remove a user (e.g., `UNDEF`) and their history:
|
|
```bash
|
|
sqlite3 openvpn_monitor.db "
|
|
DELETE FROM usage_history WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM stats_5min WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM stats_15min WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM stats_hourly WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM stats_6h WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM stats_daily WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM active_sessions WHERE client_id IN (SELECT id FROM clients WHERE common_name = 'UNDEF');
|
|
DELETE FROM clients WHERE common_name = 'UNDEF';
|
|
VACUUM;"
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 API Reference
|
|
|
|
**Base URL:** `http://<server-ip>:5001/api/v1`
|
|
|
|
| Method | Endpoint | Description |
|
|
| :--- | :--- | :--- |
|
|
| **GET** | `/stats` | Current status of all clients (Real-time). |
|
|
| **GET** | `/stats/system` | Server-wide totals (Total traffic, active count). |
|
|
| **GET** | `/stats/<common_name>` | Detailed client stats + History. Params: `range` (24h, 7d), `resolution`. |
|
|
| **GET** | `/certificates` | List of all certificates with expiration status. **Cached (Fast)**. |
|
|
| **GET** | `/analytics` | Dashboard data (Trends, Traffic distribution, Top clients). |
|
|
| **GET** | `/health` | API Health check. |
|
|
|
|
---
|
|
*Generated by Antigravity Agent*
|