OpenVPN-Monitoring-Simple/README.md

# OpenVPN Monitor & Profiler

Web suite for OpenVPN servers: real-time traffic monitoring, history/analytics, PKI and client-profile management, one UI.

| Component | Dir | Stack | Default port |
|---|---|---|---|
| UI | `APP_UI/` | Vue 3 + Vite, served by Nginx | 80 (Docker) / 8088 (native, TLS) |
| Monitoring API | `APP_CORE/` | Flask (gunicorn) | 5001 (internal) |
| Data gatherer | `APP_CORE/` | Python daemon | - |
| Profiler API | `APP_PROFILER/` | FastAPI (uvicorn) | 8000 (internal) |

Nginx is the only public entry point: `/` UI, `/api/` Monitoring API, `/profiles-api/` Profiler API.

## Quick start

- **Containers:** `docker-compose up -d --build`, open `http://<host>`. Details: [Deployment: Docker](DOCS/General/Deployment_Docker.md).
- **System services** (systemd / OpenRC, no containers): [Deployment: native](DOCS/General/Deployment_Native.md).

After the first start: sign in, open **PKI Configuration** → **Initialize PKI**, generate the server config, start OpenVPN, create profiles.

## First login and credentials

No default user is created. Seed the initial admin with `OVPMON_INITIAL_ADMIN_USER` / `OVPMON_INITIAL_ADMIN_PASSWORD` on first start (empty `users` table only), then remove them. Change the username and password and enable 2FA in **Account**.

## Security defaults

- No built-in account; the username can be changed in **Account** (API `POST /api/auth/change-username`).
- All API routes require a JWT; 2FA-pending tokens are accepted only by `/api/auth/verify-2fa`.
- Server/PKI settings are validated before they reach `server.conf` (ports, networks, routes, DNS, host names, script paths, DN fields); scripts run only from `/etc/openvpn/scripts/`.
- Native deployments: APIs run as user `ovpmon`; a root helper installs the validated `server.conf`, publishes the CRL (`crl_verify`) and controls `openvpn` through `doas` (fixed commands).
- CORS is same-origin only unless `OVPMON_CORS_ORIGINS` is set; TLS on the panel port; brute-force limits on login (Nginx + app, fail2ban jail in the deployment guide).

## Configuration

`config.ini` per component; overridden by `OVPMON_{SECTION}_{KEY}` environment variables.

| Variable | Purpose |
|---|---|
| `OVPMON_API_SECRET_KEY` | JWT secret shared by both APIs (**must be random**) |
| `OVPMON_INITIAL_ADMIN_USER` / `_PASSWORD` | One-time admin seed |
| `OVPMON_CORS_ORIGINS` | Extra allowed CORS origins, comma-separated (empty = same-origin only) |
| `OVPMON_OPENVPN_MONITOR_DB_PATH` | Monitoring DB |
| `OVPMON_PROFILER_DB_PATH` | Profiler DB |
| `OVPMON_OPENVPN_MONITOR_LOG_PATH` | `openvpn-status.log` path |
| `OVPMON_LOGGING_LEVEL` | `INFO` / `DEBUG` |

## Documentation

- Index: [DOCS/General/Index.md](DOCS/General/Index.md)
- Deployment: [Docker](DOCS/General/Deployment_Docker.md) · [System services](DOCS/General/Deployment_Native.md) · [Nginx](DOCS/General/Nginx_Configuration.md) · [Service management](DOCS/General/Service_Management.md)
- Deployment records (state, results, reboot test, plans): [DOCS/Operations](DOCS/Operations/README.md)
- Security model: [Security Architecture](DOCS/General/Security_Architecture.md) · root helper and doas rules: [`DOCS/General/privilege-separation/`](DOCS/General/privilege-separation/)
- APIs: [Monitoring](DOCS/Core_Monitoring/API_Reference.md) · [Profiler](DOCS/Profiler_Management/API_Reference.md)

## Changes and results

| Date | Change | Document |
|---|---|---|
| 2026-09-30 | Security hardening: path traversal, 2FA token bypass, CORS, log leak, HTTPS, SSH, fail2ban | [Security hardening](DOCS/Changes/2026-09-30_Security_Hardening.md) |
| 2026-09-30 | Admin username change (API + UI), no built-in default admin | [Admin username change](DOCS/Changes/2026-09-30_Admin_Username_Change.md) |
| 2026-09-30 | Validation of server/PKI settings (config injection into the root-written OpenVPN config) | [Settings validation](DOCS/Changes/2026-09-30_Settings_Validation.md) |
| 2026-09-30 | API services run as an unprivileged user; root helper validates and installs the OpenVPN config, publishes the CRL | [Privilege separation](DOCS/Changes/2026-09-30_Privilege_Separation.md) (includes CRL publishing for `crl_verify`) |
| 2026-09-30 | Route OpenVPN clients through a Hysteria2 tunnel to an exit node | [Egress via Hysteria2](DOCS/Changes/2026-09-30_Egress_via_Hysteria2.md) |

## Notes

- Native deployments run the APIs as user `ovpmon`; OpenVPN config install and service control go through a root helper (`doas`, fixed commands): see [Privilege separation](DOCS/Changes/2026-09-30_Privilege_Separation.md).
- Keep `easy-rsa/`, `client-config/`, databases and `*.env` out of git: they contain private keys and secrets.