new awesome build
This commit is contained in:
Антон
236
DOCS/Core_Monitoring/API_Reference.md
Normal file
236
DOCS/Core_Monitoring/API_Reference.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# OpenVPN Monitor API v3 Documentation
|
||||
|
||||
This API provides access to OpenVPN monitoring data, including real-time client status and historical data stored in a Time Series Database (TSDB). It features optimized aggregation for fast visualization.
|
||||
|
||||
**Base URL:** `http://<your-server-ip>:5001/api/v1`
|
||||
|
||||
---
|
||||
|
||||
## 1. Global Analytics (Dashboard)
|
||||
|
||||
Provides aggregated trend data for the entire server. optimized for visualization with exactly **96 data points** regardless of the time range.
|
||||
|
||||
### `GET /analytics`
|
||||
|
||||
#### Query Parameters
|
||||
| Parameter | Type | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `range` | string | `24h` | Time range. Supported: `24h`, `7d`, `30d`. |
|
||||
|
||||
#### Behavior
|
||||
* **24h**: Returns 15-minute intervals.
|
||||
* **7d**: Returns 105-minute intervals (1h 45m).
|
||||
* **30d**: Returns 450-minute intervals (7h 30m).
|
||||
* **Zero-Filling**: Missing data periods are automatically filled with zeros to ensure graph continuity.
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"timestamp": "2026-01-09 12:00:00",
|
||||
"range": "24h",
|
||||
"data": {
|
||||
"global_history_24h": [
|
||||
{
|
||||
"timestamp": "2026-01-09 11:45:00",
|
||||
"total_rx": 102400,
|
||||
"total_tx": 51200,
|
||||
"active_count": 5
|
||||
},
|
||||
...
|
||||
],
|
||||
"max_concurrent_24h": 12,
|
||||
"top_clients_24h": [ ... ],
|
||||
"traffic_distribution": { "rx": 1000, "tx": 500 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Client Statistics (Detail + History)
|
||||
|
||||
Main endpoint for individual client reports. Supports **Dynamic Aggregation** to optimize payload size (~98% reduction for 24h view).
|
||||
|
||||
### `GET /stats/<common_name>`
|
||||
|
||||
#### Query Parameters
|
||||
| Parameter | Type | Default | Description |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `range` | string | `24h` | Time range. Formats: `1h`, `3h`, `6h`, `12h`, `24h`, `7d`, `30d`. |
|
||||
| `resolution` | string | `auto` | Force resolution (optional): `raw`, `5min`, `hourly`, `auto`. |
|
||||
|
||||
#### Dynamic Aggregation Logic (`resolution=auto`)
|
||||
The API automatically selects the aggregation interval based on the requested range to balance detail and performance:
|
||||
|
||||
| Range | Resolution | Points | Source Table |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **1h** | **30 sec** | 120 | `usage_history` (Raw) |
|
||||
| **3h** | **1 min** | 180 | `usage_history` (Raw) |
|
||||
| **6h** | **2 min** | 180 | `usage_history` (Raw) |
|
||||
| **12h** | **5 min** | 144 | `usage_history` (Raw) |
|
||||
| **24h** | **15 min** | 96 | `usage_history` (Raw) |
|
||||
| **7d** | **1 Hour** | 168 | `stats_hourly` |
|
||||
| **30d** | **6 Hours** | 120 | `stats_6h` |
|
||||
|
||||
*All short-term ranges (≤24h) include automatic **Zero-Filling**.*
|
||||
|
||||
#### Examples: Long-Term Aggregated Data
|
||||
|
||||
To explicitly request data from long-term storage tables (skipping raw data), use the `resolution` parameter or specific ranges.
|
||||
|
||||
**1. Last 7 Days (Hourly Resolution)**
|
||||
Uses `stats_hourly` table. Reduced precision for weekly trends.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d
|
||||
```
|
||||
*or explicit resolution:*
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=7d&resolution=hourly
|
||||
```
|
||||
|
||||
**2. Last 30 Days (6-Hour Resolution)**
|
||||
Uses `stats_6h` table. Ideal for monthly volume analysis.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=30d
|
||||
```
|
||||
|
||||
**3. Last 1 Year (Daily Resolution)**
|
||||
Uses `stats_daily` table. Extremely lightweight for annual reporting.
|
||||
```http
|
||||
GET /api/v1/stats/user-alice?range=1y&resolution=daily
|
||||
```
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"current_rates": { "recv_mbps": 1.5, "sent_mbps": 0.2 },
|
||||
"totals": { "received_mb": 500.25, "sent_mb": 120.10 },
|
||||
"history": [
|
||||
{
|
||||
"timestamp": "2026-01-09 11:30:00",
|
||||
"bytes_received": 5000,
|
||||
"bytes_sent": 2000,
|
||||
"bytes_received_rate_mbps": 0.5,
|
||||
"bytes_sent_rate_mbps": 0.1
|
||||
},
|
||||
...
|
||||
],
|
||||
"meta": {
|
||||
"resolution_used": "usage_history_hires",
|
||||
"record_count": 120
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Current Statistics (All Clients)
|
||||
|
||||
Returns a snapshot of all known clients.
|
||||
|
||||
### `GET /stats`
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"count": 2,
|
||||
"data": [
|
||||
{
|
||||
"common_name": "user-alice",
|
||||
"status": "Active",
|
||||
"current_recv_rate_mbps": 1.5,
|
||||
"total_received_mb": 500.2
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. System Statistics
|
||||
|
||||
Aggregated metrics for the Server.
|
||||
|
||||
### `GET /stats/system`
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"total_clients": 15,
|
||||
"active_clients": 3,
|
||||
"total_received_gb": 10.0,
|
||||
"total_sent_gb": 5.0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Certificates
|
||||
|
||||
SSL Certificate expiration tracking.
|
||||
|
||||
### `GET /certificates`
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": [
|
||||
{
|
||||
"file": "user-alice.crt",
|
||||
"days_remaining": "360 days",
|
||||
"is_expired": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Utility Methods
|
||||
|
||||
### `GET /clients`
|
||||
Simple list of clients (Common Name + Status) for UI dropdowns.
|
||||
|
||||
### `GET /health`
|
||||
Database connectivity check. Returns `{"status": "healthy"}`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Active Sessions
|
||||
|
||||
Real-time list of currently connected clients.
|
||||
|
||||
### `GET /sessions`
|
||||
|
||||
#### Example Response
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"count": 1,
|
||||
"data": [
|
||||
{
|
||||
"client_id": 5,
|
||||
"common_name": "user-bob",
|
||||
"real_address": "192.168.1.50",
|
||||
"connected_since": "2026-01-09 10:00:00",
|
||||
"last_seen": "2026-01-09 12:00:00",
|
||||
"bytes_received": 1048576,
|
||||
"bytes_sent": 524288,
|
||||
"received_mb": 1.0,
|
||||
"sent_mb": 0.5
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
114
DOCS/Core_Monitoring/Authentication.md
Normal file
114
DOCS/Core_Monitoring/Authentication.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Процесс аутентификации в OpenVPN Monitor
|
||||
|
||||
Аутентификация в приложении реализована с использованием **Flask** и **JWT (JSON Web Tokens)**. Ниже приведено подробное описание механизмов и примеры использования API из консоли.
|
||||
|
||||
---
|
||||
|
||||
## 1. Логика работы
|
||||
|
||||
Механизм аутентификации поддерживает два режима: стандартный вход и вход с двухфакторной аутентификацией (2FA).
|
||||
|
||||
### Основные этапы:
|
||||
1. **Запрос на вход (`POST /api/auth/login`)**:
|
||||
* Клиент отправляет `username` и `password`.
|
||||
* Сервер проверяет хеш пароля с использованием **BCrypt**.
|
||||
* **Защита (Rate Limiting)**: После 5 неудачных попыток IP-адрес блокируется на 15 минут.
|
||||
2. **Выдача токена**:
|
||||
* **Если 2FA отключена**: Сервер возвращает финальный JWT-токен (валиден 8 часов).
|
||||
* **Если 2FA включена**: Сервер возвращает `temp_token` (валиден 5 минут) и флаг `requires_2fa: true`.
|
||||
3. **Верификация 2FA (`POST /api/auth/verify-2fa`)**:
|
||||
* Клиент отправляет `temp_token` и 6-значный код (OTP).
|
||||
* Сервер проверяет код с помощью библиотеки `pyotp`.
|
||||
* При успешной проверке выдается финальный JWT-токен.
|
||||
|
||||
---
|
||||
|
||||
## 2. Использование API через консоль
|
||||
|
||||
Для выполнения прямых вызовов API необходимо получить JWT-токен и передавать его в заголовке `Authorization`.
|
||||
|
||||
### Шаг 1: Аутентификация
|
||||
|
||||
#### Вариант А: 2FA отключена
|
||||
Выполните запрос для получения токена:
|
||||
```bash
|
||||
curl -X POST http://<SERVER_IP>:5001/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "ваш_пароль"}'
|
||||
```
|
||||
В ответе придет JSON с полем `"token"`.
|
||||
|
||||
#### Вариант Б: 2FA включена (двухэтапный вход)
|
||||
1. Получите временный токен:
|
||||
```bash
|
||||
curl -X POST http://<SERVER_IP>:5001/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username": "admin", "password": "ваш_пароль"}'
|
||||
```
|
||||
Скопируйте `temp_token` из ответа.
|
||||
|
||||
2. Подтвердите вход кодом OTP:
|
||||
```bash
|
||||
curl -X POST http://<SERVER_IP>:5001/api/auth/verify-2fa \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"temp_token": "ВАШ_TEMP_TOKEN", "otp": "123456"}'
|
||||
```
|
||||
Скопируйте финальный `token` из ответа.
|
||||
|
||||
### Шаг 2: Вызов защищенных методов
|
||||
|
||||
Используйте полученный токен в заголовке `Bearer`:
|
||||
|
||||
**Пример: Получение списка клиентов**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
|
||||
http://<SERVER_IP>:5001/api/v1/stats
|
||||
```
|
||||
|
||||
**Пример: Просмотр сертификатов**
|
||||
```bash
|
||||
curl -H "Authorization: Bearer ВАШ_ТОКЕН" \
|
||||
http://<SERVER_IP>:5001/api/v1/certificates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Быстрое получение токена из браузера
|
||||
|
||||
Если вы уже вошли в веб-интерфейс, токен можно быстро скопировать без лишних запросов:
|
||||
1. Откройте панель разработчика (**F12**).
|
||||
2. Перейдите на вкладку **Application** (или **Storage**).
|
||||
4. Найдите ключ `ovpmon_token` — это и есть ваш текущий JWT-токен.
|
||||
|
||||
---
|
||||
|
||||
## 4. Account Management & 2FA Configuration
|
||||
|
||||
Endpoints for managing the current user's security settings.
|
||||
|
||||
### User Profile
|
||||
`GET /api/v1/user/me`
|
||||
Returns current user info and 2FA status.
|
||||
```json
|
||||
{ "success": true, "username": "admin", "is_2fa_enabled": false }
|
||||
```
|
||||
|
||||
### Password Change
|
||||
`POST /api/auth/change-password`
|
||||
**Payload**: `{"current_password": "old", "new_password": "new"}`
|
||||
|
||||
### 2FA Setup Flow
|
||||
|
||||
1. **Initiate Setup**
|
||||
`POST /api/auth/setup-2fa`
|
||||
Returns a secret and a `otpauth://` URI for QR code generation.
|
||||
|
||||
2. **Enable 2FA**
|
||||
`POST /api/auth/enable-2fa`
|
||||
**Payload**: `{"secret": "GENERATED_SECRET", "otp": "123456"}`
|
||||
Verifies the code and enables 2FA for the user.
|
||||
|
||||
3. **Disable 2FA**
|
||||
`POST /api/auth/disable-2fa`
|
||||
Disables 2FA (No payload required).
|
||||
|
||||
45
DOCS/Core_Monitoring/Data_Architecture.md
Normal file
45
DOCS/Core_Monitoring/Data_Architecture.md
Normal file
@@ -0,0 +1,45 @@
|
||||
# OpenVPN Data Gatherer Analysis
|
||||
|
||||
This report details the internal mechanics of `openvpn_gatherer_v3.py`, responsible for collecting, processing, and storing OpenVPN usage metrics.
|
||||
|
||||
## 1. Raw Data Collection (`run_monitoring_cycle`)
|
||||
|
||||
The gatherer runs a continuous loop (default interval: **10 seconds**).
|
||||
|
||||
### A. Log Parsing
|
||||
- **Source**: `/var/log/openvpn/openvpn-status.log` (Status File v2, CSV format).
|
||||
- **Target Fields**: `Common Name`, `Real Address`, `Bytes Sent`, `Bytes Received`.
|
||||
- **Filtering**: Only lines starting with `CLIENT_LIST`.
|
||||
|
||||
### B. Delta Calculation (`update_client_status_and_bytes`)
|
||||
The log provides *lifetime* counters for a session. The gatherer calculates the traffic *delta* (increment) since the last check.
|
||||
- **Logic**: `Increment = Current Value - Last Saved Value`.
|
||||
- **Reset Detection**: If `Current Value < Last Saved Value`, it assumes a session/server restart and counts the entire `Current Value` as the increment.
|
||||
|
||||
### C. Rate Calculation
|
||||
- **Speed**: Calculated as `Increment * 8 / (Interval * 1_000_000)` to get **Mbps**.
|
||||
- **Storage**: Raw samples (10s resolution) including speed and volume are stored in the `usage_history` table.
|
||||
|
||||
## 2. Data Aggregation (TSDB)
|
||||
|
||||
To support long-term statistics without storing billions of rows, the `TimeSeriesAggregator` performs real-time rollups into 5 aggregated tables using an `UPSERT` strategy (Insert or update sum).
|
||||
|
||||
| Table | Resolution | Timestamp Alignment | Retention (Default) |
|
||||
|-------|------------|---------------------|---------------------|
|
||||
| `usage_history` | **10 sec** | Exact time | 7 Days |
|
||||
| `stats_5min` | **5 min** | 00:00, 00:05... | 14 Days |
|
||||
| `stats_15min` | **15 min** | 00:00, 00:15... | 28 Days |
|
||||
| `stats_hourly` | **1 Hour** | XX:00:00 | 90 Days |
|
||||
| `stats_6h` | **6 Hours** | 00:00, 06:00, 12:00... | 180 Days |
|
||||
| `stats_daily` | **1 Day** | 00:00:00 | 365 Days |
|
||||
|
||||
**Logic**: Every 10s cycle, the calculated `Increment` is added to the sum of *all* relevant overlapping buckets. A single 5MB download contributes immediately to the current 5min, 15min, Hourly, 6h, and Daily counters simultaneously.
|
||||
|
||||
## 3. Data Retention
|
||||
|
||||
A cleanup job runs once every 24 hours (on day change).
|
||||
- It executes `DELETE FROM table WHERE timestamp < cutoff_date`.
|
||||
- Thresholds are configurable in `APP_CORE/config.ini` under `[retention]`.
|
||||
|
||||
## Summary
|
||||
The system employs a "Write-Optimized" approach. Instead of calculating heavy aggregates on-read (which would be slow), it pre-calculates them on-write. This ensures instant dashboard loading times even with years of historical data.
|
||||
Reference in New Issue
Block a user