mirror of
https://github.com/LibreQoE/LibreQoS.git
synced 2026-11-03 12:47:03 -06:00
150 lines
5.2 KiB
Markdown
150 lines
5.2 KiB
Markdown
# API del Nodo de LibreQoS
|
|
|
|
## Requisitos
|
|
|
|
El servicio `lqos_api` (API del nodo) requiere una suscripción activa a LibreQoS Insight.
|
|
|
|
Esto es independiente de los límites base de shaping:
|
|
- `ShapedDevices.csv` puede contener entradas ilimitadas.
|
|
- Sin una suscripción/licencia Insight válida, LibreQoS admite solo los primeros 1000 circuitos mapeados válidos al estado de shaping activo.
|
|
- Conteos superiores de circuitos mapeados dependen de una licencia Insight activa.
|
|
|
|
## Fuente de verdad y pruebas
|
|
|
|
Use Swagger en su nodo como referencia completa y superficie de prueba para la versión instalada:
|
|
|
|
- Puerto local directo de la API: `http://<node-ip>:9122/api-docs`
|
|
- Si la WebUI usa HTTPS opcional con Caddy: `https://<hostname-o-ip-del-nodo>/api/v1/api-docs`
|
|
|
|
En sistemas que usan HTTPS con Caddy gestionado, deje el listener de la API en loopback y acceda a la API mediante `/api/v1/`. `LQOS_API_LISTEN` es un override avanzado para despliegues que exponen intencionalmente el listener de la API en forma directa; no lo configure en sistemas con Caddy gestionado salvo que la exposición directa, el firewall, TLS y los controles de acceso de operadores se hayan planificado juntos.
|
|
|
|
Use esta página como mapa de capacidades. Use Swagger para inventario completo de endpoints, esquemas request/response y pruebas en vivo.
|
|
|
|
¿Necesita definiciones de persistencia e impacto en runtime? Vea el [Glosario](glossary-es.md).
|
|
|
|
## Instalar y habilitar
|
|
|
|
Si instaló vía `.deb` (recomendado), `lqos_api` ya está en:
|
|
|
|
- `/opt/libreqos/src/bin/lqos_api`
|
|
|
|
Habilitar servicio:
|
|
|
|
```bash
|
|
sudo cp /opt/libreqos/src/bin/lqos_api.service.example /etc/systemd/system/lqos_api.service
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable lqos_api
|
|
sudo systemctl start lqos_api
|
|
```
|
|
|
|
La plantilla incluida de `lqos_api.service.example` espera `network-online.target`, para que la API no arranque antes de que DNS y la ruta por defecto esten listas.
|
|
|
|
Actualizar solo el binario de la API:
|
|
|
|
```bash
|
|
cd /opt/libreqos/src
|
|
./update_api.sh
|
|
```
|
|
|
|
Verificar estado del servicio:
|
|
|
|
```bash
|
|
sudo systemctl status lqos_api
|
|
```
|
|
|
|
## Autenticación
|
|
|
|
La mayoría de endpoints requieren:
|
|
|
|
- Header: `x-bearer`
|
|
- Valor: su clave de licencia Insight
|
|
|
|
## Qué pueden hacer los ISPs con la API
|
|
|
|
### 1) Ciclo de vida de suscriptores/circuitos
|
|
|
|
Aprovisionar, actualizar y eliminar registros de suscriptor/dispositivo.
|
|
|
|
- Alta o reemplazo:
|
|
- `POST /overrides/persistent_devices`
|
|
- `POST /shaped_devices/update`
|
|
- Ajustes de velocidad:
|
|
- `POST /overrides/adjustments/circuit_speed`
|
|
- `POST /overrides/adjustments/device_speed`
|
|
- Bajas:
|
|
- `DELETE /overrides/persistent_devices/by_circuit/{circuit_id}`
|
|
- `DELETE /overrides/persistent_devices/by_device/{device_id}`
|
|
- `POST /overrides/adjustments/remove_circuit`
|
|
- `POST /overrides/adjustments/remove_device`
|
|
|
|
### 2) Gestión de overrides y políticas
|
|
|
|
Mantener políticas persistentes para circuitos, dispositivos, sitios y overrides específicos de UISP.
|
|
|
|
- `GET/POST/DELETE /overrides/adjustments*`
|
|
- `GET/POST/DELETE /overrides/network_adjustments*`
|
|
- `GET/POST/DELETE /overrides/uisp/bandwidth*`
|
|
- `GET/POST/DELETE /overrides/uisp/routes*`
|
|
|
|
### 3) Topología y archivos de entrada de shaping
|
|
|
|
Inspeccionar y actualizar archivos de topología/shaping usados por los flujos de runtime.
|
|
|
|
- `GET /network_json/json`
|
|
- `GET /network_json/text`
|
|
- `POST /network_json/update`
|
|
- `POST /network_json/set_site_speed`
|
|
- `POST /network_json/set_site_speed_batch`
|
|
- `GET /shaped_devices`
|
|
- `POST /shaped_devices/update`
|
|
|
|
### 4) Monitoreo y diagnóstico
|
|
|
|
Leer estado de salud, scheduler, throughput, flujos, colas y circuitos.
|
|
|
|
Endpoints representativos:
|
|
- `GET /health`
|
|
- `GET /status_snapshot`
|
|
- `GET /scheduler_status`
|
|
- `GET /circuit/{circuit_id}`
|
|
- `GET /search`
|
|
- `GET /current_throughput`
|
|
- `GET /queue_stats_total`
|
|
- `GET /warnings`
|
|
- `GET /urgent`, `GET /urgent/status`
|
|
|
|
### 5) Operaciones de control y reload
|
|
|
|
Disparar acciones de control operativo cuando sea necesario.
|
|
|
|
- `POST /reload_libreqos`
|
|
- `POST /clear_hot_cache`
|
|
|
|
Trátelas como operaciones de mayor riesgo en producción.
|
|
|
|
## Modelo de persistencia (importante)
|
|
|
|
No todas las escrituras persisten del mismo modo:
|
|
|
|
- `overrides/*`: estado de política persistente.
|
|
- `network_json/set_site_speed*`: ediciones transitorias.
|
|
- `network_json/update` y `shaped_devices/update`: reemplazo directo de archivos, generalmente sobrescribible por integración.
|
|
|
|
Si hay integraciones habilitadas, sus ciclos de refresco pueden sobrescribir ediciones directas de archivos.
|
|
|
|
## Flujo recomendado para producción
|
|
|
|
1. Validar comportamiento del endpoint y esquema de payload en Swagger.
|
|
2. Aplicar el cambio mínimo necesario.
|
|
3. Verificar resultado con checks de solo lectura (`/health`, `/scheduler_status`, vistas de circuito/throughput).
|
|
4. Mantener snapshots de rollback para operaciones que cambien config/datos.
|
|
|
|
## Hardening de despliegue
|
|
|
|
- Limite acceso de API a redes de gestión confiables.
|
|
- No exponga la API directamente a Internet público.
|
|
- Si necesita acceso remoto, use reverse proxy con TLS y autenticación.
|
|
- Restrinja acceso entrante con allowlists de firewall.
|
|
|
|
Si quiere que la WebUI y la documentación de la API compartan el mismo origen HTTPS, vea [HTTPS opcional con Caddy](https-caddy-es.md).
|