From c7de842f66a70fe74b548e62c814b93c6501a44d Mon Sep 17 00:00:00 2001 From: Robert Chacon Date: Wed, 25 Feb 2026 16:45:04 -0700 Subject: [PATCH] changes --- .github/workflows/docs.yml | 18 +++ docs-es/index.rst | 6 + docs-es/v2.0/api-es.md | 164 ++++++++++++++++------ docs-es/v2.0/components-es.md | 108 ++++++++------- docs-es/v2.0/insight-es.md | 31 +++++ docs-es/v2.0/integrations-es.md | 65 +++++++++ docs-es/v2.0/lts-es.md | 44 ++---- docs-es/v2.0/node-manager-ui-es.md | 76 +++++++++++ docs-es/v2.0/performance-tuning-es.md | 75 +++++++--- docs-es/v2.0/scale-topology-es.md | 73 ++++++++++ docs-es/v2.0/stormguard-es.md | 74 ++++++++++ docs-es/v2.0/troubleshooting-es.md | 190 +++++++++++++++++--------- docs/v2.0/api.md | 117 +++++++++++++--- docs/v2.0/components.md | 33 +++++ docs/v2.0/configuration.md | 77 +++++++++++ docs/v2.0/git-install.md | 2 +- docs/v2.0/insight.md | 28 ++++ docs/v2.0/integrations.md | 66 ++++++++- docs/v2.0/lts.md | 45 ++---- docs/v2.0/node-manager-ui.md | 76 +++++++++++ docs/v2.0/performance-tuning.md | 71 ++++++++-- docs/v2.0/scale-topology.md | 73 ++++++++++ docs/v2.0/share.md | 35 ----- docs/v2.0/stormguard.md | 76 +++++++++++ docs/v2.0/troubleshooting.md | 80 +++++++++++ docs/v2.0/update.md | 16 ++- index.rst | 5 + 27 files changed, 1414 insertions(+), 310 deletions(-) create mode 100644 .github/workflows/docs.yml create mode 100644 docs-es/v2.0/node-manager-ui-es.md create mode 100644 docs-es/v2.0/scale-topology-es.md create mode 100644 docs-es/v2.0/stormguard-es.md create mode 100644 docs/v2.0/node-manager-ui.md create mode 100644 docs/v2.0/scale-topology.md delete mode 100644 docs/v2.0/share.md create mode 100644 docs/v2.0/stormguard.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..e5dd98ef --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,18 @@ +name: Docs + +on: [pull_request, push] + +jobs: + docs: + runs-on: lq_run + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + - name: Install docs dependencies + run: | + python -m pip install --upgrade pip + python -m pip install sphinx myst-parser sphinx-rtd-theme + - name: Build docs (warnings as errors) + run: sphinx-build -b html -n -W . _build/html diff --git a/docs-es/index.rst b/docs-es/index.rst index 51ef5120..5b65a1ae 100644 --- a/docs-es/index.rst +++ b/docs-es/index.rst @@ -13,6 +13,7 @@ Bienvenido a la documentación de LibreQoS v2.0/ubuntu-server-es v2.0/bridge-es v2.0/quickstart-es + v2.0/git-install-es .. toctree:: :maxdepth: 1 @@ -21,6 +22,9 @@ Bienvenido a la documentación de LibreQoS v2.0/configuration-es v2.0/integrations-es v2.0/components-es + v2.0/node-manager-ui-es + v2.0/stormguard-es + v2.0/scale-topology-es v2.0/update-es v2.0/troubleshooting-es @@ -30,10 +34,12 @@ Bienvenido a la documentación de LibreQoS v2.0/insight-es v2.0/api-es + v2.0/lts-es .. toctree:: :maxdepth: 1 :caption: Misceláneo v2.0/cake-es + v2.0/performance-tuning-es v2.0/extras-es diff --git a/docs-es/v2.0/api-es.md b/docs-es/v2.0/api-es.md index fe1ce0da..81301d1e 100644 --- a/docs-es/v2.0/api-es.md +++ b/docs-es/v2.0/api-es.md @@ -1,33 +1,65 @@ # API del Nodo de LibreQoS ## Requisitos -La API de nodo LibreQoS requiere una suscripción activa a LibreQoS Insight. + +La API del nodo LibreQoS requiere una suscripción activa a LibreQoS Insight. ## Instalación -### Descarga +### Si instaló vía `.deb` (recomendado) -``` -cd ~ -sudo apt-get update -sudo apt-get upgrade -wget https://libreqos.io/wp-content/uploads/2025/09/lqos_api.zip -sudo apt-get install unzip -sudo mkdir /opt/lqos_api/ -sudo chown -R $USER /opt/lqos_api/ -cd /opt/lqos_api/ -unzip lqos_api.zip -``` +`lqos_api` se instala con LibreQoS en: + +`/opt/libreqos/src/bin/lqos_api` ### Ejecución de prueba -``` -cd /opt/lqos_api/ -./lqos_api + +```bash +/opt/libreqos/src/bin/lqos_api ``` ### Servicio systemd -Si la ejecución de prueba funciona correctamente, use `sudo nano /etc/systemd/system/lqos_api.service` y pegue el siguiente contenido: +El paquete incluye un archivo de servicio de ejemplo: + +```bash +sudo cp /opt/libreqos/src/bin/lqos_api.service.example /etc/systemd/system/lqos_api.service +``` + +Luego ejecute: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable lqos_api +sudo systemctl start lqos_api +``` + +### Actualizar solo el binario de la API + +Use el script de ayuda: + +```bash +cd /opt/libreqos/src +./update_api.sh +``` + +Esto descarga el `lqos_api` más reciente e instala en `/opt/libreqos/src/bin/lqos_api`. + +Puede omitir el reinicio del servicio: + +```bash +./update_api.sh --no-restart +``` + +O instalar en otra ruta: + +```bash +./update_api.sh --bin-dir /alguna/ruta/bin --no-restart +``` + +### Archivo de servicio manual (si es necesario) + +Si crea el servicio manualmente, use: ``` [Unit] @@ -35,15 +67,17 @@ After=network.service lqosd.service Requires=lqosd.service [Service] -WorkingDirectory=/opt/lqos_api/ -ExecStart=/opt/lqos_api/lqos_api +WorkingDirectory=/opt/libreqos/src/bin +ExecStart=/opt/libreqos/src/bin/lqos_api Restart=always [Install] WantedBy=default.target ``` + Luego ejecute: -``` + +```bash sudo systemctl daemon-reload sudo systemctl enable lqos_api sudo systemctl start lqos_api @@ -51,42 +85,66 @@ sudo systemctl start lqos_api ## Uso -Vea `localhost:9122/api-docs` para la interfaz de Swagger UI. +Vea `localhost:9122/api-docs` para la interfaz Swagger. + +`/api-docs` es la fuente de verdad para su versión instalada. La disponibilidad de endpoints puede cambiar entre versiones. + +## Guía de despliegue y hardening + +Postura recomendada para producción: + +1. Mantenga la API accesible solo desde redes de gestión confiables. +2. No exponga la API directamente a Internet público. +3. Si requiere acceso remoto, publíquela detrás de un reverse proxy con TLS y autenticación. +4. Restrinja acceso entrante con allowlists de firewall (host/red). +5. Monitoree logs de API/servicio para detectar accesos anómalos. + +Si la API no se necesita en un nodo, deshabilite el servicio: + +```bash +sudo systemctl disable --now lqos_api +``` + +Si está habilitada, verifique el estado tras actualizaciones: + +```bash +sudo systemctl status lqos_api +``` ## Endpoints de la API ### Salud y sistema -- `/health` - Comprobación de salud del servicio -- `/reload_libreqos` - Recargar la configuración de LibreQoS -- `/validate_shaped_devices` - Validar el CSV de dispositivos modelados -- `/lqos_stats` - Obtener estadísticas internas de lqosd -- `/stormguard_stats` - Obtener estadísticas de Stormguard -- `/bakery_stats` - Obtener el recuento de circuitos activos de Bakery +- `/health` - Verificación de salud del servicio +- `/reload_libreqos` - Recarga configuración de LibreQoS +- `/validate_shaped_devices` - Valida CSV de Shaped Devices +- `/lqos_stats` - Estadísticas internas de lqosd +- `/stormguard_stats` - Estadísticas de StormGuard +- `/bakery_stats` - Conteo de circuitos activos de Bakery ### Métricas de tráfico -- `/current_throughput` - Estadísticas actuales de rendimiento de la red -- `/top_n_downloaders/{start}/{end}` - Descargadores principales por tráfico -- `/worst_rtt/{start}/{end}` - Hosts con peor tiempo de ida y vuelta (RTT) +- `/current_throughput` - Throughput actual de red +- `/top_n_downloaders/{start}/{end}` - Top descargadores por tráfico +- `/worst_rtt/{start}/{end}` - Hosts con peor RTT - `/worst_retransmits/{start}/{end}` - Hosts con más retransmisiones TCP -- `/best_rtt/{start}/{end}` - Hosts con mejor tiempo de ida y vuelta (RTT) -- `/host_counter` - Todos los contadores de tráfico por host +- `/best_rtt/{start}/{end}` - Hosts con mejor RTT +- `/host_counter` - Contadores de tráfico por host ### Topología de red -- `/network_map/{parent}` - Mapa de red desde el nodo padre -- `/full_network_map` - Topología de red completa -- `/top_map_queues/{n}` - Las N colas principales por tráfico -- `/node_names` - Obtener nombres de nodos a partir de IDs -- `/funnel/{target}` - Analizar el embudo de tráfico hacia el circuito +- `/network_map/{parent}` - Mapa de red desde nodo padre +- `/full_network_map` - Topología completa +- `/top_map_queues/{n}` - Top N colas por tráfico +- `/node_names` - Nombres de nodos por ID +- `/funnel/{target}` - Análisis de embudo hacia circuito ### Gestión de circuitos -- `/all_circuits` - Listar todos los circuitos -- `/raw_queue_data/{circuit_id}` - Datos en bruto de colas para el circuito +- `/all_circuits` - Lista de todos los circuitos +- `/raw_queue_data/{circuit_id}` - Datos de cola en bruto por circuito ### Análisis de flujos -- `/dump_active_flows` - Volcar todos los flujos activos (lento) +- `/dump_active_flows` - Volcado de flujos activos (lento) - `/count_active_flows` - Conteo de flujos activos -- `/top_flows/{flow_type}/{n}` - Flujos principales por tipo de métrica -- `/flows_by_ip/{ip}` - Flujos para una IP específica +- `/top_flows/{flow_type}/{n}` - Top flujos por tipo de métrica +- `/flows_by_ip/{ip}` - Flujos por IP específica - `/flow_duration` - Estadísticas de duración de flujos ### Geo y protocolos @@ -94,3 +152,25 @@ Vea `localhost:9122/api-docs` para la interfaz de Swagger UI. - `/current_endpoint_latlon` - Coordenadas geográficas de endpoints - `/ether_protocol_summary` - Resumen de protocolos Ethernet - `/ip_protocol_summary` - Resumen de protocolos IP + +## Cobertura de API en versiones recientes + +Compilaciones recientes ampliaron cobertura en algunas áreas. Dependiendo de su versión, la API también puede incluir: + +- Resúmenes de alertas y warnings +- Resúmenes de conteo de dispositivos y circuitos +- Consulta de detalle para circuito individual +- Helpers de búsqueda para flujos de UI +- Endpoints de detalle de scheduler y estadísticas de colas + +Use `localhost:9122/api-docs` para confirmar rutas y esquemas exactos en su nodo. + +## Capturar inventario de endpoints por release + +Para notas de release o runbooks internos, capture un snapshot de rutas API desde el nodo: + +```bash +curl -s http://localhost:9122/api-docs | jq -r '.paths | keys[]' | sort +``` + +Guarde esta salida junto con artefactos del release para comparar diferencias entre versiones. diff --git a/docs-es/v2.0/components-es.md b/docs-es/v2.0/components-es.md index d5d46778..18b496c2 100644 --- a/docs-es/v2.0/components-es.md +++ b/docs-es/v2.0/components-es.md @@ -1,72 +1,80 @@ -# Componentes de Software de LibreQoS +# Componentes de software de LibreQoS + +## Servicios systemd -## Servicios de Systemd ### lqosd -- Administra el código XDP actual. -- Desarrollado en Rust. -- Ejecuta la interfaz gráfica (GUI) disponible en http://a.b.c.d:9123 +- Administra la lógica de shaping/XDP. +- Implementado en Rust. +- Ejecuta la UI local disponible en `http://a.b.c.d:9123`. +- Hospeda páginas de Node Manager como: + - Mapa de flujos + - Árbol de red + - Explorador ASN + - Árbol/Pesos de CPU + - Editores de configuración para integraciones (UISP, Splynx, Netzur, VISP, etc.) ### lqos_scheduler -- lqos_scheduler realiza actualizaciones continuas de los reguladores de tráfico (shapers) de LibreQoS, incluyendo la obtención de datos desde cualquier integración CRM habilitada (UISP, Splynx, Netzur). -- Acciones realizadas: - - Al iniciar: realiza una configuración completa de las colas. - - Cada X minutos: actualiza las colas, obteniendo nueva configuración desde la integración CRM si está habilitada. - - El intervalo por defecto es de 30 minutos, por lo que la actualización ocurre cada 30 minutos. - - El intervalo de minutos puede ajustarse mediante el parámetro `queue_refresh_interval_mins` ubicado en `/etc/lqos.conf`. +- Realiza refrescos continuos de shaping, incluyendo lectura de integraciones CRM habilitadas. +- Acciones: + - Al iniciar: ejecución de setup completo de colas. + - Cada X minutos: actualización de colas y datos de integración. +- El intervalo por defecto es 30 minutos (`queue_refresh_interval_mins` en `/etc/lqos.conf`). -### Verificar el estado de los servicios +### Verificación de estado -``` +```bash sudo systemctl status lqosd lqos_scheduler ``` -Si el estado de alguno de los dos servicios aparece como 'failed', debe examinarse la causa utilizando journalctl, el cual muestra el historial completo del servicio. Por ejemplo, si lqosd ha fallado, ejecute: -``` -sudo journalctl -u lqosd -b -``` -Presione la tecla End en su teclado para ir al final del registro y ver las actualizaciones más recientes. -Lqosd indicará las razones específicas por las cuales falló, como una interfaz que no está activa, falta de soporte para múltiples filas en la interfaz, entre otros problemas. +Si algún servicio aparece como `failed`, revise logs: + +```bash +sudo journalctl -u lqosd -b +sudo journalctl -u lqos_scheduler -b +``` ### Depuración de lqos_scheduler -En segundo plano, lqos_scheduler ejecuta el script de Python scheduler.py, el cual a su vez ejecuta el script de Python LibreQoS.py +`lqos_scheduler` ejecuta `scheduler.py`, que a su vez invoca `LibreQoS.py`. -- scheduler.py: realiza actualizaciones continuas de los reguladores de tráfico (shapers) de LibreQoS, incluyendo la obtención de datos desde cualquier integración CRM habilitada (UISP, Splynx, Netzur). -- LibreQoS.py: se encarga de crear y actualizar las filas y el regulamiento de tráfico de los dispositivos. +Flujo de depuración recomendado: -Ejecuciones puntuales de estos componentes individuales pueden ser de gran ayuda para depurar y asegurar que todo esté correctamente configurado. - -Primero, detenga el servicio lqos_scheduler: - -```shell +```bash sudo systemctl stop lqos_scheduler -``` - -Para realizar una ejecución única de LibreQoS.py, utilice: - -```shell -sudo ./LibreQoS.py -``` - -- Para ejecutar en modo depuración con respuestas mas detalladas, use: - -```shell +cd /opt/libreqos/src sudo ./LibreQoS.py --debug -``` - -Para confirmar que lqos_scheduler (scheduler.py) funciona correctamente, ejecute: - -```shell sudo python3 scheduler.py -``` - -Una vez que se hayan corregido los errores, reinicie el servicio lqos_scheduler con: - -```shell sudo systemctl start lqos_scheduler ``` -### Solución de problemas de los servicios -Consulta la sección de [Solución de Problemas](troubleshooting-es.md). +## Modo privacidad en Node Manager + +Node Manager incluye redacción del lado cliente para demos/capturas: + +- Se activa con el ícono de máscara en la barra superior. +- La preferencia se guarda en `localStorage`. +- Oculta datos visibles en la UI; no modifica archivos fuente. + +## Canal de problemas urgentes + +Node Manager incluye un canal de problemas urgentes para eventos de alta prioridad (por ejemplo, límite de circuitos mapeados). + +- Los eventos aparecen en el indicador de navegación superior. +- Pueden revisarse y reconocerse desde el modal de problemas urgentes. +- Úselo como señal rápida; confirme detalle con `journalctl -u lqosd`. + +## Indicador de estado del scheduler + +Node Manager incluye visibilidad del estado del scheduler. + +- Úselo como señal rápida de salud para jobs periódicos. +- Si el scheduler no está saludable, valide primero estado de `lqosd` y `lqos_scheduler`. +- Revise detalle con: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - `journalctl -u lqosd --since "30 minutes ago"` + +## Solución de problemas de componentes + +Consulte [Solución de Problemas](troubleshooting-es.md). diff --git a/docs-es/v2.0/insight-es.md b/docs-es/v2.0/insight-es.md index 0a9606ba..50521da4 100644 --- a/docs-es/v2.0/insight-es.md +++ b/docs-es/v2.0/insight-es.md @@ -3,6 +3,37 @@ ## Acerca de Insight Conoce más sobre Insight en nuestro sitio web, [aquí](https://libreqos.io/insight/). +## Comportamiento de licenciamiento de Insight (lado nodo) + +### Material de claves local y grants offline + +LibreQoS guarda material de claves de Insight en: + +`/.keys/` + +Las compilaciones actuales pueden cachear grants firmados localmente para que el nodo siga operando durante pérdidas temporales de conectividad con servicios de control de Insight. La validez y expiración del grant se aplica localmente. + +Notas operativas: + +- Mantenga `.keys/` persistente entre reinicios. +- Trate `.keys/` como material sensible. +- Si hay estado inválido de grant/clave, `lqosd` mostrará errores de licencia/grant en logs. + +### Límites de circuitos mapeados y estado de licencia + +Compilaciones recientes aplican límites de circuitos mapeados según estado de licencia. + +Si su nodo está sin licencia/válido, LibreQoS puede aplicar un límite predeterminado de circuitos mapeados. Cuando se excede, los logs incluyen mensajes como: + +- `Mapped circuit limit reached` +- `Bakery mapped circuit cap enforced` + +Cuando ocurra: + +1. Revise estado de licencia Insight en la UI. +2. Revise `journalctl -u lqosd` para conteos requested/allowed/dropped. +3. Verifique si la cantidad de circuitos mapeados excede su licencia. + ## Interfaz de Insight ### Barra de tareas diff --git a/docs-es/v2.0/integrations-es.md b/docs-es/v2.0/integrations-es.md index ca09cedd..9d0c7216 100644 --- a/docs-es/v2.0/integrations-es.md +++ b/docs-es/v2.0/integrations-es.md @@ -6,6 +6,7 @@ + [Acceso API de Splynx](#acceso-api-de-splynx) + [Sobrescrituras de Splynx](#sobrescrituras-de-splynx) * [Integración con Netzur](#integración-con-netzur) + * [Integración con VISP](#integración-con-visp) * [Integración con UISP](#integración-con-uisp) + [Estrategias de Topología](#estrategias-de-topología-1) + [Estrategias de Manejo de Suspensiones](#estrategias-de-manejo-de-suspensiones) @@ -153,6 +154,46 @@ python3 integrationNetzur.py La integración actualiza `ShapedDevices.csv` y, salvo que `always_overwrite_network_json` esté deshabilitado, también `network.json`. Ajuste la opción Integración → Común si necesita preservar un `network.json` existente entre ejecuciones de Netzur. +## Integración con VISP + +Primero, configure los parámetros relevantes de VISP en `/etc/lqos.conf`: + +```ini +[visp_integration] +enable_visp = true +client_id = "su-client-id" +client_secret = "su-client-secret" +username = "usuario-app" +password = "password-app" +# Opcional: si se deja vacío, se usa el primer ISP ID del token +# isp_id = 0 +timeout_secs = 20 +# Opcional: dominio para enriquecimiento de sesiones online +# online_users_domain = "" +``` + +Notas: + +- La importación VISP usa GraphQL y actualmente trabaja en estrategia `flat`. +- La integración reescribe `ShapedDevices.csv` en cada ejecución. +- `network.json` solo se sobrescribe cuando `always_overwrite_network_json = true` (en `[integration_common]`). +- Los tokens de VISP se cachean en `/.visp_token_cache_*.json`. + +Importación manual: + +```bash +python3 integrationVISP.py +``` + +Para ejecución automática con scheduler: + +- `[visp_integration] enable_visp = true` +- reinicie scheduler: + +```bash +sudo systemctl restart lqos_scheduler +``` + ## Integración con UISP Primero, configure los parámetros relevantes de UISP en `/etc/lqos.conf`. @@ -246,8 +287,32 @@ commit_bandwidth_multiplier = 0.98 # Establecer mínimo al 98% del máximo (CIR ipv6_with_mikrotik = false # Habilitar si usa DHCPv6 con MikroTik always_overwrite_network_json = false # Establecer true para reconstruir topología en cada ejecución exception_cpes = [] # Excepciones de CPE en formato ["cpe:parent"] +squash_sites = [] # Opcional: sitios a compactar (flujo legacy de full) +enable_squashing = false # Opcional: habilita lógica adicional de compactación +do_not_squash_sites = [] # Opcional: sitios excluidos de compactación +ignore_calculated_capacity = false # Opcional: prioriza capacidad configurada sobre la calculada +insecure_ssl = false # Opcional: ignora validación TLS del API UISP ``` +### Opciones avanzadas/operativas de UISP + +Las compilaciones actuales también incluyen estas opciones en los editores de configuración de Node Manager: + +- `exclude_sites`: lista de sitios a excluir de la importación. +- `exception_cpes`: sobrescrituras `cpe:parent` para asignación ambigua. +- `squash_sites`: lista opcional de sitios a compactar en flujos `full`. +- `enable_squashing`: habilita compactación adicional donde aplique. +- `do_not_squash_sites`: exclusiones explícitas de compactación. +- `use_ptmp_as_parent`: prioriza AP PtMP como padre en rutas relevantes. +- `ignore_calculated_capacity`: usa capacidades configuradas en lugar de calculadas. +- `insecure_ssl`: deshabilita validación de certificados TLS para UISP. + +Uso recomendado: + +1. Mantenga `insecure_ssl = false` salvo necesidad interna clara (PKI/self-signed). +2. Use primero `exclude_sites` y `do_not_squash_sites` para cambios más seguros. +3. Aplique `squash_sites`/`enable_squashing` de forma incremental y valide colocación de colas tras cada cambio. + Para probar la integración con UISP, ejecute: ```shell diff --git a/docs-es/v2.0/lts-es.md b/docs-es/v2.0/lts-es.md index 78c13bc7..c27f8c8e 100644 --- a/docs-es/v2.0/lts-es.md +++ b/docs-es/v2.0/lts-es.md @@ -1,38 +1,18 @@ -# LibreQoS Long-Term Stats (LTS) +# Nomenclatura LTS heredada (deprecado) -## Acerca de LTS -Obtén más información sobre LTS en nuestro sitio web, [aquí](https://libreqos.io/lts/). - -## Registro -Encuentre su ID de Nodo LibreQoS iniciando sesión en su equipo donde se encuentre LibreQoS por SSH y ejecutando: +```{warning} +LTS está deprecado y fue reemplazado por LibreQoS Insight. +Para despliegues actuales y nuevas suscripciones, use la documentación de Insight: +[Insight](insight-es.md) ``` -sed -n 's/node_id = //p' /etc/lqos.conf | sed -e 's/^"//' -e 's/"$//'` -``` -El resultado será un número largo: el identificador único de su caja LibreQoS. -Ahora visite: -``` -https://stats.libreqos.io/trial1/YOUR_NODE_ID -``` -Donde YOUR_NODE_ID es el ID de Nodo que encontró en el paso anterior. +## Nota de migración -Si es la primera vez que usa LTS, seleccione "Sign Up - Regular Long-Term Stats". +Si tiene referencias heredadas a LTS en runbooks/documentación interna: -Complete el registro para la prueba gratuita de 30 días ingresando su información de pago. +- Reemplácelas por referencias a Insight. +- Use [insight-es.md](insight-es.md) para comportamiento y flujos actuales. +- Use [api-es.md](api-es.md) para detalles de API de nodo (`/api-docs` en su nodo es la fuente de verdad). +- En algunas rutas UI/código todavía aparecen nombres históricos como `lts_trial` o `config_lts`; en versiones actuales se refieren a flujos de Insight. -El proceso de registro le proporcionará una Clave de Licencia LTS. - -Regrese a la caja de LibreQoS y edite el archivo `/etc/lqos.conf` para modificar la sección [long_term_stats] de la siguiente manera: -``` -[long_term_stats] -gather_stats = true -collation_period_seconds = 60 -license_key = "YOUR_LICENSE_KEY" -uisp_reporting_interval_seconds = 300 -``` -Donde YOUR_LICENSE_KEY es su clave única de licencia LTS obtenida en el paso anterior. Asegúrese de incluir las comillas. - -Ahora guarde el archivo y ejecute: `sudo systemctl restart lqosd lqos_scheduler`. Esto reiniciará el proceso lqosd, permitiéndole comenzar a enviar datos a LTS. - -## Acceso a LTS -Para acceder a LTS, visite [https://stats.libreqos.io/](https://stats.libreqos.io/) - e ingrese su clave LTS, usuario (correo electrónico) y contraseña. +Las instrucciones heredadas de onboarding de LTS se removieron para evitar confusión en despliegues nuevos. diff --git a/docs-es/v2.0/node-manager-ui-es.md b/docs-es/v2.0/node-manager-ui-es.md new file mode 100644 index 00000000..fe7f4352 --- /dev/null +++ b/docs-es/v2.0/node-manager-ui-es.md @@ -0,0 +1,76 @@ +# Interfaz Node Manager de LibreQoS + +Esta página documenta las vistas clave del Node Manager y su comportamiento operativo en la interfaz local (`http://ip_del_shaper:9123`). + +## Vistas principales + +### Dashboard +- Resumen por widgets de throughput, retransmisiones, RTT, flujos y actividad de colas. +- El contenido puede variar según versión y funciones habilitadas. + +### Vista de árbol de red +- Vista jerárquica de nodos/circuitos desde la perspectiva del shaper. +- Útil para identificar cuellos de botella y patrones de utilización padre/hijo. + +### Mapa de flujos +- Visualización geográfica de flujos según geolocalización de endpoints. +- Requiere volumen de datos reciente suficiente. + +### Explorador ASN +- Exploración por ASN (volumen, RTT/retransmisiones y detalle de flujos asociados). +- Resultados vacíos suelen indicar poco dato reciente, no necesariamente falla. + +### Árbol/ponderación de CPU +- Muestra distribución de colas/circuitos por núcleo de CPU. +- Ayuda a validar comportamiento de binpacking y balance de carga. + +### Editor de Shaped Devices +- Editor CRUD para `ShapedDevices.csv`. +- Incluye paginación y filtros en versiones actuales. + +### Problemas urgentes +- Node Manager puede mostrar problemas operativos urgentes emitidos por servicios backend. +- Ejemplos: advertencias de límites de mapeo/licencia y errores de alta prioridad. +- Operadores pueden reconocer/limpiar eventos desde la UI. +- Códigos comunes: `MAPPED_CIRCUIT_LIMIT` y `TC_U16_OVERFLOW` (ver [Solución de Problemas](troubleshooting-es.md#códigos-de-problemas-urgentes-y-primeras-acciones)). + +### Estado del scheduler +- Node Manager muestra salud/disponibilidad del scheduler. +- Úselo para validar refrescos periódicos después de cambios de configuración/integración. +- Si hay errores, correlacione con: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - `journalctl -u lqosd --since "30 minutes ago"` + +## Modo privacidad / redacción + +- Se activa con el ícono de máscara en la barra superior. +- Es redacción del lado cliente y se guarda en `localStorage` del navegador. +- Ayuda a ocultar PII en capturas/demos. +- No modifica `ShapedDevices.csv`, `network.json` ni datos backend. + +## Comportamiento de vistas vacías + +Las siguientes vistas pueden verse vacías cuando hay poco dato: +- Mapa de flujos +- Sankey del árbol de red +- Explorador ASN + +Si ocurre: +1. Confirme que `lqosd` está saludable. +2. Espere a que se acumule tráfico/dato reciente. +3. Recargue la página. +4. Revise logs: + +```bash +journalctl -u lqosd --since "10 minutes ago" +``` + +## Nota de nomenclatura heredada + +Algunos identificadores internos todavía usan nombres históricos `lts_*`. Operativamente, en versiones actuales se refieren a flujos de Insight. + +## Páginas relacionadas + +- [Componentes](components-es.md) +- [Configuración](configuration-es.md) +- [Solución de Problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/performance-tuning-es.md b/docs-es/v2.0/performance-tuning-es.md index c2a0af3e..b1125d84 100644 --- a/docs-es/v2.0/performance-tuning-es.md +++ b/docs-es/v2.0/performance-tuning-es.md @@ -1,28 +1,71 @@ -# Ajuste de Rendimiento +# Ajuste de rendimiento -## Ubuntu inicia lentamente (~2 minutos) +## Base de CPU e IRQ -### Listar todos los servicios que dependen de la red +Configure el governor de CPU en modo rendimiento para bare metal/hipervisor: -```shell +```bash +sudo cpupower frequency-set --governor performance +``` + +Confirme que el conteo de colas NIC y la distribución por CPU sean razonables: + +```bash +ethtool -l +grep -E 'CPU\\(|IRQ' /proc/interrupts | head -n 50 +``` + +Si un solo núcleo/cola está saturado y los demás están ociosos, rebalancee afinidad IRQ/colas y revise la configuración de colas en `/etc/lqos.conf`. + +## Presión por topología/colas + +Cuando modele jerarquías grandes: + +- Prefiera estrategias de menor profundidad (`ap_only`/`ap_site`) salvo que necesite jerarquía completa. +- Use `promote_to_root` en topologías multi-sitio para evitar cuellos de botella de un solo núcleo. +- Valide CPU Tree/CPU Weights en Node Manager después de cambios topológicos importantes. + +Consulte también [Escalado y diseño de topología](scale-topology-es.md). + +## Frecuencia del scheduler y carga + +La cadencia de `lqos_scheduler` afecta carga del plano de control y velocidad de cambios. + +- Comience con `queue_refresh_interval_mins` conservador. +- Reduzca intervalo solo si su integración/API y host soportan ese churn. +- Tras cambiar intervalo, monitoree: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - estado del scheduler en Node Manager + +## Despliegue de StormGuard + +Si usa StormGuard: + +1. Inicie con `dry_run = true`. +2. Observe al menos un periodo de alto tráfico. +3. Pase a modo activo solo tras revisar estado/depuración. + +Vea [StormGuard](stormguard-es.md). + +## Arranque lento / dependencias de red + +Si Ubuntu arranca lento por dependencias de `network-online`, inspeccione: + +```bash systemctl show -p WantedBy network-online.target ``` -### En Ubuntu 22.04 este comando puede ayudar +En algunos entornos Ubuntu, deshabilitar servicios no usados de cloud/iSCSI puede ayudar: -```shell -systemctl disable cloud-config iscsid cloud-final +```bash +sudo systemctl disable cloud-config iscsid cloud-final ``` -### Establecer el governor correcto para la CPU (baremetal/hipervisor) +Valide esta acción contra su entorno antes de aplicarla. -```shell -cpupower frequency-set --governor performance -``` +## Convergencia de ruteo (OSPF) -### OSPF +Para despliegues enrutados, ajuste timers OSPF entre core y edge para reducir ventanas de indisponibilidad en reinicios: -Se recomienda ajustar los temporizadores OSPF de ambos vecinos (core y edge router) para minimizar el tiempo de inactividad cuando el servidor LibreQoS se reinicie. - -* hello interval -* dead interval +- hello interval +- dead interval diff --git a/docs-es/v2.0/scale-topology-es.md b/docs-es/v2.0/scale-topology-es.md new file mode 100644 index 00000000..687a5c24 --- /dev/null +++ b/docs-es/v2.0/scale-topology-es.md @@ -0,0 +1,73 @@ +# Escalado y diseño de topología + +Esta guía se centra en diseñar `network.json` y elegir estrategias de integración para mantener rendimiento estable a escala. + +## Principios de diseño + +- Mantenga la jerarquía tan simple como sea posible. +- Evite concentrar demasiado tráfico bajo un único padre de nivel superior. +- Use nombres y relaciones padre/hijo estables para reducir churn de colas. +- Valide cambios de topología en ventana de mantenimiento. + +## Selección de estrategia por escala + +Use la estrategia más simple que cumpla el objetivo operativo: + +| Estrategia | Ajuste típico de escala | Tradeoff | +|---|---|---| +| `flat` | Máximo rendimiento, mínima jerarquía | Menor visibilidad/agregación | +| `ap_only` | Redes grandes centradas en APs | Buen rendimiento, visibilidad media | +| `ap_site` | Redes medianas/grandes con sitio+AP | Mejor agregación, costo moderado | +| `full` | Necesidad de ruta/backhaul completo | Mayor control y mayor costo CPU/memoria | + +Si necesita `full` y detecta saturación de un solo núcleo, use `promote_to_root`. + +## Distribución padre/hijo + +Objetivos: + +- Balancear padres de nivel superior en tráfico y cantidad de circuitos. +- Evitar ramas excesivamente profundas sin valor real para shaping. +- Mantener nombres de hermanos únicos y estables. + +Señales de alerta: + +- Un núcleo saturado de forma persistente y el resto ocioso. +- Reconstrucciones grandes de colas por cambios menores. +- CPU Tree de Node Manager con distribución muy sesgada. + +## Nodos virtuales y agrupación lógica + +Los nodos virtuales ayudan para organización y agregación visual. + +- Úselos para mejorar operabilidad y reportes. +- No los use para ocultar una topología física confusa. +- Valide colisiones de nombres tras promoción virtual. + +## Guardrails de colas/clasificadores + +A gran escala, la presión sobre identificadores de clase puede ser real. + +- Monitoree eventos urgentes como `TC_U16_OVERFLOW`. +- Si aparece, reduzca complejidad topológica y/o aumente paralelismo de colas. +- Reevalúe profundidad de estrategia (`full` -> `ap_site`/`ap_only`) cuando haya riesgo. + +Consulte [Solución de Problemas](troubleshooting-es.md#códigos-de-problemas-urgentes-y-primeras-acciones). + +## Checklist de despliegue para cambios de topología + +1. Respaldar `network.json` y `ShapedDevices.csv`. +2. Aplicar un conjunto de cambios por vez. +3. Revisar logs de `lqos_scheduler` y `lqosd` tras cada cambio. +4. Validar en Node Manager: + - CPU Tree / CPU Weights + - comportamiento de mapa de flujos/ASN/árbol + - estado del scheduler y problemas urgentes +5. Mantener plan de rollback con configuración y archivos previos. + +## Páginas relacionadas + +- [Integraciones](integrations-es.md) +- [Ajuste de rendimiento](performance-tuning-es.md) +- [Configuración](configuration-es.md) +- [Solución de Problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/stormguard-es.md b/docs-es/v2.0/stormguard-es.md new file mode 100644 index 00000000..c3b0110d --- /dev/null +++ b/docs-es/v2.0/stormguard-es.md @@ -0,0 +1,74 @@ +# StormGuard + +StormGuard es el subsistema de ajuste adaptativo de colas de LibreQoS para eventos de congestión y calidad. + +## Qué hace StormGuard + +- Monitorea señales en tiempo real (throughput, métricas RTT/pérdida y contexto de saturación). +- Aplica ajustes acotados a límites de nodos configurados para proteger calidad bajo estrés. +- Expone estado y depuración en Node Manager. + +## Configuración + +StormGuard se configura en `/etc/lqos.conf` bajo `[stormguard]`. + +Claves comunes: + +- `enabled`: habilita o deshabilita StormGuard. +- `dry_run`: calcula decisiones sin aplicar cambios de colas en vivo. +- `targets`: lista de nodos de nivel superior a gestionar. +- `minimum_download_percentage`: piso mínimo de descarga. +- `minimum_upload_percentage`: piso mínimo de subida. +- `log_file`: ruta opcional para telemetría CSV de decisiones/cambios. + +Ejemplo: + +```toml +[stormguard] +enabled = true +dry_run = true +log_file = "/var/log/stormguard.csv" +targets = ["SITE_A", "SITE_B"] +minimum_download_percentage = 0.5 +minimum_upload_percentage = 0.5 +``` + +Si está probando, comience con `dry_run = true`. + +## UI y depuración + +- Node Manager incluye vistas de estado y depuración de StormGuard. +- La página de depuración muestra: + - límites efectivos actuales + - métricas de evaluación + - contexto de reglas/decisiones + +## Patrón de despliegue seguro + +1. Habilitar con `dry_run = true`. +2. Observar durante varios periodos pico. +3. Validar que no haya oscilaciones indeseadas. +4. Cambiar a `dry_run = false`. +5. Monitorear después de cada cambio grande de topología/integración. + +## Solución de problemas + +Si el comportamiento parece incorrecto: + +```bash +sudo systemctl status lqosd lqos_scheduler +journalctl -u lqosd --since "30 minutes ago" +``` + +También verifique: + +- que los nombres en `targets` aún coincidan con `network.json` +- que cambios de integración no hayan renombrado nodos clave +- que los pisos mínimos sean razonables para su perfil de tráfico +- que `log_file` (si se usa) sea escribible por el servicio + +## Páginas relacionadas + +- [Configuración](configuration-es.md) +- [Componentes](components-es.md) +- [Solución de Problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/troubleshooting-es.md b/docs-es/v2.0/troubleshooting-es.md index be9ed4eb..de1fa6a9 100644 --- a/docs-es/v2.0/troubleshooting-es.md +++ b/docs-es/v2.0/troubleshooting-es.md @@ -1,79 +1,94 @@ -# Solución de Problemas +# Solución de problemas -## Problemas Comunes +## Problemas comunes ### La contraseña de usuario no funciona -Eliminar el archivo lqusers: -``` +Elimine el archivo de usuarios: + +```bash sudo rm /opt/libreqos/src/lqusers.toml sudo systemctl restart lqosd lqos_scheduler ``` -Entonces visita: BOX_IP:9123/index.html -Esto le permitirá configurar el usuario nuevamente desde cero utilizando la interfaz web. + +Luego abra: `IP_CAJA:9123/index.html`. ### No hay WebUI en x.x.x.x:9123 -La interfaz web (WebUI) está controlada por el servicio lqosd. Generalmente, cuando la WebUI no se inicia, se debe a que lqosd está en un estado fallido. Verifica si el servicio lqosd está corriendo con el siguiente comando: -``` -sudo systemctl status lqosd -``` +La WebUI depende de `lqosd`. Cuando no carga, normalmente `lqosd` está fallando. -Si el estado es 'failed', examina la causa usando journalctl, que muestra el estado completo del servicio: -``` +```bash +sudo systemctl status lqosd journalctl -u lqosd --since "10 minutes ago" ``` -Presiona la tecla End en el teclado para ir al final del registro y ver las últimas actualizaciones. -Lqosd proporcionará razones específicas del fallo, como por ejemplo que una interfaz no está activa, o que le falta soporte para múltiples filas (multi-queue), u otros problemas. +`lqosd` suele mostrar causa específica (interfaz caída, falta de multi-queue, etc.). -### LibreQoS está en ejecución, pero no se está aplicando el shaping al tráfico +### LibreQoS está en ejecución, pero no hace shaping -En el archivo /etc/lqos.conf, asegúrese de que los parámetros `to_internet` y `to_network` estén configurados correctamente. -Si no lo están, simplemente intercambie las interfaces y reinicie lqosd y el scheduler. +Verifique en `/etc/lqos.conf` que `to_internet` y `to_network` estén correctos. -``` +```bash sudo systemctl restart lqosd lqos_scheduler -``` - -Asegurese de que los servicios estén funcionando correctamente - -``` sudo systemctl status lqosd lqos_scheduler ``` -El servicio lqos_scheduler depende de que el servicio lqosd esté en buen estado y en ejecución. +### On-a-stick: shaping incorrecto o una dirección débil -### El servicio lqosd no se está ejecutando o falló al iniciar +On-a-stick depende de split correcto por dirección. Si la detección TX o `override_available_queues` está mal, el mapeo puede degradarse. -Verifica el estado del servicio lqosd: -``` +```bash sudo systemctl status lqosd +journalctl -u lqosd --since "10 minutes ago" +sudo systemctl restart lqosd lqos_scheduler ``` -Si el estado es 'failed', examine la causa con journalctl, que muestra el estado completo del servicio: -``` +### El servicio lqosd no se ejecuta o falla al iniciar + +```bash +sudo systemctl status lqosd journalctl -u lqosd --since "10 minutes ago" ``` -Presiona la tecla End en el teclado para ir al final del registro y ver las últimas actualizaciones. - -Lqosd le mostrará razones específicas del fallo, como por ejemplo que una interfaz no está activa, que le falta soporte multi-queue, u otros problemas. ### Depuración avanzada de lqosd -Desde la línea de comandos, ejecuta: -``` +```bash sudo RUST_LOG=info /opt/libreqos/src/bin/lqosd ``` -Esto ejecutará lqosd en modo debug y te proporcionará detalles sobre por qué falló al iniciar. + +### El servicio lqos_scheduler muestra errores + +```bash +sudo journalctl -u lqos_scheduler --since "1 day ago" --no-pager > lqos_sched_log.txt +``` + +### El estado del scheduler en Node Manager aparece no saludable + +Versiones recientes muestran estado/readiness del scheduler en Node Manager. + +Si aparece caído/desactualizado: + +1. Verifique ambos servicios. +2. Revise logs recientes del scheduler. +3. Revise logs de `lqosd` para eventos de scheduler ready/error. +4. Si hubo cambios recientes, reinicie servicios. + +```bash +sudo systemctl status lqosd lqos_scheduler +journalctl -u lqos_scheduler --since "30 minutes ago" +journalctl -u lqosd --since "30 minutes ago" +sudo systemctl restart lqosd lqos_scheduler +``` + +Si oscila entre ready/error, valide credenciales y timeouts de integración en `/etc/lqos.conf`. ### RTNETLINK answers: Invalid argument -Este error suele aparecer cuando el qdisc tipo MQ no puede ser añadido correctamente a la interfaz de red (NIC). -Esto sugiere que la tarjeta de red no tiene suficientes filas RX/TX. Asegurese de estar utilizando las [NICs recomendadas](requirements-es.md). +Suele indicar que no se pudo agregar correctamente qdisc MQ en la NIC (colas RX/TX insuficientes). Verifique [NICs recomendadas](requirements-es.md). -### Error de Python ModuleNotFoundError en Ubuntu 24.04 -``` +### Python ModuleNotFoundError en Ubuntu 24.04 + +```bash pip uninstall binpacking --break-system-packages --yes sudo pip uninstall binpacking --break-system-packages --yes sudo pip install binpacking --break-system-packages @@ -84,40 +99,89 @@ pip uninstall deepdiff --break-system-packages --yes sudo pip uninstall deepdiff --break-system-packages --yes sudo pip install deepdiff --break-system-packages ``` -### Todas las IPs de clientes aparecen como "Unknown IPs" en lugar de "Shaped Devices" en la interfaz gráfica -``` + +### Todas las IPs de clientes aparecen como Unknown IPs + +```bash cd /opt/libreqos/src sudo systemctl stop lqos_scheduler sudo python3 LibreQoS.py ``` -El texto que se genera en la terminal al ejecutar LibreQoS.py proporciona más detalles sobre errores más específicos relacionados con problemas en los archivos ShapedDevices.csv y network.json. -Una vez que haya identificado el error y corregido ShapedDevices.csv y/o network.json, ejecute: -```sudo systemctl start lqos_scheduler``` - -### Colisión al promover nodos virtuales (network.json) - -Si LibreQoS.py falla con un error como `Virtual node promotion collision: 'AP_A' already exists at this level.`, tienes un nodo con `"virtual": true` cuyos hijos se promueven a un nivel padre donde ya existe un nodo con el mismo nombre. - -Renombra uno de los nodos en conflicto (los nombres deben ser únicos entre hermanos después de la promoción), o reestructura la jerarquía para que los hijos promovidos no colisionen. - -### Error de segmentación (segfault) en systemd - -Si experimenta un segfault en systemd, este es un problema conocido en systemd [1](https://github.com/systemd/systemd/issues/36031) [2](https://github.com/systemd/systemd/issues/33643). -Como solución temporal, puede compilar systemd desde cero: - -### Instalar dependencias de compilación +Corrija errores en `ShapedDevices.csv` y/o `network.json`, luego: +```bash +sudo systemctl start lqos_scheduler ``` + +### Flow Map / Tree Overview / ASN Explorer aparecen en blanco + +Algunas vistas requieren suficiente dato reciente para renderizar. + +1. Confirme que `lqosd` está saludable. +2. Espere acumulación de tráfico. +3. Recargue la página tras 1-2 minutos. +4. Revise logs: + +```bash +journalctl -u lqosd --since "10 minutes ago" +``` + +Si sigue en blanco con tráfico normal, recolecte logs y abra issue. + +### Colisión de promoción de nodo virtual (`network.json`) + +Si `LibreQoS.py` falla con `Virtual node promotion collision: 'AP_A' already exists at this level.`, hay un nodo con `"virtual": true` cuyos hijos colisionan por nombre al promoverse. + +Renombre nodos en conflicto o reestructure jerarquía para evitar colisiones. + +### Se alcanzó el límite de circuitos mapeados + +Si ve mensajes como: + +- `Mapped circuit limit reached` +- `Bakery mapped circuit cap enforced` + +LibreQoS está aplicando un límite de circuitos mapeados. + +Checks recomendados: + +1. Confirmar estado de licencia Insight en UI. +2. Revisar logs de `lqosd` para requested/allowed/dropped. +3. Reducir circuitos mapeados (corto plazo) o ajustar licencia/límites (largo plazo). + +### Códigos de problemas urgentes y primeras acciones + +Node Manager muestra códigos legibles por máquina para triage rápido. + +| Código | Significado | Primeros checks | Ruta de corrección típica | +|---|---|---|---| +| `MAPPED_CIRCUIT_LIMIT` | Bakery está forzando límite de circuitos mapeados. | Estado de licencia Insight y `journalctl -u lqosd` con requested/allowed/dropped. | Reducir circuitos mapeados o actualizar licencia/límites. | +| `TC_U16_OVERFLOW` | IDs minor de clases/colas excedieron rango u16 de tc en una cola CPU. | `journalctl -u lqos_scheduler -u lqosd`, profundidad topológica y distribución por colas. | Aumentar paralelismo de colas y/o simplificar/rebalancear jerarquía. | + +Patrón operativo: + +1. Abra el detalle del problema urgente en Node Manager (código/mensaje/contexto). +2. Recolecte logs correlacionados de `lqosd` y `lqos_scheduler`. +3. Aplique mitigación inmediata. +4. Reconozca/limpie el evento en UI cuando esté estable. + +### Segfault de systemd + +Si experimenta un segfault en systemd, es un problema conocido [1](https://github.com/systemd/systemd/issues/36031) [2](https://github.com/systemd/systemd/issues/33643). + +#### Instalar dependencias de compilación + +```bash sudo apt update sudo apt install build-essential git meson libcap-dev libmount-dev libseccomp-dev \ libblkid-dev libacl1-dev libattr1-dev libcryptsetup-dev libaudit-dev \ libpam0g-dev libselinux1-dev libzstd-dev libcurl4-openssl-dev ``` -#### Clonar el repositorio de systemd desde github +#### Clonar systemd desde GitHub -``` +```bash git clone https://github.com/systemd/systemd.git cd systemd git checkout v257.5 @@ -125,9 +189,9 @@ meson setup build meson compile -C build sudo meson install -C build ``` -Después, reinicia el sistema y confirma la versión de systemd con `systemctl --version` -``` -libreqos@libreqos:~$ systemctl --version -systemd 257 (257.5) +Luego reinicie y valide con: + +```bash +systemctl --version ``` diff --git a/docs/v2.0/api.md b/docs/v2.0/api.md index 39d46a76..8cbb6d48 100644 --- a/docs/v2.0/api.md +++ b/docs/v2.0/api.md @@ -6,29 +6,60 @@ The LibreQoS Node API requires an active LibreQoS Insight subscription. ## Installation -### Download +### If installed via `.deb` (recommended) -``` -cd ~ -sudo apt-get update -sudo apt-get upgrade -wget https://libreqos.io/wp-content/uploads/2025/09/lqos_api.zip -sudo apt-get install unzip -sudo mkdir /opt/lqos_api/ -sudo chown -R $USER /opt/lqos_api/ -cd /opt/lqos_api/ -unzip lqos_api.zip -``` +`lqos_api` is installed with LibreQoS into: + +`/opt/libreqos/src/bin/lqos_api` ### Test run -``` -cd /opt/lqos_api/ -./lqos_api + +```bash +/opt/libreqos/src/bin/lqos_api ``` ### Systemd Service -If the test run succeeds, use `sudo nano /etc/systemd/system/lqos_api.service` and paste these contents: +The package includes a template service file: + +```bash +sudo cp /opt/libreqos/src/bin/lqos_api.service.example /etc/systemd/system/lqos_api.service +``` + +Then run: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable lqos_api +sudo systemctl start lqos_api +``` + +### Update just the API binary + +Use the helper script: + +```bash +cd /opt/libreqos/src +./update_api.sh +``` + +This downloads the latest `lqos_api` and installs it to `/opt/libreqos/src/bin/lqos_api`. + +You can optionally skip service restart: + +```bash +./update_api.sh --no-restart +``` + +Or install to an alternate location: + +```bash +./update_api.sh --bin-dir /some/path/bin --no-restart +``` + +### Manual service file (if needed) + +If you are creating the service manually, use: ``` [Unit] @@ -36,15 +67,17 @@ After=network.service lqosd.service Requires=lqosd.service [Service] -WorkingDirectory=/opt/lqos_api/ -ExecStart=/opt/lqos_api/lqos_api +WorkingDirectory=/opt/libreqos/src/bin +ExecStart=/opt/libreqos/src/bin/lqos_api Restart=always [Install] WantedBy=default.target ``` + Then run: -``` + +```bash sudo systemctl daemon-reload sudo systemctl enable lqos_api sudo systemctl start lqos_api @@ -54,6 +87,30 @@ sudo systemctl start lqos_api See `localhost:9122/api-docs` for the Swagger UI. +`/api-docs` is the source of truth for your installed version. Endpoint availability can change between releases. + +## Deployment and Hardening Guidance + +Recommended production posture: + +1. Keep the Node API reachable only from trusted management networks. +2. Do not expose the API directly to the public Internet. +3. If remote access is required, place it behind a reverse proxy with TLS and authentication. +4. Restrict inbound access with host/network firewall allowlists. +5. Monitor API and service logs for abnormal access patterns. + +If the API is not needed on a node, disable the service: + +```bash +sudo systemctl disable --now lqos_api +``` + +If enabled for operations, verify service state after upgrades: + +```bash +sudo systemctl status lqos_api +``` + ## API Endpoints ### Health & System @@ -95,3 +152,25 @@ See `localhost:9122/api-docs` for the Swagger UI. - `/current_endpoint_latlon` - Endpoint geographic coordinates - `/ether_protocol_summary` - Ethernet protocol statistics - `/ip_protocol_summary` - IP protocol statistics + +## Newer API Coverage Areas + +Recent builds expanded API coverage in a few areas. Depending on your version, the API may also include: + +- Alerts and warnings summaries +- Device and circuit count summaries +- Single-circuit detail lookups +- Search result helpers for UI workflows +- Scheduler and queue-stat detail endpoints + +Use `localhost:9122/api-docs` to confirm exact paths and schemas on your node. + +## Capturing an endpoint inventory for your release + +For release notes or internal runbooks, capture a snapshot of API paths from your node: + +```bash +curl -s http://localhost:9122/api-docs | jq -r '.paths | keys[]' | sort +``` + +Save this output with your release artifacts so operators can compare endpoint differences between versions. diff --git a/docs/v2.0/components.md b/docs/v2.0/components.md index 9eba93c0..4016bc06 100644 --- a/docs/v2.0/components.md +++ b/docs/v2.0/components.md @@ -6,6 +6,12 @@ - Manages actual XDP code. - Coded in Rust. - Runs the GUI available at http://a.b.c.d:9123 +- Hosts Node Manager pages such as: + - Flow Map + - Network Tree Overview + - ASN Explorer + - CPU Tree / CPU Weights + - Configuration editors for integrations (UISP, Splynx, Netzur, VISP, etc.) ### lqos_scheduler @@ -71,3 +77,30 @@ sudo systemctl start lqos_scheduler ### Troubleshooting Service Components Please see [Troubleshooting](troubleshooting.md). + +## Node Manager privacy mode + +Node Manager includes a client-side redaction mode for demos/screenshots: +- Toggle using the mask icon in the top navigation. +- Redaction preference is saved in browser local storage. +- This masks/redacts visible data in the browser UI; it does not modify source data files. + +For public screenshots, enable redaction before capture. + +## Urgent issue channel + +Node Manager includes an urgent issue channel for high-priority events (for example, mapped-circuit limit enforcement and related operational warnings). + +- Urgent issues appear in the top navigation indicator. +- They can be reviewed and acknowledged from the urgent issues modal. +- Use this as an at-a-glance operational signal; confirm details in `journalctl -u lqosd`. + +## Scheduler status indicator + +Node Manager includes scheduler status visibility for operator awareness. + +- Use scheduler status as a quick health signal for recurring refresh jobs. +- If scheduler is not healthy, validate `lqosd` and `lqos_scheduler` service state first. +- Confirm details with: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - `journalctl -u lqosd --since "30 minutes ago"` diff --git a/docs/v2.0/configuration.md b/docs/v2.0/configuration.md index 4b060ada..131e3e95 100644 --- a/docs/v2.0/configuration.md +++ b/docs/v2.0/configuration.md @@ -170,10 +170,58 @@ netflow_version = 5 do_not_track_subnets = ["192.168.0.0/16"] ``` +#### On-a-stick mode queue mapping (single interface) + +When running on-a-stick mode, LibreQoS splits available TX queues in half: +- first half for one direction +- second half for the reverse direction + +So if 16 queues are available, each direction gets 8 queues. This directional offset is computed automatically at startup. + +If your NIC exposes unusual queue counts, you can set `override_available_queues` in `[queues]` and restart `lqosd`. + +If shaping appears asymmetric in on-a-stick deployments, verify: +- the interface has enough TX queues +- `override_available_queues` is not forcing an incorrect value +- you have restarted after config changes + +See also [Troubleshooting](troubleshooting.md). + #### CRM/NMS Integrations Learn more about [configuring integrations here](integrations.md). +### Runtime overrides (`lqos_overrides.json`) + +LibreQoS supports runtime-friendly adjustments via `lqos_overrides.json` in your `lqos_directory`. + +Use the `lqos_overrides` CLI: + +```bash +/opt/libreqos/src/bin/lqos_overrides --help +``` + +Common examples: + +```bash +# List persistent devices +/opt/libreqos/src/bin/lqos_overrides persistent-devices list + +# Add/replace per-circuit speed adjustment +/opt/libreqos/src/bin/lqos_overrides adjustments add-circuit-speed --circuit-id "1234" --max-download-bandwidth 200 --max-upload-bandwidth 50 + +# Set a node to logical-only (virtual) without editing network.json directly +/opt/libreqos/src/bin/lqos_overrides network-adjustments set-virtual "AP_GROUP_A" true + +# List network adjustments +/opt/libreqos/src/bin/lqos_overrides network-adjustments list +``` + +How overrides apply: +- `lqos_scheduler` applies overrides during refresh cycles. +- persistent devices are merged into `ShapedDevices.csv`. +- circuit/device/network adjustments are applied on top of imported/manual data. + ### Network Hierarchy #### Network.json @@ -255,6 +303,28 @@ LibreQoS knows how to shape these devices, and what Node (AP, Site, etc) they ar The ShapedDevices.csv file correlates device IP addresses to Circuits (each internet subscriber's unique service). +The base format has 13 columns, with an optional 14th `sqm` column for per-circuit queue overrides: + +``` +Circuit ID,Circuit Name,Device ID,Device Name,Parent Node,MAC,IPv4,IPv6,Download Min Mbps,Upload Min Mbps,Download Max Mbps,Upload Max Mbps,Comment[,sqm] +``` + +##### Optional `sqm` column + +If present, `sqm` overrides queueing for that circuit. + +Allowed values: +- Single token: `cake`, `fq_codel`, `none` +- Directional token: `down_sqm/up_sqm` where each side is `cake`, `fq_codel`, `none`, or empty + +Examples: +- `cake` (both directions) +- `cake/fq_codel` (download cake, upload fq_codel) +- `fq_codel/` (download fq_codel, upload uses global default) +- `/none` (upload disabled, download uses global default) + +If `sqm` is empty/missing, global queue defaults apply. + Here is an example of an entry in the ShapedDevices.csv file: | Circuit ID | Circuit Name | Device ID | Device Name | Parent Node | MAC | IPv4 | IPv6 | Download Min Mbps | Upload Min Mbps | Download Max Mbps | Upload Max Mbps | Comment | |------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| @@ -272,6 +342,13 @@ Here is an example of an entry in the ShapedDevices.csv file: If you are using one of our CRM integrations, this file will be automatically generated. If you are not using an integration, you can manually edit the file using either the WebUI or by directly editing the ShapedDevices.csv file through the CLI. +Directional SQM examples: + +``` +2794,"6 Littleton Drive, Ringgold, GA 30736",5,Device 5,AP_11,,100.64.0.5,"fdd7:b724:0:500::/56",1,1,105,18,"",cake/fq_codel +2795,"7 Example Ave",6,Device 6,AP_11,,100.64.0.6,,1,1,105,18,"",/none +``` + ##### Multiple IPs per Circuit If you need to list multiple IPv4s in the IPv4 field, or multiple IPv6s in the IPv6 field, add a comma between them. If you are editing with a CSV editor (LibreOffice Calc, Excel), the CSV editor will automatically wrap these comma-seperated items with quotes for you. If you are editing the file manually with a utility like notepad or nano, please add quotes surrounding the comma-seperated entries. diff --git a/docs/v2.0/git-install.md b/docs/v2.0/git-install.md index 8fdf12d6..cee5582e 100644 --- a/docs/v2.0/git-install.md +++ b/docs/v2.0/git-install.md @@ -53,7 +53,7 @@ This will take a while the first time, but it puts everything in the right place Now, to build rust crates, run: ```shell -cd rust +cd /opt/libreqos/src/rust cargo build --all ``` diff --git a/docs/v2.0/insight.md b/docs/v2.0/insight.md index 79974dc1..c8386fdd 100644 --- a/docs/v2.0/insight.md +++ b/docs/v2.0/insight.md @@ -3,6 +3,34 @@ ## About Insight Learn more about Insight on our website, [here](https://libreqos.io/insight/). +## Insight Licensing Behavior (Node-side) + +### Local key material and offline grants + +LibreQoS stores Insight key material under: + +`/.keys/` + +Current builds can cache signed license grants locally so nodes can continue operating through temporary connectivity loss to Insight control services. Grant validity and expiration are enforced locally. + +Operational notes: +- Keep `.keys/` persistent across reboots. +- Treat `.keys/` as sensitive local key material. +- If grant or key state is invalid, `lqosd` logs will show license/grant errors. + +### Mapped circuit limits and license state + +Recent builds enforce mapped-circuit limits based on license state. + +If your node is unlicensed/invalid, LibreQoS can enforce a default mapped-circuit cap. When the cap is exceeded, logs include messages such as: +- `Mapped circuit limit reached` +- `Bakery mapped circuit cap enforced` + +When this occurs, check: +1. Insight license status in the UI. +2. `journalctl -u lqosd` for requested/allowed/dropped mapped counts. +3. Whether the number of mapped circuits exceeds your licensed allowance. + ## Insight UI ### Taskbar diff --git a/docs/v2.0/integrations.md b/docs/v2.0/integrations.md index 530b1fa0..65a09660 100644 --- a/docs/v2.0/integrations.md +++ b/docs/v2.0/integrations.md @@ -6,6 +6,7 @@ + [Splynx API Access](#splynx-api-access) + [Splynx Overrides](#splynx-overrides) * [Netzur Integration](#netzur-integration) + * [VISP Integration](#visp-integration) * [UISP Integration](#uisp-integration) + [Topology Strategies](#topology-strategies-1) + [Suspension Handling Strategies](#suspension-handling-strategies) @@ -38,10 +39,10 @@ LibreQoS supports multiple topology strategies for Splynx integration to balance | `ap_site` | Two layers: Site → AP → Clients | Medium | Site-level aggregation with moderate complexity | | `full` | Complete topology mapping | Highest | Full network hierarchy representation | -Configure the strategy in `/etc/lqos.conf` under the `[splynx]` section: +Configure the strategy in `/etc/lqos.conf` under the `[splynx_integration]` section: ```ini -[splynx] +[splynx_integration] # ... other splynx settings ... strategy = "ap_only" ``` @@ -158,6 +159,44 @@ python3 integrationNetzur.py The integration regenerates `ShapedDevices.csv` and, unless `always_overwrite_network_json` is disabled, updates `network.json`. Adjust the Integration → Common settings if you need to preserve an existing network map between Netzur syncs. +## VISP Integration + +First, set the relevant parameters for VISP in `/etc/lqos.conf`: + +```ini +[visp_integration] +enable_visp = true +client_id = "your-client-id" +client_secret = "your-client-secret" +username = "appuser-username" +password = "appuser-password" +# Optional: leave unset/blank to auto-select first ISP ID returned by token payload +# isp_id = 0 +timeout_secs = 20 +# Optional: used for online session enrichment +# online_users_domain = "" +``` + +Notes: +- VISP import is GraphQL-based and currently defaults to a flat topology strategy. +- The integration writes `ShapedDevices.csv` every run. +- `network.json` is only overwritten when `always_overwrite_network_json = true` (under `[integration_common]`). +- VISP auth tokens are cached in `/.visp_token_cache_*.json`. + +Run a manual import with: + +```bash +python3 integrationVISP.py +``` + +To run automatically through `lqos_scheduler`, set: +- `[visp_integration] enable_visp = true` +- then restart scheduler: + +```bash +sudo systemctl restart lqos_scheduler +``` + ## UISP Integration First, set the relevant parameters for UISP in `/etc/lqos.conf`. @@ -251,8 +290,31 @@ commit_bandwidth_multiplier = 0.98 # Set minimum to 98% of maximum (CIR) ipv6_with_mikrotik = false # Enable if using DHCPv6 with MikroTik always_overwrite_network_json = false # Set true to rebuild topology each run exception_cpes = [] # CPE exceptions in ["cpe:parent"] format +squash_sites = [] # Optional: sites to squash (legacy full strategy behavior) +enable_squashing = false # Optional: enable AP/single-entry squashing logic +do_not_squash_sites = [] # Optional: never squash these sites +ignore_calculated_capacity = false # Optional: keep configured capacities even if calculated differs +insecure_ssl = false # Optional: ignore UISP TLS certificate validation ``` +### UISP Advanced/Operational Options + +The following UISP options are available in current builds and Node Manager config editors: + +- `exclude_sites`: list of site names to exclude from import. +- `exception_cpes`: list of `cpe:parent` overrides for ambiguous parent assignment. +- `squash_sites`: optional list of sites to squash in full strategy workflows. +- `enable_squashing`: enables additional squashing behavior where supported. +- `do_not_squash_sites`: explicit exclusions from squashing. +- `use_ptmp_as_parent`: prefer PtMP AP as parent for relevant topology paths. +- `ignore_calculated_capacity`: prefer configured capacities instead of integration-calculated values. +- `insecure_ssl`: disables TLS certificate verification for UISP API calls. + +Recommended use: +1. Keep `insecure_ssl = false` unless you have a known internal PKI/self-signed requirement. +2. Use `exclude_sites` and `do_not_squash_sites` first for safer topology changes. +3. Apply `squash_sites`/`enable_squashing` incrementally and validate queue placement after each change. + To test the UISP Integration, use ```shell diff --git a/docs/v2.0/lts.md b/docs/v2.0/lts.md index e6ce3613..8ab254de 100644 --- a/docs/v2.0/lts.md +++ b/docs/v2.0/lts.md @@ -1,38 +1,17 @@ -# LibreQoS Long-Term Stats (LTS) +# Legacy LTS Naming (Deprecated) -## About LTS -Learn more about LTS on our website, [here](https://libreqos.io/lts/). - -## Signup -Find your LibreQoS Node ID by logging into your LibreQoS Shaper Box by SSH, and running: +```{warning} +LTS is deprecated and has been superseded by LibreQoS Insight. +For current deployments and new subscriptions, use Insight docs: +[Insight](insight.md) ``` -sed -n 's/node_id = //p' /etc/lqos.conf | sed -e 's/^"//' -e 's/"$//'` -``` -The output will be a long number - the unique identifier of your Shaper Box. -Now please visit: -``` -https://stats.libreqos.io/trial1/YOUR_NODE_ID -``` -Where YOUR_NODE_ID is the Node ID you found in the prior step. +## Migration note -If this is the first time you're using LTS - choose "Sign Up - Regular Long-Term Stats". +If you have legacy references to LTS in older internal docs/runbooks: +- Replace them with Insight references. +- Use [insight.md](insight.md) for current product behavior and workflows. +- Use [api.md](api.md) for Node API details (`/api-docs` on your node is authoritative). +- In some UI/code paths, historical names such as `lts_trial` or `config_lts` may still exist; these refer to Insight signup/config flows. -Complete the enrollment for the 30 day free trial by entering your payment information. - -The signup process will provide you with an LTS License Key. - -Head back to your Shaper Box, and edit `/etc/lqos.conf` to modify the [long_term_stats] section as follows: -``` -[long_term_stats] -gather_stats = true -collation_period_seconds = 60 -license_key = "YOUR_LICENSE_KEY" -uisp_reporting_interval_seconds = 300 -``` -Where YOUR_LICENSE_KEY is your unique LTS License Key provided in the prior step. Be sure to include the surrounding quotes. - -Now, save the file, and run `sudo systemctl restart lqosd lqos_scheduler`. This will reload the lqosd process, allowing it to start submitting data to LTS. - -## Accessing LTS -To access LTS, please visit [https://stats.libreqos.io/](https://stats.libreqos.io/) - then enter your LTS key, username (email), and password. +Legacy LTS onboarding instructions have been removed from this guide to avoid confusion for new deployments. diff --git a/docs/v2.0/node-manager-ui.md b/docs/v2.0/node-manager-ui.md new file mode 100644 index 00000000..ff6d6edd --- /dev/null +++ b/docs/v2.0/node-manager-ui.md @@ -0,0 +1,76 @@ +# LibreQoS Node Manager UI + +This page documents key Node Manager views and operational behavior in the local WebUI (`http://your_shaper_ip:9123`). + +## Core Views + +### Dashboard +- Widget-based overview of throughput, retransmits, RTT, flow counts, and queue activity. +- Dashboard content can vary by version and enabled features. + +### Network Tree Overview +- Hierarchical topology view of nodes/circuits from the shaper perspective. +- Useful for spotting bottlenecks and parent/child utilization patterns. + +### Flow Map +- Geographic flow visualization based on endpoint geolocation. +- Best used when enough recent flow data is available. + +### ASN Explorer +- ASN-centric traffic exploration (volume, RTT/retransmit context, and related flow details). +- Empty results often indicate low recent data volume rather than failure. + +### CPU Tree / CPU Weights +- Shows queue/circuit distribution by CPU core. +- Helps evaluate binpacking and load distribution behavior. + +### Shaped Devices Editor +- CRUD editor for `ShapedDevices.csv`. +- Supports paging and filtering in current builds. + +### Urgent Issues +- Node Manager can display urgent operational issues generated by backend services. +- Examples include mapping/license-limit warnings and other high-priority health events. +- Operators can acknowledge/clear issues in the UI after review. +- Common codes include `MAPPED_CIRCUIT_LIMIT` and `TC_U16_OVERFLOW` (see [Troubleshooting](troubleshooting.md#urgent-issue-codes-and-first-actions)). + +### Scheduler Status +- Node Manager surfaces scheduler health/readiness. +- Use it to quickly verify periodic refresh operation after config/integration changes. +- If status indicates errors, correlate with: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - `journalctl -u lqosd --since "30 minutes ago"` + +## Privacy / Redaction Mode + +- Toggle with the mask icon in the top navigation. +- Redaction is client-side and stored in browser local storage. +- Redaction helps hide PII in screenshots/demos. +- Redaction does not modify `ShapedDevices.csv`, `network.json`, or any backend data. + +## Common Empty-State Behavior + +The following pages may appear sparse/blank when data is low: +- Flow Map +- Tree Overview Sankey views +- ASN Explorer + +When this happens: +1. Confirm `lqosd` is healthy. +2. Wait for fresh traffic data. +3. Reload the page. +4. Check logs: + +```bash +journalctl -u lqosd --since "10 minutes ago" +``` + +## Useful Related Pages + +- [Components](components.md) +- [Configuration](configuration.md) +- [Troubleshooting](troubleshooting.md) + +## Legacy Naming Note + +Some internal page identifiers can still use historical `lts_*` naming in current builds. In operator terms, these map to Insight functionality. diff --git a/docs/v2.0/performance-tuning.md b/docs/v2.0/performance-tuning.md index fa959c36..b801ee83 100644 --- a/docs/v2.0/performance-tuning.md +++ b/docs/v2.0/performance-tuning.md @@ -1,28 +1,69 @@ # Performance Tuning -## Ubuntu Starts Slowly (~2 minutes) +## CPU and IRQ Baseline -### List all services which requires network +Set CPU frequency governor to performance on bare metal/hypervisor hosts: -```shell +```bash +sudo cpupower frequency-set --governor performance +``` + +Confirm NIC queue count and CPU distribution are sensible for your hardware: + +```bash +ethtool -l +grep -E 'CPU\\(|IRQ' /proc/interrupts | head -n 50 +``` + +If a single queue/CPU is saturated while others are idle, rebalance queue/IRQ affinity and revisit queue-count settings in `/etc/lqos.conf`. + +## Topology/Queue Pressure + +When shaping large hierarchies: + +- Prefer lower-depth integration strategies (`ap_only`/`ap_site`) unless full hierarchy is required. +- Use `promote_to_root` for large multi-site topologies to avoid single-core choke points. +- Validate Node Manager CPU Tree/CPU Weights after major topology changes. + +## Scheduler Refresh and Load + +`lqos_scheduler` refresh cadence affects control-plane load and change responsiveness. + +- Start with a conservative `queue_refresh_interval_mins`. +- Decrease interval only if your integration/API and host can handle the extra churn. +- After changing interval, monitor: + - `journalctl -u lqos_scheduler --since "30 minutes ago"` + - Node Manager scheduler status + +## StormGuard Rollout + +If using StormGuard: + +1. Start with `dry_run = true`. +2. Observe at least one busy period. +3. Move to live mode only after reviewing debug/status behavior. + +See [StormGuard](stormguard.md) for details. + +## Startup/Boot Delays + +If Ubuntu startup is slow due to network-online dependencies, inspect target dependencies: + +```bash systemctl show -p WantedBy network-online.target ``` -### For Ubuntu 22.04 this command can help +On some Ubuntu installs, disabling unused cloud/iSCSI services may help: -```shell -systemctl disable cloud-config iscsid cloud-final +```bash +sudo systemctl disable cloud-config iscsid cloud-final ``` -### Set proper governor for CPU (baremetal/hypervisior host) +Validate this against your environment before disabling services. -```shell -cpupower frequency-set --governor performance -``` +## Routing Convergence (OSPF) -### OSPF +For routed deployments, tune OSPF neighbor timers on core and edge routers to reduce outage windows during reboots: -It is recommended to set the OSPF timers of both OSPF neighbors (core and edge router) to minimize downtime upon a reboot of the LibreQoS server. - -* hello interval -* dead +- hello interval +- dead interval diff --git a/docs/v2.0/scale-topology.md b/docs/v2.0/scale-topology.md new file mode 100644 index 00000000..84e1d374 --- /dev/null +++ b/docs/v2.0/scale-topology.md @@ -0,0 +1,73 @@ +# Scale Planning and Topology Design + +This guide focuses on designing `network.json` and integration strategy choices for stable performance at scale. + +## Core Design Principles + +- Keep hierarchy only as deep as operationally necessary. +- Avoid concentrating too much traffic under one top-level parent. +- Prefer predictable naming and stable parent relationships to reduce queue churn. +- Validate topology changes in a maintenance window before broad rollout. + +## Strategy Selection by Scale + +Use the simplest integration strategy that still meets operational needs: + +| Strategy | Typical Scale Fit | Tradeoff | +|---|---|---| +| `flat` | Maximum performance, minimal hierarchy | Lowest topology visibility/aggregation | +| `ap_only` | Large AP-driven networks | Good performance, moderate visibility | +| `ap_site` | Medium to large site/AP networks | Better aggregation with moderate overhead | +| `full` | Networks requiring full path/backhaul representation | Highest control and highest CPU/memory cost | + +If `full` is required and you observe single-core saturation, use `promote_to_root` to distribute load. + +## Parent/Child Distribution Guidance + +Design goals: + +- Keep top-level parents balanced in traffic and circuit count. +- Avoid very deep branch chains unless they add real shaping value. +- Keep sibling naming unique and stable (important for virtual-node promotion and operational clarity). + +Warning signs: + +- One core persistently overloaded while others are mostly idle. +- Frequent major queue rebuilds after small integration updates. +- Node Manager CPU Tree shows skewed distribution not explained by demand. + +## Virtual Nodes and Logical Grouping + +Virtual nodes are useful for logical organization and aggregation views. + +- Use virtual nodes to improve operability and reporting structure. +- Do not use virtual nodes as a substitute for physical topology clarity. +- Validate for name collisions after promotion behavior. + +## Queue/Classifier Guardrails + +At high scale, queue/class identifier pressure can become real. + +- Monitor for urgent issues such as `TC_U16_OVERFLOW`. +- If encountered, reduce topology complexity and/or increase queue parallelism where appropriate. +- Reassess strategy depth (`full` -> `ap_site`/`ap_only`) when overflow risk appears. + +See [Troubleshooting](troubleshooting.md#urgent-issue-codes-and-first-actions) for urgent-code response steps. + +## Rollout Checklist for Topology Changes + +1. Export current `network.json` and `ShapedDevices.csv` backups. +2. Apply one topology change set at a time. +3. Run/observe `lqos_scheduler` and `lqosd` logs after each change. +4. Validate Node Manager: + - CPU Tree / CPU Weights distribution + - Flow Map/ASN/Tree behavior + - scheduler status and urgent issues +5. Keep a rollback copy of prior integration settings and topology files. + +## Related Pages + +- [Integrations](integrations.md) +- [Performance Tuning](performance-tuning.md) +- [Configuration](configuration.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/share.md b/docs/v2.0/share.md deleted file mode 100644 index c1377456..00000000 --- a/docs/v2.0/share.md +++ /dev/null @@ -1,35 +0,0 @@ -# Share your before and after - -We ask that you please share an anonymized screenshot of your LibreQoS deployment before (monitor only mode) and after (queuing enabled) to the [LibreQoS Chat](https://chat.libreqos.io/join/fvu3cerayyaumo377xwvpev6/). This helps us gauge the impact of our software. It also makes us smile. - -1. Enable monitor only mode -2. Run for 1 week -3. Disable monitor only mode -4. Toggle "Redact" to hide customer info in the LTS WebUI -5. Screenshot - -## Enable monitor only mode - -```shell -sudo nano /etc/lqos.conf -``` - -In the `[queues]` section, set `monitor_only = true` to switch to monitor only mode. - -The restart lqosd and lqos_scheduler: -```shell -sudo systemctl restart lqosd lqos_scheduler -``` - -## Disable monitor only mode - -```shell -sudo nano /etc/lqos.conf -``` - -In the `[queues]` section, set `monitor_only = false` to switch off monitor only mode. - -The restart lqosd and lqos_scheduler: -```shell -sudo systemctl restart lqosd lqos_scheduler -``` diff --git a/docs/v2.0/stormguard.md b/docs/v2.0/stormguard.md new file mode 100644 index 00000000..f0507bfe --- /dev/null +++ b/docs/v2.0/stormguard.md @@ -0,0 +1,76 @@ +# StormGuard + +StormGuard is LibreQoS' adaptive queue-adjustment subsystem for congestion and quality events. + +## What StormGuard Does + +- Monitors real-time signals (throughput, RTT/loss-related metrics, and saturation context). +- Applies bounded adjustments to configured node limits to protect quality under stress. +- Exposes status/debug data in the Node Manager UI. + +## Configuration + +StormGuard is configured in `/etc/lqos.conf` under `[stormguard]`. + +Common keys: + +- `enabled`: turns StormGuard on/off. +- `dry_run`: calculate decisions without applying live queue changes. +- `targets`: list of top-level node names to manage. +- `minimum_download_percentage`: minimum floor ratio for download limits. +- `minimum_upload_percentage`: minimum floor ratio for upload limits. +- `log_file`: optional CSV output path for decision/change telemetry. + +Example: + +```toml +[stormguard] +enabled = true +dry_run = true +log_file = "/var/log/stormguard.csv" +targets = ["SITE_A", "SITE_B"] +minimum_download_percentage = 0.5 +minimum_upload_percentage = 0.5 +``` + +If you are testing, start with `dry_run = true` so you can observe decisions before allowing live limit changes. + +## UI and Debugging + +- Node Manager provides StormGuard status and debug views. +- The StormGuard debug page shows: + - current effective limits + - evaluation metrics + - rule/decision context + +Use this during rollout validation. + +## Safe Rollout Pattern + +1. Enable StormGuard with `dry_run = true`. +2. Observe behavior for multiple peak periods. +3. Validate there are no undesirable limit oscillations. +4. Switch `dry_run = false`. +5. Continue monitoring after each major topology/integration change. + +## Troubleshooting + +If StormGuard behavior seems incorrect: + +```bash +sudo systemctl status lqosd lqos_scheduler +journalctl -u lqosd --since "30 minutes ago" +``` + +Also verify: + +- target node names still match your current `network.json` hierarchy +- integration updates have not renamed key nodes/APs +- your minimum percentage floors are reasonable for expected traffic profiles +- `log_file` path (if configured) is writable by the service user + +## Related Pages + +- [Configuration](configuration.md) +- [Components](components.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/troubleshooting.md b/docs/v2.0/troubleshooting.md index 412718c0..74c35391 100644 --- a/docs/v2.0/troubleshooting.md +++ b/docs/v2.0/troubleshooting.md @@ -44,6 +44,21 @@ sudo systemctl status lqosd lqos_scheduler The service lqos_scheduler is dependent on the lqosd service being in a healthy, running state. +### On-a-stick shaping looks wrong or one direction is weak + +On-a-stick mode depends on queue splitting per direction. If TX queue discovery is wrong or `override_available_queues` is mis-set, directional mapping can be degraded. + +Check: +``` +sudo systemctl status lqosd +journalctl -u lqosd --since "10 minutes ago" +``` + +Then verify queue-related config in `/etc/lqos.conf` and restart: +``` +sudo systemctl restart lqosd lqos_scheduler +``` + ### Service lqosd is not running or failed to start Check to see the state of the lqosd service: @@ -75,6 +90,30 @@ sudo journalctl -u lqos_scheduler --since "1 day ago" --no-pager > lqos_sched_lo ``` This exports a log file to lqos_sched_log.txt. You can review this file to see what caused the scheduler to error out. +### Scheduler status in Node Manager looks unhealthy + +Recent builds expose scheduler readiness/state in the Node Manager UI. + +If scheduler status appears down/stale: +1. Verify both services: +``` +sudo systemctl status lqosd lqos_scheduler +``` +2. Check recent scheduler logs: +``` +journalctl -u lqos_scheduler --since "30 minutes ago" +``` +3. Check lqosd bus/log state for scheduler-ready or scheduler-error messages: +``` +journalctl -u lqosd --since "30 minutes ago" +``` +4. If config/integration changes were recent, restart services cleanly: +``` +sudo systemctl restart lqosd lqos_scheduler +``` + +If status repeatedly oscillates between ready/error, collect both logs and confirm integration credentials/timeouts in `/etc/lqos.conf`. + ### RTNETLINK answers: Invalid argument This tends to show up when the MQ qdisc cannot be added correctly to the NIC interface. This would suggest the NIC has insufficient RX/TX queues. Please make sure you are using the [recommended NICs](requirements.md). @@ -103,12 +142,53 @@ Once you have identified the error and fixed ShapedDevices.csv and/or Network.js ```sudo systemctl start lqos_scheduler``` +### Flow Map / Tree Overview / ASN Explorer appears blank + +Some views require enough recent data to render meaningfully. If pages look empty: +1. Confirm `lqosd` is healthy. +2. Wait for traffic/data to accumulate. +3. Reload the page after 1-2 minutes. +4. Check logs for websocket or ticker warnings: +``` +journalctl -u lqosd --since "10 minutes ago" +``` + +If still blank under normal traffic, collect recent logs and open an issue. + ### Virtual node promotion collision (network.json) If LibreQoS.py fails with an error like `Virtual node promotion collision: 'AP_A' already exists at this level.`, you have a `"virtual": true` node whose children get promoted into a parent level where a node with the same name already exists. Rename one of the colliding nodes (names must be unique among siblings after virtual-node promotion), or restructure the hierarchy so promoted children won’t collide. +### Mapped circuit limit reached + +If logs mention messages like: +- `Mapped circuit limit reached` +- `Bakery mapped circuit cap enforced` + +LibreQoS is enforcing a mapped-circuit cap. In current builds, default behavior without active Insight licensing enforces a finite mapped-circuit limit. + +Recommended checks: +1. Confirm Insight/license status in the UI. +2. Review `lqosd` logs for requested/allowed/dropped counts. +3. Reduce mapped circuit count (short term) or update licensing/limits (long term). + +### Urgent issue codes and first actions + +Node Manager urgent issues include machine-readable codes. Use them to triage quickly. + +| Code | Meaning | First checks | Typical fix path | +|---|---|---|---| +| `MAPPED_CIRCUIT_LIMIT` | Bakery is enforcing a mapped-circuit limit. | Insight license status, `journalctl -u lqosd` for requested/allowed/dropped counts. | Reduce mapped circuits immediately or update license/limits. | +| `TC_U16_OVERFLOW` | Queue/class minor IDs exceeded the Linux tc u16 range on a CPU queue. | `journalctl -u lqos_scheduler -u lqosd`, topology depth/queue distribution. | Increase queue count and/or simplify/rebalance hierarchy (for example with integration strategy or root promotion changes). | + +Operational pattern: +1. Open urgent issue details in Node Manager (code/message/context). +2. Pull matching logs from `lqosd` and `lqos_scheduler`. +3. Apply the immediate mitigation. +4. Acknowledge/clear the issue in UI once stable. + ### Systemd segfault If you experience a segfault in systemd, this is a known issue in systemd [1](https://github.com/systemd/systemd/issues/36031) [2](https://github.com/systemd/systemd/issues/33643). diff --git a/docs/v2.0/update.md b/docs/v2.0/update.md index ef4c8d3e..87e66497 100644 --- a/docs/v2.0/update.md +++ b/docs/v2.0/update.md @@ -23,10 +23,10 @@ This will flush the old eBPF maps and load the latest LibreQoS version. ## If you installed with Git -1. Change to your `LibreQoS` directory (e.g. `cd /opt/LibreQoS`) +1. Change to your LibreQoS directory (e.g. `cd /opt/libreqos`) 2. Update from Git: `git pull` 3. ```git switch develop``` -5. Recompile: `./build-rust.sh` +5. Recompile: `./build_rust.sh` 6. `sudo rust/remove_pinned_maps.sh` Run the following commands to reload the LibreQoS services. @@ -34,3 +34,15 @@ Run the following commands to reload the LibreQoS services. ```shell sudo systemctl restart lqosd lqos_scheduler ``` + +### Notes on pinned BPF maps + +`rust/remove_pinned_maps.sh` removes pinned maps used by the eBPF/XDP pipeline so newer map schemas can load cleanly after upgrades. + +Recent versions include additional map cleanup (including `ip_mapping_epoch`). If this cleanup is skipped after a schema-changing upgrade, you may see stale behavior or mapping inconsistencies. + +If you use Git installs, keep this order: +1. build/update binaries +2. stop/restart services as needed +3. run `sudo rust/remove_pinned_maps.sh` +4. restart `lqosd` and `lqos_scheduler` diff --git a/index.rst b/index.rst index c596407e..e86390c9 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ Welcome to the LibreQoS documentation docs/v2.0/ubuntu-server docs/v2.0/bridge docs/v2.0/quickstart + docs/v2.0/git-install .. toctree:: :maxdepth: 1 @@ -24,6 +25,8 @@ Welcome to the LibreQoS documentation docs/v2.0/configuration docs/v2.0/integrations docs/v2.0/components + docs/v2.0/node-manager-ui + docs/v2.0/stormguard docs/v2.0/update docs/v2.0/troubleshooting @@ -33,10 +36,12 @@ Welcome to the LibreQoS documentation docs/v2.0/insight docs/v2.0/api + docs/v2.0/lts .. toctree:: :maxdepth: 1 :caption: Misc: docs/v2.0/cake + docs/v2.0/performance-tuning docs/v2.0/extras