OpenVPN-Monitoring-Simple/README.md

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.

# 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.

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)

[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)

[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:

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.

#!/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

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):

apk add apache2 apache2-proxy
rc-service apache2 restart

Setup (Debian/Ubuntu):

sudo a2enmod rewrite proxy proxy_http
sudo systemctl restart apache2

Ensure mod_rewrite, mod_proxy, and mod_proxy_http are enabled.

VirtualHost Config:

<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:

   # 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:

   rm openvpn_monitor.db
   

3. Restart Services: The system will automatically recreate the database with a fresh schema.

   # 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:

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:

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