diff --git a/docs-es/index.rst b/docs-es/index.rst index 4292d67a..78332572 100644 --- a/docs-es/index.rst +++ b/docs-es/index.rst @@ -13,13 +13,14 @@ 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 :caption: Gestionando LibreQoS (v1.5 a v2.0): v2.0/configuration-es + v2.0/operating-modes-es + v2.0/configuration-advanced-es v2.0/integrations-es v2.0/components-es v2.0/node-manager-ui-es diff --git a/docs-es/v2.0/components-es.md b/docs-es/v2.0/components-es.md index 18b496c2..492ab01d 100644 --- a/docs-es/v2.0/components-es.md +++ b/docs-es/v2.0/components-es.md @@ -7,7 +7,7 @@ - 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: +- Hospeda páginas de WebUI (Node Manager) como: - Mapa de flujos - Árbol de red - Explorador ASN @@ -49,9 +49,9 @@ sudo python3 scheduler.py sudo systemctl start lqos_scheduler ``` -## Modo privacidad en Node Manager +## Modo privacidad en WebUI -Node Manager incluye redacción del lado cliente para demos/capturas: +WebUI (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`. @@ -59,7 +59,7 @@ Node Manager incluye redacción del lado cliente para demos/capturas: ## Canal de problemas urgentes -Node Manager incluye un canal de problemas urgentes para eventos de alta prioridad (por ejemplo, límite de circuitos mapeados). +WebUI (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. @@ -67,7 +67,7 @@ Node Manager incluye un canal de problemas urgentes para eventos de alta priorid ## Indicador de estado del scheduler -Node Manager incluye visibilidad del estado del scheduler. +WebUI (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`. diff --git a/docs-es/v2.0/configuration-advanced-es.md b/docs-es/v2.0/configuration-advanced-es.md new file mode 100644 index 00000000..3222eaea --- /dev/null +++ b/docs-es/v2.0/configuration-advanced-es.md @@ -0,0 +1,174 @@ +# Referencia avanzada de configuración + +Use esta página cuando necesite configuración por CLI, edición directa de archivos o contenido de referencia detallado. + +## Configuración por línea de comando + +También puedes modificar ajustes usando la CLI. + +### Archivo de Configuración Principal +### /etc/lqos.conf + +La configuración para cada caja reguladora de LibreQoS se almacena en el archivo `/etc/lqos.conf`. + +Edite el archivo para que coincida con su configuración usando: + +```shell +sudo nano /etc/lqos.conf +``` + +En la sección ```[bridge]```, cambie `to_internet` y `to_network` para que coincidan con sus interfaces de red. +- `to_internet = "enp1s0f1"` +- `to_network = "enp1s0f2"` + +En la sección `[bridge]` del archivo lqos.conf, puede habilitar o deshabilitar el puente XDP con la opción `use_xdp_bridge`. El valor predeterminado es `false` - ya que la configuración por defecto asume un [Puente Linux](prereq-es.md). Si eligió usar el puente XDP durante la configuración de requisitos previos, establezca `use_xdp_bridge = true`. + +- Configure downlink_bandwidth_mbps y uplink_bandwidth_mbps para que coincidan con el ancho de banda en Mbps de la conexión WAN/Upstream de su red. Lo mismo puede hacerse para generated_pn_download_mbps y generated_pn_upload_mbps. +- to_internet es la interfaz que apunta hacia su router de borde (edge router) y el internet. +- to_network es la interfaz que apunta hacia su router interno (core router) (o la red interna puenteada, si su red está configurada de esa manera). + +Nota: Si observa que el tráfico no se está regulando cuando debería, asegúrese de invertir el orden de las interfaces y reiniciar lqosd y lqos_scheduler con: ```sudo systemctl restart lqosd lqos_scheduler```. + +Después de cambiar cualquier parte de `/etc/lqos.conf`, se recomienda reiniciar siempre lqosd usando: `sudo systemctl restart lqosd`. Esto integra los nuevos valores en lqos.conf, haciéndolos accesibles tanto para el código en Rust como en Python. + +### Netflow (opcional) +Para habilitar Netflow, agregue la siguiente sección `[flows]` al archivo de configuración `/etc/lqos.conf`, configurando el `netflow_ip` adecuado: +``` +[flows] +flow_timeout_seconds = 30 +netflow_enabled = true +netflow_port = 2055 +netflow_ip = "100.100.100.100" +netflow_version = 5 +do_not_track_subnets = ["192.168.0.0/16"] +``` + +### Integraciones con CRM/NMS + +Más información sobre [configuración de integraciones aquí.](integrations-es.md). + +## Jerarquía de Red +### Network.json + +Network.json permite a los operadores de internet (ISP) definir una topología de red jerárquica o plana. + +Si planea usar las integraciones ya incluidas en LibreQoS de UISP, Splynx o Netzur, no necesita todavía crear un archivo network.json. +Si planea usar la integración ya incluida de UISP, el archivo network.json se creará en automático durante la primera ejecución (siempre y cuando network.json no exista previamente). + +Si no planea usar una integración, puede definir manualmente el archivo network.json siguiendo el archivo de plantilla - [network.example.json](https://github.com/LibreQoE/LibreQoS/blob/develop/src/network.example.json). A continuación se muestra una ilustración en tabla del network.example.json. + +
Entire Network
Site_1Site_2
AP_ASite_3Pop_1AP_1
PoP_5AP_7
AP_9PoP_6
AP_11
+ +Para redes sin nodos padre (sin puntos de acceso o sitios estrictamente definidos), edita el network.json para usar una topología de red plana con: +``` +echo "{}" > network.json +``` + +#### Nodos virtuales (solo lógicos) + +LibreQoS soporta **nodos virtuales** en `network.json` para agrupar y para monitoreo/agregación en la WebUI/Insight. Los nodos virtuales **no** se incluyen en el árbol físico de shaping HTB (no crean clases HTB y no aplican límites de ancho de banda). + +Para marcar un nodo como virtual, configura `"virtual": true` en ese nodo. (Compatibilidad heredada: `"type": "virtual"` también se reconoce, pero se recomienda `"virtual": true` para poder mantener un `"type"` real como `"Site"` o `"AP"`.) + +Ejemplo: + +```json +{ + "Region": { + "downloadBandwidthMbps": 1000, + "uploadBandwidthMbps": 1000, + "children": { + "Town": { + "virtual": true, + "downloadBandwidthMbps": 500, + "uploadBandwidthMbps": 500, + "children": { + "AP_A": { + "downloadBandwidthMbps": 200, + "uploadBandwidthMbps": 200 + } + } + } + } + } +} +``` + +Notas: +- Durante el shaping, los nodos virtuales se eliminan y sus hijos se promueven al ancestro no virtual más cercano (revisa `queuingStructure.json` para el plan físico activo). +- `ShapedDevices.csv` aún puede usar un nodo virtual como `Parent Node` para mostrar/agrupar; LibreQoS adjuntará esos circuitos para shaping al ancestro no virtual más cercano (si el nodo virtual está en el nivel superior y no tiene ancestro no virtual, se tratará como sin nodo padre para el shaping). +- Evita colisiones de nombres después de la promoción (dos nodos con el mismo nombre terminando al mismo nivel). + +#### Consideraciones de CPU + +cpu + +#### Ayudante para convertir CSV a JSON + +Puede usar: + +```shell +python3 csvToNetworkJSON.py +``` + +para convertir manualNetwork.csv en un archivo network.json. +manualNetwork.csv puede copiarse desde el archivo de plantilla manualNetwork.template.csv. + +Nota: El nombre del nodo padre debe coincidir con el nombre usado para los clientes en ShapedDevices.csv. + +## Circuitos + +LibreQoS regula dispositivos individuales por sus direcciones IP, las cuales son agrupadas en "circuitos". + +Un circuito representa el servicio de internet de un suscriptor de la operadora de internet, el cual puede tener solo una IP asociada (por ejemplo, el router del suscriptor puede tener asignada una sola IPv4 /32) o puede tener asignado varias IPs (quizás su router tenga asignado un /29, o varias /32). + +El archivo ShapedDevices.csv correlaciona direcciones IP de dispositivos con circuitos (el servicio único de cada suscriptor de internet). + +### ShapedDevices.csv + +El archivo ShapedDevices.csv correlaciona las direcciones IP de los dispositivos con los circuitos (cada servicio único de suscriptor). + +A continuación un ejemplo de entrada en ShapedDevices.csv: +| 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 | +|------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| +| 1 | 968 Circle St., Gurnee, IL 60031 | 1 | Device 1 | AP_A | | 100.64.0.1, 100.64.0.14 | fdd7:b724:0:100::/56 | 1 | 1 | 155 | 20 | | +| 2 | 31 Marconi Street, Lake In The Hills, IL 60156 | 2 | Device 2 | AP_A | | 100.64.0.2 | fdd7:b724:0:200::/56 | 1 | 1 | 105 | 18 | | +| 3 | 255 NW. Newport Ave., Jamestown, NY 14701 | 3 | Device 3 | AP_9 | | 100.64.0.3 | fdd7:b724:0:300::/56 | 1 | 1 | 105 | 18 | | +| 4 | 8493 Campfire Street, Peabody, MA 01960 | 4 | Device 4 | AP_9 | | 100.64.0.4 | fdd7:b724:0:400::/56 | 1 | 1 | 105 | 18 | | +| 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 | | +| 2794 | 6 Littleton Drive, Ringgold, GA 30736 | 6 | Device 6 | AP_11 | | 100.64.0.6 | fdd7:b724:0:600::/56 | 1 | 1 | 105 | 18 | | +| 5 | 93 Oklahoma Ave., Parsippany, NJ 07054 | 7 | Device 7 | AP_1 | | 100.64.0.7 | fdd7:b724:0:700::/56 | 1 | 1 | 155 | 20 | | +| 6 | 74 Bishop Ave., Bakersfield, CA 93306 | 8 | Device 8 | AP_1 | | 100.64.0.8 | fdd7:b724:0:800::/56 | 1 | 1 | 105 | 18 | | +| 7 | 9598 Peg Shop Drive, Lutherville Timonium, MD 21093 | 9 | Device 9 | AP_7 | | 100.64.0.9 | fdd7:b724:0:900::/56 | 1 | 1 | 105 | 18 | | +| 8 | 115 Gartner Rd., Gettysburg, PA 17325 | 10 | Device 10 | AP_7 | | 100.64.0.10 | fdd7:b724:0:a00::/56 | 1 | 1 | 105 | 18 | | +| 9 | 525 Birchpond St., Romulus, MI 48174 | 11 | Device 11 | Site_1 | | 100.64.0.11 | fdd7:b724:0:b00::/56 | 1 | 1 | 105 | 18 | | + +Si está utilizando una de nuestras integraciones con CRM, este archivo se generará automáticamente. Si no está utilizando una integración, puede editar el archivo manualmente usando la interfaz WebUI o editando directamente el archivo ShapedDevices.csv a través de la CLI. + +#### Múltiples IPs por Circuito +Si necesita listar múltiples IPv4 en el campo IPv4, o múltiples IPv6 en el campo IPv6, agregue una coma entre ellas. Si está editando con un editor CSV (LibreOffice Calc, Excel), el editor CSV automáticamente colocará comillas alrededor de los elementos separados por coma. Si usted está editando el archivo manualmente con un editor de texto como notepad o nano, por favor agregue comillas alrededor de las entradas separadas por coma. + +``` +2794,"6 Littleton Drive, Ringgold, GA 30736",5,Device 5,AP_11,,100.64.0.5,"fdd7:b724:0:500::/56,fdd7:b724:0:600::/56",1,1,105,18,"" +``` + +#### Edición Manual mediante WebUI +Navegue a la interfaz Web de LibreQoS (http://a.b.c.d:9123) y seleccione Configuration > Shaped Devices. + +#### Edición Manual mediante CLI + +- Modifique el archivo ShapedDevices.csv usando su editor de hojas de cálculo preferido (LibreOffice Calc, Excel, etc.), siguiendo el archivo de plantilla - ShapedDevices.example.csv. +- El Circuit ID es obligatorio. El Circuit ID puede ser un número o texto. Este campo NO debe incluir símbolos de hashtag (#). Cada circuito requiere un Circuit ID único – no pueden reutilizarse. Aquí, "circuito" se refiere esencialmente al servicio de un cliente. Si un cliente tiene múltiples ubicaciones en diferentes partes de su red, use un Circuit ID único para cada una. +- Se requiere al menos una dirección IPv4 o IPv6 para cada entrada. +- El nombre del Punto de Acceso o Sitio debe establecerse en el campo Parent Node. Puede dejarse en blanco para redes planas. +- El archivo ShapedDevices.csv le permite establecer el ancho de banda mínimo (garantizado) y el máximo permitido por suscriptor. +- Los valores Download Min y Upload Min de cada circuito deben ser 1 Mbps o mayores. Generalmente, deberían configurarse en 1 Mbps por defecto. +- Los valores Download Max y Upload Max de cada circuito deben ser 2 Mbps o mayores. Generalmente, corresponden al plan de velocidad contratado por el cliente. +- Recomendación: configure el ancho de banda mínimo en 1/1 y el máximo en 1.15X la velocidad anunciada del plan: + - De esta manera, cuando un AP alcance su límite, los usuarios tendrán la capacidad restante del AP distribuida equitativamente. + - Al establecer el máximo en 1.15X la velocidad contratada, se incrementa la probabilidad de que el suscriptor vea un resultado satisfactorio en un test de velocidad, incluso si hay tráfico ligero en segundo plano en su circuito (como un video HD, actualizaciones de software, etc.). + - Esto permite a los suscriptores usar hasta el limite máximo de su plan cuando el AP tiene capacidad disponible. + +Nota sobre SLAs: Para clientes con contratos SLA, donde garantizan un ancho de banda mínimo, puede configurar el plan contratado como el ancho de banda mínimo. De esta manera, cuando un AP se acerque a su límite, los clientes con SLA siempre tendrán esa velocidad disponible. Asegúrese de que la suma de los anchos de banda mínimos de los circuitos conectados a un nodo padre no supere la capacidad total de ese nodo padre. Si esto ocurre, LibreQoS tiene un mecanismo de seguridad que [reduce los mínimos a 1/1](https://github.com/LibreQoE/LibreQoS/pull/643) para todos los circuitos afectados. + +Una vez que su configuración esté completa, estará listo para ejecutar la aplicación e iniciar los [servicios systemd](./components-es.md#servicios-de-systemd) diff --git a/docs-es/v2.0/configuration-es.md b/docs-es/v2.0/configuration-es.md index c50ed2fb..023da345 100644 --- a/docs-es/v2.0/configuration-es.md +++ b/docs-es/v2.0/configuration-es.md @@ -3,231 +3,62 @@ ## Configuración inicial mediante la herramienta de instalación (desde el .deb) setup_tool -NOTAS: -- La herramienta de configuración de LibreQoS solo se controla con teclado. Usa las flechas para desplazarte y presiona ```Enter``` para seleccionar. -- Al presionar la tecla ```Q``` se cierra la herramienta sin guardar. -- Si estabas usando la herramienta y se cerró, debes ejecutar los siguientes comandos para relanzarla: +La herramienta de instalación configura puente, interfaces, ancho de banda, rangos IP y usuarios de WebUI. + +Notas: +- La herramienta se controla con teclado (`Enter` para seleccionar, `Q` para salir sin guardar). +- Si necesita volver a abrirla: ``` sudo apt remove libreqos sudo apt install ./{deb_url_v1_5} ``` -El primer paso es darle un nombre a tu Shaper Box (nodo). Por defecto se llama LibreQoS. -Usa las flechas del teclado para recorrer las secciones de configuración: - -### Bridge Mode -bridge_mode - -De manera predeterminada se selecciona el puente Linux. Si elegiste el puente XDP en el paso anterior, ajústalo aquí. - -NOTA: el modo Single Interface, como su nombre indica, es para usuarios que solo pueden usar 1 interfaz y requiere soporte especial. Para más detalles visita nuestro [Zulip Chat]. - -### Interfaces -interfaces - -Siguiendo el diagrama recomendado, la interfaz “To Internet” debe apuntar al router de borde (y, por lo tanto, a Internet) y la interfaz “To Network” debe apuntar al router central. - -### Bandwidth -bandwidth - -En el contexto del ancho de banda contratado a tu proveedor upstream, ```To Internet``` representa el ancho de banda de subida y ```To Network``` el de bajada. - -### IP Range -ip_ranges - -En esta sección debes especificar todos los rangos IP utilizados por los routers de tus clientes, incluyendo rangos para IPs estáticas. De forma predeterminada se incluyen 4 rangos comunes, como se ve en la imagen. - -*Tip: para eliminar un rango, selecciónalo con las flechas del teclado y presiona ```Tab``` hasta resaltar ``````, luego ```Enter```. - -### Web Users -web_users - -Aquí puedes crear usuarios para el panel web de LibreQoS con sus respectivos roles. Hay dos tipos: ```Admin``` y ```Read Only```. -*** -Después de guardar el archivo podrías ver el siguiente mensaje en la terminal: -``` -No VM guests are running outdated hypervisor (qemu) binaries on this host. -N: Download is performed unsandboxed as root as file '/home/libreqos/libreqos_1.5-RC2.202510052233-1_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) -``` -Ese mensaje es benigno; puedes ignorarlo. - ### Próximos pasos -Si la instalación se completó correctamente, podrás ingresar a la WebUI en ```http://tu_ip_del_shaper:9123```. En el primer ingreso podrás definir usuario y contraseña. +Después de instalar, ingrese a la WebUI en `http://tu_ip_del_shaper:9123`. -Luego, configura tu [integración con CRM o NMS](integrations-es.md) usando la página de configuración de la WebUI. Si no usas un CRM/NMS soportado, tendrás que crear un script o proceso que genere los archivos necesarios para que LibreQoS pueda regular el tráfico: `network.json` y `ShapedDevices.csv`. Los formatos se explican más adelante en esta página. +Para la mayoría de operadores: +1. Elegir modo de operación: [Modos de operación y fuente de verdad](operating-modes-es.md) +2. Configurar integración en WebUI: [Integraciones CRM/NMS](integrations-es.md) +3. Validar scheduler y shaping en WebUI: [LibreQoS WebUI (Node Manager)](node-manager-ui-es.md) ## Configuración mediante la interfaz web -La mayoría de los parámetros del shaper pueden modificarse desde la página Configuration en la WebUI (http://tu_ip_del_shaper:9123/config_general.html). +La mayoría de cambios operativos diarios se realizan en la WebUI (`http://tu_ip_del_shaper:9123/config_general.html`). + +### Dónde en la WebUI + +- Ajustes generales: `Configuration -> General` +- Ajustes de integración: `Configuration -> Integrations` +- Editor de dispositivos regulados: `Configuration -> Shaped Devices` +- Validación operativa: páginas de `WebUI (Node Manager)` (dashboard/tree/flow/scheduler) + +## Modos de operación y fuente de verdad + +Lea esto primero antes de cambios en producción: +- [Modos de operación y fuente de verdad](operating-modes-es.md) + +## Referencia avanzada de configuración + +La configuración por CLI, edición directa de archivos y referencia detallada se movió aquí: +- [Referencia avanzada de configuración](configuration-advanced-es.md) ## Configuración por línea de comando -También puedes modificar ajustes usando la CLI. +Esta sección se movió a [Referencia avanzada de configuración](configuration-advanced-es.md#configuración-por-línea-de-comando). -### Archivo de Configuración Principal -### /etc/lqos.conf +## Jerarquía de red -La configuración para cada caja reguladora de LibreQoS se almacena en el archivo `/etc/lqos.conf`. - -Edite el archivo para que coincida con su configuración usando: - -```shell -sudo nano /etc/lqos.conf -``` - -En la sección ```[bridge]```, cambie `to_internet` y `to_network` para que coincidan con sus interfaces de red. -- `to_internet = "enp1s0f1"` -- `to_network = "enp1s0f2"` - -En la sección `[bridge]` del archivo lqos.conf, puede habilitar o deshabilitar el puente XDP con la opción `use_xdp_bridge`. El valor predeterminado es `false` - ya que la configuración por defecto asume un [Puente Linux](prereq-es.md). Si eligió usar el puente XDP durante la configuración de requisitos previos, establezca `use_xdp_bridge = true`. - -- Configure downlink_bandwidth_mbps y uplink_bandwidth_mbps para que coincidan con el ancho de banda en Mbps de la conexión WAN/Upstream de su red. Lo mismo puede hacerse para generated_pn_download_mbps y generated_pn_upload_mbps. -- to_internet es la interfaz que apunta hacia su router de borde (edge router) y el internet. -- to_network es la interfaz que apunta hacia su router interno (core router) (o la red interna puenteada, si su red está configurada de esa manera). - -Nota: Si observa que el tráfico no se está regulando cuando debería, asegúrese de invertir el orden de las interfaces y reiniciar lqosd y lqos_scheduler con: ```sudo systemctl restart lqosd lqos_scheduler```. - -Después de cambiar cualquier parte de `/etc/lqos.conf`, se recomienda reiniciar siempre lqosd usando: `sudo systemctl restart lqosd`. Esto integra los nuevos valores en lqos.conf, haciéndolos accesibles tanto para el código en Rust como en Python. - -### Netflow (opcional) -Para habilitar Netflow, agregue la siguiente sección `[flows]` al archivo de configuración `/etc/lqos.conf`, configurando el `netflow_ip` adecuado: -``` -[flows] -flow_timeout_seconds = 30 -netflow_enabled = true -netflow_port = 2055 -netflow_ip = "100.100.100.100" -netflow_version = 5 -do_not_track_subnets = ["192.168.0.0/16"] -``` - -### Integraciones con CRM/NMS - -Más información sobre [configuración de integraciones aquí.](integrations-es.md). - -## Jerarquía de Red -### Network.json - -Network.json permite a los operadores de internet (ISP) definir una topología de red jerárquica o plana. - -Si planea usar las integraciones ya incluidas en LibreQoS de UISP, Splynx o Netzur, no necesita todavía crear un archivo network.json. -Si planea usar la integración ya incluida de UISP, el archivo network.json se creará en automático durante la primera ejecución (siempre y cuando network.json no exista previamente). - -Si no planea usar una integración, puede definir manualmente el archivo network.json siguiendo el archivo de plantilla - [network.example.json](https://github.com/LibreQoE/LibreQoS/blob/develop/src/network.example.json). A continuación se muestra una ilustración en tabla del network.example.json. - -
Entire Network
Site_1Site_2
AP_ASite_3Pop_1AP_1
PoP_5AP_7
AP_9PoP_6
AP_11
- -Para redes sin nodos padre (sin puntos de acceso o sitios estrictamente definidos), edita el network.json para usar una topología de red plana con: -``` -echo "{}" > network.json -``` - -#### Nodos virtuales (solo lógicos) - -LibreQoS soporta **nodos virtuales** en `network.json` para agrupar y para monitoreo/agregación en la WebUI/Insight. Los nodos virtuales **no** se incluyen en el árbol físico de shaping HTB (no crean clases HTB y no aplican límites de ancho de banda). - -Para marcar un nodo como virtual, configura `"virtual": true` en ese nodo. (Compatibilidad heredada: `"type": "virtual"` también se reconoce, pero se recomienda `"virtual": true` para poder mantener un `"type"` real como `"Site"` o `"AP"`.) - -Ejemplo: - -```json -{ - "Region": { - "downloadBandwidthMbps": 1000, - "uploadBandwidthMbps": 1000, - "children": { - "Town": { - "virtual": true, - "downloadBandwidthMbps": 500, - "uploadBandwidthMbps": 500, - "children": { - "AP_A": { - "downloadBandwidthMbps": 200, - "uploadBandwidthMbps": 200 - } - } - } - } - } -} -``` - -Notas: -- Durante el shaping, los nodos virtuales se eliminan y sus hijos se promueven al ancestro no virtual más cercano (revisa `queuingStructure.json` para el plan físico activo). -- `ShapedDevices.csv` aún puede usar un nodo virtual como `Parent Node` para mostrar/agrupar; LibreQoS adjuntará esos circuitos para shaping al ancestro no virtual más cercano (si el nodo virtual está en el nivel superior y no tiene ancestro no virtual, se tratará como sin nodo padre para el shaping). -- Evita colisiones de nombres después de la promoción (dos nodos con el mismo nombre terminando al mismo nivel). - -#### Consideraciones de CPU - -cpu - -#### Ayudante para convertir CSV a JSON - -Puede usar: - -```shell -python3 csvToNetworkJSON.py -``` - -para convertir manualNetwork.csv en un archivo network.json. -manualNetwork.csv puede copiarse desde el archivo de plantilla manualNetwork.template.csv. - -Nota: El nombre del nodo padre debe coincidir con el nombre usado para los clientes en ShapedDevices.csv. +Esta sección se movió a [Referencia avanzada de configuración](configuration-advanced-es.md#jerarquía-de-red). ## Circuitos -LibreQoS regula dispositivos individuales por sus direcciones IP, las cuales son agrupadas en "circuitos". +Esta sección se movió a [Referencia avanzada de configuración](configuration-advanced-es.md#circuitos). -Un circuito representa el servicio de internet de un suscriptor de la operadora de internet, el cual puede tener solo una IP asociada (por ejemplo, el router del suscriptor puede tener asignada una sola IPv4 /32) o puede tener asignado varias IPs (quizás su router tenga asignado un /29, o varias /32). +## Páginas relacionadas -El archivo ShapedDevices.csv correlaciona direcciones IP de dispositivos con circuitos (el servicio único de cada suscriptor de internet). - -### ShapedDevices.csv - -El archivo ShapedDevices.csv correlaciona las direcciones IP de los dispositivos con los circuitos (cada servicio único de suscriptor). - -A continuación un ejemplo de entrada en ShapedDevices.csv: -| 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 | -|------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| -| 1 | 968 Circle St., Gurnee, IL 60031 | 1 | Device 1 | AP_A | | 100.64.0.1, 100.64.0.14 | fdd7:b724:0:100::/56 | 1 | 1 | 155 | 20 | | -| 2 | 31 Marconi Street, Lake In The Hills, IL 60156 | 2 | Device 2 | AP_A | | 100.64.0.2 | fdd7:b724:0:200::/56 | 1 | 1 | 105 | 18 | | -| 3 | 255 NW. Newport Ave., Jamestown, NY 14701 | 3 | Device 3 | AP_9 | | 100.64.0.3 | fdd7:b724:0:300::/56 | 1 | 1 | 105 | 18 | | -| 4 | 8493 Campfire Street, Peabody, MA 01960 | 4 | Device 4 | AP_9 | | 100.64.0.4 | fdd7:b724:0:400::/56 | 1 | 1 | 105 | 18 | | -| 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 | | -| 2794 | 6 Littleton Drive, Ringgold, GA 30736 | 6 | Device 6 | AP_11 | | 100.64.0.6 | fdd7:b724:0:600::/56 | 1 | 1 | 105 | 18 | | -| 5 | 93 Oklahoma Ave., Parsippany, NJ 07054 | 7 | Device 7 | AP_1 | | 100.64.0.7 | fdd7:b724:0:700::/56 | 1 | 1 | 155 | 20 | | -| 6 | 74 Bishop Ave., Bakersfield, CA 93306 | 8 | Device 8 | AP_1 | | 100.64.0.8 | fdd7:b724:0:800::/56 | 1 | 1 | 105 | 18 | | -| 7 | 9598 Peg Shop Drive, Lutherville Timonium, MD 21093 | 9 | Device 9 | AP_7 | | 100.64.0.9 | fdd7:b724:0:900::/56 | 1 | 1 | 105 | 18 | | -| 8 | 115 Gartner Rd., Gettysburg, PA 17325 | 10 | Device 10 | AP_7 | | 100.64.0.10 | fdd7:b724:0:a00::/56 | 1 | 1 | 105 | 18 | | -| 9 | 525 Birchpond St., Romulus, MI 48174 | 11 | Device 11 | Site_1 | | 100.64.0.11 | fdd7:b724:0:b00::/56 | 1 | 1 | 105 | 18 | | - -Si está utilizando una de nuestras integraciones con CRM, este archivo se generará automáticamente. Si no está utilizando una integración, puede editar el archivo manualmente usando la interfaz WebUI o editando directamente el archivo ShapedDevices.csv a través de la CLI. - -#### Múltiples IPs por Circuito -Si necesita listar múltiples IPv4 en el campo IPv4, o múltiples IPv6 en el campo IPv6, agregue una coma entre ellas. Si está editando con un editor CSV (LibreOffice Calc, Excel), el editor CSV automáticamente colocará comillas alrededor de los elementos separados por coma. Si usted está editando el archivo manualmente con un editor de texto como notepad o nano, por favor agregue comillas alrededor de las entradas separadas por coma. - -``` -2794,"6 Littleton Drive, Ringgold, GA 30736",5,Device 5,AP_11,,100.64.0.5,"fdd7:b724:0:500::/56,fdd7:b724:0:600::/56",1,1,105,18,"" -``` - -#### Edición Manual mediante WebUI -Navegue a la interfaz Web de LibreQoS (http://a.b.c.d:9123) y seleccione Configuration > Shaped Devices. - -#### Edición Manual mediante CLI - -- Modifique el archivo ShapedDevices.csv usando su editor de hojas de cálculo preferido (LibreOffice Calc, Excel, etc.), siguiendo el archivo de plantilla - ShapedDevices.example.csv. -- El Circuit ID es obligatorio. El Circuit ID puede ser un número o texto. Este campo NO debe incluir símbolos de hashtag (#). Cada circuito requiere un Circuit ID único – no pueden reutilizarse. Aquí, "circuito" se refiere esencialmente al servicio de un cliente. Si un cliente tiene múltiples ubicaciones en diferentes partes de su red, use un Circuit ID único para cada una. -- Se requiere al menos una dirección IPv4 o IPv6 para cada entrada. -- El nombre del Punto de Acceso o Sitio debe establecerse en el campo Parent Node. Puede dejarse en blanco para redes planas. -- El archivo ShapedDevices.csv le permite establecer el ancho de banda mínimo (garantizado) y el máximo permitido por suscriptor. -- Los valores Download Min y Upload Min de cada circuito deben ser 1 Mbps o mayores. Generalmente, deberían configurarse en 1 Mbps por defecto. -- Los valores Download Max y Upload Max de cada circuito deben ser 2 Mbps o mayores. Generalmente, corresponden al plan de velocidad contratado por el cliente. -- Recomendación: configure el ancho de banda mínimo en 1/1 y el máximo en 1.15X la velocidad anunciada del plan: - - De esta manera, cuando un AP alcance su límite, los usuarios tendrán la capacidad restante del AP distribuida equitativamente. - - Al establecer el máximo en 1.15X la velocidad contratada, se incrementa la probabilidad de que el suscriptor vea un resultado satisfactorio en un test de velocidad, incluso si hay tráfico ligero en segundo plano en su circuito (como un video HD, actualizaciones de software, etc.). - - Esto permite a los suscriptores usar hasta el limite máximo de su plan cuando el AP tiene capacidad disponible. - -Nota sobre SLAs: Para clientes con contratos SLA, donde garantizan un ancho de banda mínimo, puede configurar el plan contratado como el ancho de banda mínimo. De esta manera, cuando un AP se acerque a su límite, los clientes con SLA siempre tendrán esa velocidad disponible. Asegúrese de que la suma de los anchos de banda mínimos de los circuitos conectados a un nodo padre no supere la capacidad total de ese nodo padre. Si esto ocurre, LibreQoS tiene un mecanismo de seguridad que [reduce los mínimos a 1/1](https://github.com/LibreQoE/LibreQoS/pull/643) para todos los circuitos afectados. - -Una vez que su configuración esté completa, estará listo para ejecutar la aplicación e iniciar los [servicios systemd](./components-es.md#servicios-de-systemd) +- [Quickstart](quickstart-es.md) +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Integraciones CRM/NMS](integrations-es.md) +- [Referencia avanzada de configuración](configuration-advanced-es.md) +- [Solución de problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/high-availability-es.md b/docs-es/v2.0/high-availability-es.md index 9db604f7..49ce9513 100644 --- a/docs-es/v2.0/high-availability-es.md +++ b/docs-es/v2.0/high-availability-es.md @@ -74,6 +74,8 @@ Si usa BGP, utilice controles de preferencia estándar para definir una ruta pri ## Documentación Relacionada - [Planificación de Escala y Diseño de Topología](scale-topology-es.md) +- [Ajuste de rendimiento](performance-tuning-es.md) +- [StormGuard](stormguard-es.md) - [Configuración](configuration-es.md) - [Integraciones](integrations-es.md) - [Resolució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 50521da4..65a6d43a 100644 --- a/docs-es/v2.0/insight-es.md +++ b/docs-es/v2.0/insight-es.md @@ -3,37 +3,6 @@ ## 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 @@ -133,3 +102,34 @@ Insight permite generar reportes asistidos por IA sobre circuitos específicos. 11 alerts La sección **Alerts** entrega advertencias automáticas sobre comportamientos fuera de norma para nodos de la red (AP, OLT, sitios, etc.). + +## 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. diff --git a/docs-es/v2.0/integrations-es.md b/docs-es/v2.0/integrations-es.md index 9d0c7216..2188dd9f 100644 --- a/docs-es/v2.0/integrations-es.md +++ b/docs-es/v2.0/integrations-es.md @@ -1,437 +1,47 @@ # Integraciones CRM/NMS - * [Integración con Splynx](#integración-con-splynx) - + [Estrategias de Topología](#estrategias-de-topología) - + [Promover Nodos a Raíz (Optimización de Rendimiento)](#promover-nodos-a-raíz-optimización-de-rendimiento) - + [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) - + [Burst](#burst) - + [Ejemplo de Configuración](#ejemplo-de-configuración) - + [Sobrescrituras de UISP](#sobrescrituras-de-uisp) - - [Sobrescrituras de Rutas UISP](#sobrescrituras-de-rutas-uisp) - * [Integración con WISPGate](#integración-con-wispgate) - * [Integración con Powercode](#integración-con-powercode) - * [Integración con Sonar](#integración-con-sonar) +La mayoría de operadores usan las integraciones incluidas. Si usa scripts propios como fuente de verdad para `network.json` y `ShapedDevices.csv`, comience por [Modos de operación y fuente de verdad](operating-modes-es.md). -## Integración con Splynx +## Elegir ruta de integración -> **⚠️ Aviso de Cambio Importante**: Antes de v1.5-RC-2, la estrategia predeterminada de Splynx era `full`. A partir de v1.5-RC-2, la estrategia predeterminada es `ap_only` para un mejor rendimiento del CPU. Si requiere el comportamiento anterior, configure explícitamente `strategy = "full"` en su sección de configuración de Splynx. +| Ruta | Mejor para | Fuente de verdad principal | +|---|---|---| +| Integración incluida | La mayoría de operadores con sistemas soportados | CRM/NMS por jobs de integración de LibreQoS | +| Fuente-de-verdad personalizada | Operadores con sincronización propia de CRM/NMS | Archivos externos generados (`network.json`, `ShapedDevices.csv`) | -Primero, configure los parámetros relevantes de Splynx (splynx_api_key, splynx_api_secret, etc.) en `/etc/lqos.conf`. +## Dónde en la WebUI -### Estrategias de Topología +- Comportamiento común de integración: `Configuration -> Integrations` +- Campos por integración: `Configuration -> Integrations` +- Validación de salud tras cambios: `WebUI -> Scheduler Status` y `WebUI -> Urgent Issues` +- Validación de resultados/topología: `WebUI -> Network Tree Overview` y `Flow Map` -LibreQoS soporta múltiples estrategias de topología para la integración con Splynx, balanceando el rendimiento del CPU con las necesidades de jerarquía de red: +## Integraciones incluidas -| Estrategia | Descripción | Impacto CPU | Caso de Uso | -|------------|-------------|-------------|-------------| -| `flat` | Solo regula suscriptores, sin jerarquía | Menor | Máximo rendimiento, regulación simple de suscriptores únicamente | -| `ap_only` | Una capa: AP → Clientes | Bajo | **Predeterminado**. Mejor balance entre rendimiento y estructura | -| `ap_site` | Dos capas: Sitio → AP → Clientes | Medio | Agregación a nivel de sitio con complejidad moderada | -| `full` | Mapeo completo de topología | Mayor | Representación completa de jerarquía de red | +- [Integración con Splynx](integrations-splynx-es.md) +- [Integración con UISP](integrations-uisp-es.md) +- [Integración con Netzur](integrations-netzur-es.md) +- [Integración con VISP](integrations-visp-es.md) +- [Integración con WISPGate](integrations-wispgate-es.md) +- [Integración con Powercode](integrations-powercode-es.md) +- [Integración con Sonar](integrations-sonar-es.md) -Configure la estrategia en `/etc/lqos.conf` bajo la sección `[splynx]`: +## Comportamiento importante de sobrescritura -```ini -[splynx] -# ... otras configuraciones de splynx ... -strategy = "ap_only" -``` +Cuando hay integraciones habilitadas: +- `ShapedDevices.csv` normalmente se regenera por jobs de sincronización. +- `network.json` también puede sobrescribirse según configuración (por ejemplo `always_overwrite_network_json`). +- Las ediciones manuales pueden sobrescribirse en el siguiente ciclo de refresco. -**Consideraciones de Rendimiento:** -- Las estrategias `flat` y `ap_only` reducen significativamente la carga del CPU al limitar la profundidad de la red -- Elija `ap_only` para la mayoría de implementaciones a menos que necesite agregación de tráfico a nivel de sitio -- Use `full` solamente si requiere representación completa de la topología de red y tiene recursos CPU adecuados +## ¿Necesita la referencia completa heredada? -### Promover Nodos a Raíz (Optimización de Rendimiento) +El contenido detallado completo se conserva aquí: +- [Referencia de integraciones (detallada)](integrations-reference-es.md) -Cuando use la estrategia de topología `full`, puede encontrar cuellos de botella de rendimiento del CPU donde todo el tráfico fluye a través de un solo sitio raíz, limitando el throughput a lo que un solo núcleo de CPU puede manejar. +## Páginas relacionadas -La función **promote_to_root** soluciona esto promoviendo sitios específicos a nodos de nivel raíz, distribuyendo la regulación de tráfico entre múltiples núcleos de CPU. - -**Configuración:** -1. Navegue a Integración → Común en la interfaz web -2. En el campo "Promover Nodos a Raíz", ingrese un nombre de sitio por línea: -``` -Sitio_Remoto_Alpha -Sitio_Remoto_Beta -Centro_Datos_Oeste -``` - -**Beneficios:** -- Elimina el cuello de botella de CPU único para redes con sitios remotos -- Distribuye la regulación de tráfico entre múltiples núcleos de CPU -- Mejora el rendimiento general de la red para topologías grandes -- Funciona tanto con integraciones de Splynx como de UISP - -**Cuándo Usar:** -- Redes con múltiples sitios remotos de alta capacidad -- Cuando use la estrategia de topología `full` y experimente limitaciones de CPU -- Redes grandes donde el tráfico del sitio raíz excede la capacidad de un solo núcleo - -### Acceso API de Splynx - -La integración con Splynx utiliza autenticación Básica. Para usar este tipo de autenticación, asegúrese de habilitar el [Acceso No Seguro](https://splynx.docs.apiary.io/#introduction/authentication) en la configuración de su clave API de Splynx. Además, la clave API de Splynx debe tener los permisos adecuados. - -| Categoría | Nombre | Permiso | -|----------------|------------------------------|------------| -| Tariff Plans | Internet | View | -| FUP | Compiler | View | -| FUP | Policies | View | -| FUP | Capped Data | View | -| FUP | CAP Tariff | View | -| FUP | FUP Limits | View | -| Customers | Customer | View | -| Customers | Customers Online | View | -| Customers | Customer Internet services | View | -| Networking | Routers | View | -| Networking | Router contention | View | -| Networking | MikroTik | View | -| Networking | Monitoring | View | -| Networking | Network Sites | View | -| Networking | IPv4 Networks | View | -| Networking | IPv4 Networks IP | View | -| Networking | CPE | View | -| Networking | CPE AP | View | -| Networking | IPv6 Networks | View | -| Networking | IPv6 Networks IP (Addresses) | View | -| Administration | Locations | View | - -Para probar la integración con Splynx, use: - -```shell -python3 integrationSplynx.py -``` - -En la primera ejecución exitosa, se crearán los archivos ShapedDevices.csv y network.json. -ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración con Splynx. - -Para asegurarse de que network.json siempre se sobrescriba con la versión más reciente obtenida por la integración, edite `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. -Luego ejecute `sudo systemctl restart lqosd`. - -Tiene la opción de ejecutar integrationSplynx.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_splynx = true``` bajo la sección ```[splynx_integration]``` en `/etc/lqos.conf`. -Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. - -### Sobrescrituras de Splynx - -También puede modificar el archivo `integrationSplynxBandwidths.csv` para sobrescribir los anchos de banda predeterminados de cada Nodo (Sitio, AP). - -Hay una plantilla disponible en la carpeta `/opt/libreqos/src`. Para usarla, copie el archivo `integrationSplynxBandwidths.template.csv` (eliminando la parte `.template` del nombre) y edítelo con la información correspondiente. Por ejemplo, si desea cambiar el bando de ancha de un sitio, ejecutaría: -``` -sudo cp /opt/libreqos/src/integrationSplynxBandwidths.template.csv /opt/libreqos/src/integrationSplynxBandwidths.csv -``` -Y luego editaría el CSV con LibreOffice o el editor de CSV de su preferencia. - -## Integración con Netzur - -Los despliegues de Netzur proporcionan un endpoint REST con información de zonas y clientes protegido con token Bearer. Configure la sección `[netzur_integration]` en `/etc/lqos.conf`: - -```ini -[netzur_integration] -enable_netzur = true -api_key = "su-token-netzur" -api_url = "https://netzur.ejemplo.com/api/libreqos" -timeout_secs = 60 -use_mikrotik_ipv6 = false -``` - -- `enable_netzur` habilita la importación automática desde `lqos_scheduler`. -- `api_key` es el token Bearer generado dentro de Netzur. -- `api_url` debe devolver un JSON con los arreglos `zones` (convertidos en sitios) y `customers` (convertidos en circuitos y dispositivos). -- `timeout_secs` permite incrementar el tiempo de espera de la petición cuando el API responde lentamente (por defecto 60 segundos). -- `use_mikrotik_ipv6` agrega prefijos IPv6 obtenidos de `mikrotikDHCPRouterList.csv`. - -Para una importación manual: - -```bash -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`. - -### Estrategias de Topología - -LibreQoS soporta múltiples estrategias de topología para la integración con UISP para equilibrar el rendimiento del CPU con las necesidades de jerarquía de red: - -| Estrategia | Descripción | Impacto en CPU | Caso de Uso | -|------------|-------------|----------------|-------------| -| `flat` | Solo regula suscriptores por velocidad del plan de servicio | Mínimo | Máximo rendimiento, regulación simple solo de suscriptores | -| `ap_only` | Regula por plan de servicio y Punto de Acceso | Bajo | Buen equilibrio entre rendimiento y control a nivel de AP | -| `ap_site` | Regula por plan de servicio, Punto de Acceso y Sitio | Medio | Agregación a nivel de sitio con complejidad moderada | -| `full` | Regula toda la red incluyendo backhauls, Sitios, APs y clientes | Alto | **Recomendado para la mayoría de implementaciones**. Jerarquía completa de red con reconocimiento de backhaul | - -**Cómo Elegir la Estrategia Correcta:** -- Use `full` para la mayoría de implementaciones para obtener reconocimiento completo de la topología de red incluyendo enlaces de backhaul -- Use `ap_site` si necesita control a nivel de sitio pero no necesita regulación de backhaul -- Use `ap_only` para mejor rendimiento cuando no se necesita agregación de sitios -- Use `flat` solo cuando el máximo rendimiento es crítico y no necesita ninguna jerarquía - -**Nota de Rendimiento:** Cuando use la estrategia `full` con redes grandes, considere usar la función **promote_to_root** (vea [Promover Nodos a Raíz](#promover-nodos-a-raíz-optimización-de-rendimiento) arriba) para distribuir la carga del CPU entre múltiples núcleos. - -### Estrategias de Manejo de Suspensiones - -Configure cómo LibreQoS maneja las cuentas de clientes suspendidos: - -| Estrategia | Descripción | Caso de Uso | -|------------|-------------|-------------| -| `none` | No manejar suspensiones | Cuando el manejo de suspensiones se gestiona en otro lugar | -| `ignore` | No agregar clientes suspendidos al mapa de red | Reduce el número de colas y mejora el rendimiento para redes con muchas cuentas suspendidas | -| `slow` | Limitar clientes suspendidos a 0.1 Mbps | Mantiene conectividad mínima para cuentas suspendidas (por ejemplo, portales de pago) | - -**Cómo Elegir una Estrategia de Suspensión:** -- Use `none` si su router de borde u otro sistema maneja las suspensiones -- Use `ignore` para reducir la carga del sistema al no crear colas para clientes suspendidos -- Use `slow` para mantener conectividad mínima (útil para portales de pago o mensajes de servicio) - -### Burst - -- En UISP, las velocidades de Descarga y Subida (Download/Upload Speed) se configuran en Mbps (por ejemplo, 100 Mbps). -- En UISP, los valores de Burst de Descarga y Subida (Download/Upload Burst) se configuran en kilobytes por segundo (kB/s). -- Conversión y conformado: - - burst_mbps = kB/s × 8 / 1000 - - Download Min = Download Speed (Mbps) × commit_bandwidth_multiplier - - Download Max = (Download Speed (Mbps) + burst_mbps) × bandwidth_overhead_factor - - Upload Min/Max se calculan igual desde Upload Speed (Mbps) y Upload Burst (kB/s) -- Ejemplo: - - Valores en UISP: Download Speed = 100 Mbps, Download Burst = 12,500 kB/s - - El burst añade 12,500 × 8 / 1000 = 100 Mbps - - Download Min = 100 × commit_bandwidth_multiplier - - Download Max = (100 + 100) × bandwidth_overhead_factor -- Referencia rápida (burst kB/s → Mbps añadidos): - - 6,250 kB/s → +50 Mbps - - 12,500 kB/s → +100 Mbps - - 25,000 kB/s → +200 Mbps -- Notas: - - Deje el burst vacío/nulo en UISP para desactivarlo. - - Si suspended_strategy está en slow, Min y Max se fijan en 0.1 Mbps. - -### Ejemplo de Configuración - -```ini -[uisp_integration] -# Configuración Principal -enable_uisp = true -token = "su-token-api-aqui" -url = "https://uisp.su_dominio.com" -site = "Nombre_Sitio_Raiz" # Sitio raíz para perspectiva de topología - -# Estrategia de Topología (ver tabla arriba) -strategy = "full" # Recomendado para la mayoría de implementaciones - -# Manejo de Suspensiones (ver tabla arriba) -suspended_strategy = "none" - -# Ajustes de Capacidad -# Las capacidades de AP reportadas por UISP pueden ser optimistas -airmax_capacity = 0.65 # Usar 65% de la capacidad reportada de AirMax -ltu_capacity = 0.95 # Usar 95% de la capacidad reportada de LTU - -# Gestión de Sitios -exclude_sites = [] # Sitios a excluir, ej: ["Sitio_Prueba", "Sitio_Lab"] -use_ptmp_as_parent = true # Para sitios conectados a través de APs PtMP - -# Ajustes de Ancho de Banda -bandwidth_overhead_factor = 1.15 # Dar a clientes 15% sobre velocidad del plan -commit_bandwidth_multiplier = 0.98 # Establecer mínimo al 98% del máximo (CIR) - -# Opciones Avanzadas -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 -cd /opt/libreqos/src -sudo /opt/libreqos/src/bin/uisp_integration -``` -En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. -Si ya existe un archivo network.json, no será sobrescrito a menos que configure ```always_overwrite_network_json = true```. - -ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración de UISP. - -Para asegurarse de que network.json siempre sea sobrescrito con la versión más reciente obtenida por la integración, edite el archivo `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. -Luego ejecute: `sudo systemctl restart lqosd`. - -Tiene la opción de ejecutar integrationUISP.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_uisp = true``` en `/etc/lqos.conf`. Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. - -### Sobrescrituras de UISP - -También puede modificar los siguientes archivos para reflejar su red con mayor precisión: -- integrationUISPbandwidths.csv -- integrationUISProutes.csv - -Cada uno de los archivos mencionados arriba tienen plantillas, las cuales están disponibles en la carpeta `/opt/libreqos/src`. Si no los encuentra, puede obtenerlos [aquí](https://github.com/LibreQoE/LibreQoS/tree/develop/src). Para utilizarlos, copie el archivo (eliminando la parte `.template` del nombre) y edítelo con la información correspondiente. -Por ejemplo, si desea cambiar el bando de ancha de un sitio, ejecutaría: -``` -sudo cp /opt/libreqos/src/integrationUISPbandwidths.template.csv /opt/libreqos/src/integrationUISPbandwidths.csv -``` -Y luego editaría el CSV con LibreOffice o el editor de CSV de su preferencia. - -#### Sobrescrituras de Rutas UISP - -El costo predeterminado entre nodos suele ser 10. La integración genera un archivo de gráfico en formato dot: `/opt/libreqos/src/graph.dot` el cuál puede visualizarse con [Graphviz](https://dreampuf.github.io/GraphvizOnline/). Esto genera un mapa con los costos de todos los enlaces. - -![image](https://github.com/user-attachments/assets/4edba4b5-c377-4659-8798-dfc40d50c859) - -Ejemplo: -Tiene Sitio 1, Sitio 2 y Sitio 3. -Existe un camino de respaldo entre Sitio 1 y Sitio 3, pero no es el preferido. -El camino preferido debería ser: Sitio 1 > Sitio 2 > Sitio 3, pero la integración conecta directamente Sitio 1 > Sitio 3 por predeterminado. - -Para solucionar esto, agregue un costo mayor al predeterminado entre Sitio 1 y Sitio 3: -``` -Site 1, Site 3, 100 -Site 3, Site 1, 100 -``` -De esta forma, el tráfico seguirá el camino: Sitio 1 > Sitio 2 > Sitio 3. - -Para aplicar el cambio, reinicie la integración ejecutando: ```sudo systemctl restart lqos_scheduler```. - -## Integración con WISPGate -Primero, configure los parámetros relevantes de WISPGate en `/etc/lqos.conf`. -Debería haber una sección como la siguiente: - -``` -[wispgate_integration] -enable_wispgate = false -wispgate_api_token = "token" -wispgate_api_url = "https://your_wispgate_url.com" -``` - -Si la sección no existe, agréguela copiando el bloque anterior. -Después, configure los valores apropiados para wispgate_api_token y wispgate_api_url, luego guarde el archivo. - -Para probar la integración con WISPGate, ejecute: - -```shell -python3 integrationWISPGate.py -``` - -En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. -ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración de WISPGate. - -Para asegurarse de que network.json siempre sea sobrescrito con la versión más reciente obtenida por la integración, edite el archivo `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. -Luego ejecute: `sudo systemctl restart lqosd`. - -Tiene la opción de ejecutar integrationWISPGate.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_wispgate = true``` en `/etc/lqos.conf`. Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. - -## Integración con Powercode - -Primero, configure los parámetros relevantes de Powercode (powercode_api_key, powercode_api_url, etc.) en `/etc/lqos.conf`. - -Para probar la integración con Powercode, ejecute: - -```shell -python3 integrationPowercode.py -``` - -En la primera ejecución exitosa, se creará el archivo ShapedDevices.csv. -Puede modificar el archivo network.json manualmente para reflejar los límites de ancho de banda de los Sitios/AP. -El archivo ShapedDevices.csv se sobrescribirá cada vez que se ejecute la integración de Powercode. -Tiene la opción de ejecutar integrationPowercode.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_powercode = true``` en `/etc/lqos.conf`. - -## Integración con Sonar - -Primero, configure los parámetros relevantes de Sonar (sonar_api_key, sonar_api_url, etc.) en `/etc/lqos.conf`. - -Para probar la integración con Sonar, ejecute: - -```shell -python3 integrationSonar.py -``` - -En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. -Si ya existe un archivo network.json, no será sobrescrito a menos que configure ```always_overwrite_network_json = true```. -Puede modificar el archivo network.json para reflejar con mayor precisión los límites de ancho de banda. -El archivo ShapedDevices.csv se sobrescribirá cada vez que se ejecute la integración de Sonar. -Tiene la opción de ejecutar integrationSonar.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_sonar = true``` en `/etc/lqos.conf`. - -## Herramientas de Terceros - -### Jesync UI Tool Dashboard -Jesync UI Tool Dashboard es un panel de control moderno, basado en la web, diseñado para facilitar, agilizar y hacer más amigable la gestión de LibreQoS y de sus archivos de integración. - -[https://github.com/jesienazareth/jesync_dashboard](https://github.com/jesienazareth/jesync_dashboard) - -### Integración MikroTik PPPoE -Este script automatiza la sincronización de los secretos PPP de MikroTik (por ejemplo, usuarios PPPoE) y los usuarios activos de hotspot con un archivo CSV compatible con LibreQoS (ShapedDevices.csv). Supervisa continuamente el router MikroTik para detectar cambios en los secretos PPP y en los usuarios activos de hotspot, como adiciones, actualizaciones o eliminaciones, y actualiza el archivo CSV en consecuencia. -El script también calcula los límites de velocidad (descarga/carga) según el perfil PPP asignado y garantiza que el archivo CSV siempre esté actualizado. - -El script está diseñado para ejecutarse como un servicio en segundo plano utilizando systemd, asegurando que se inicie automáticamente al arrancar el sistema y se reinicie en caso de algún fallo. - -[https://github.com/Kintoyyy/MikroTik-LibreQos-Integration](https://github.com/Kintoyyy/MikroTik-LibreQos-Integration) +- [Quickstart](quickstart-es.md) +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Configurar LibreQoS](configuration-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Solución de problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/integrations-netzur-es.md b/docs-es/v2.0/integrations-netzur-es.md new file mode 100644 index 00000000..0651ed73 --- /dev/null +++ b/docs-es/v2.0/integrations-netzur-es.md @@ -0,0 +1,21 @@ +# Integración con Netzur + +## Resumen + +Use esta integración cuando Netzur sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure `[netzur_integration]` en `/etc/lqos.conf`. +2. Ejecute una importación manual de prueba. +3. Habilite sincronización por scheduler. + +## Notas operativas + +- La integración regenera `ShapedDevices.csv`. +- `network.json` depende de su configuración de sobrescritura. + +## Referencia completa + +- [Referencia detallada de Netzur](integrations-reference-es.md#integración-con-netzur) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-powercode-es.md b/docs-es/v2.0/integrations-powercode-es.md new file mode 100644 index 00000000..e797a556 --- /dev/null +++ b/docs-es/v2.0/integrations-powercode-es.md @@ -0,0 +1,21 @@ +# Integración con Powercode + +## Resumen + +Use esta integración cuando Powercode sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure Powercode en `/etc/lqos.conf`. +2. Ejecute una importación manual de prueba. +3. Habilite sincronización por scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se regenera en cada sincronización. +- Revise cómo desea gestionar `network.json` en su flujo de topología. + +## Referencia completa + +- [Referencia detallada de Powercode](integrations-reference-es.md#integración-con-powercode) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-reference-es.md b/docs-es/v2.0/integrations-reference-es.md new file mode 100644 index 00000000..6a30fb16 --- /dev/null +++ b/docs-es/v2.0/integrations-reference-es.md @@ -0,0 +1,448 @@ +# Integraciones CRM/NMS + +Esta página conserva la referencia detallada heredada de integraciones. +Para el punto de entrada orientado a tareas, use [Integraciones CRM/NMS](integrations-es.md). + + * [Integración con Splynx](#integración-con-splynx) + + [Estrategias de Topología](#estrategias-de-topología) + + [Promover Nodos a Raíz (Optimización de Rendimiento)](#promover-nodos-a-raíz-optimización-de-rendimiento) + + [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) + + [Burst](#burst) + + [Ejemplo de Configuración](#ejemplo-de-configuración) + + [Sobrescrituras de UISP](#sobrescrituras-de-uisp) + - [Sobrescrituras de Rutas UISP](#sobrescrituras-de-rutas-uisp) + * [Integración con WISPGate](#integración-con-wispgate) + * [Integración con Powercode](#integración-con-powercode) + * [Integración con Sonar](#integración-con-sonar) + +La mayoría de operadores usan este camino de integraciones incluidas. +Si usa scripts propios como fuente de verdad para `network.json` y `ShapedDevices.csv`, comience por [Modos de operación y fuente de verdad](configuration-es.md#modos-de-operación-y-fuente-de-verdad). + +Comportamiento importante cuando hay integraciones habilitadas: +- `ShapedDevices.csv` normalmente se regenera por los jobs de sincronización. +- El comportamiento de sobrescritura de `network.json` depende de su configuración de integración (por ejemplo `always_overwrite_network_json`). +- Las ediciones manuales pueden sobrescribirse en el próximo ciclo de refresco. + +## Integración con Splynx + +> **⚠️ Aviso de Cambio Importante**: Antes de v1.5-RC-2, la estrategia predeterminada de Splynx era `full`. A partir de v1.5-RC-2, la estrategia predeterminada es `ap_only` para un mejor rendimiento del CPU. Si requiere el comportamiento anterior, configure explícitamente `strategy = "full"` en su sección de configuración de Splynx. + +Primero, configure los parámetros relevantes de Splynx (splynx_api_key, splynx_api_secret, etc.) en `/etc/lqos.conf`. + +### Estrategias de Topología + +LibreQoS soporta múltiples estrategias de topología para la integración con Splynx, balanceando el rendimiento del CPU con las necesidades de jerarquía de red: + +| Estrategia | Descripción | Impacto CPU | Caso de Uso | +|------------|-------------|-------------|-------------| +| `flat` | Solo regula suscriptores, sin jerarquía | Menor | Máximo rendimiento, regulación simple de suscriptores únicamente | +| `ap_only` | Una capa: AP → Clientes | Bajo | **Predeterminado**. Mejor balance entre rendimiento y estructura | +| `ap_site` | Dos capas: Sitio → AP → Clientes | Medio | Agregación a nivel de sitio con complejidad moderada | +| `full` | Mapeo completo de topología | Mayor | Representación completa de jerarquía de red | + +Configure la estrategia en `/etc/lqos.conf` bajo la sección `[splynx]`: + +```ini +[splynx] +# ... otras configuraciones de splynx ... +strategy = "ap_only" +``` + +**Consideraciones de Rendimiento:** +- Las estrategias `flat` y `ap_only` reducen significativamente la carga del CPU al limitar la profundidad de la red +- Elija `ap_only` para la mayoría de implementaciones a menos que necesite agregación de tráfico a nivel de sitio +- Use `full` solamente si requiere representación completa de la topología de red y tiene recursos CPU adecuados + +### Promover Nodos a Raíz (Optimización de Rendimiento) + +Cuando use la estrategia de topología `full`, puede encontrar cuellos de botella de rendimiento del CPU donde todo el tráfico fluye a través de un solo sitio raíz, limitando el throughput a lo que un solo núcleo de CPU puede manejar. + +La función **promote_to_root** soluciona esto promoviendo sitios específicos a nodos de nivel raíz, distribuyendo la regulación de tráfico entre múltiples núcleos de CPU. + +**Configuración:** +1. Navegue a Integración → Común en la interfaz web +2. En el campo "Promover Nodos a Raíz", ingrese un nombre de sitio por línea: +``` +Sitio_Remoto_Alpha +Sitio_Remoto_Beta +Centro_Datos_Oeste +``` + +**Beneficios:** +- Elimina el cuello de botella de CPU único para redes con sitios remotos +- Distribuye la regulación de tráfico entre múltiples núcleos de CPU +- Mejora el rendimiento general de la red para topologías grandes +- Funciona tanto con integraciones de Splynx como de UISP + +**Cuándo Usar:** +- Redes con múltiples sitios remotos de alta capacidad +- Cuando use la estrategia de topología `full` y experimente limitaciones de CPU +- Redes grandes donde el tráfico del sitio raíz excede la capacidad de un solo núcleo + +### Acceso API de Splynx + +La integración con Splynx utiliza autenticación Básica. Para usar este tipo de autenticación, asegúrese de habilitar el [Acceso No Seguro](https://splynx.docs.apiary.io/#introduction/authentication) en la configuración de su clave API de Splynx. Además, la clave API de Splynx debe tener los permisos adecuados. + +| Categoría | Nombre | Permiso | +|----------------|------------------------------|------------| +| Tariff Plans | Internet | View | +| FUP | Compiler | View | +| FUP | Policies | View | +| FUP | Capped Data | View | +| FUP | CAP Tariff | View | +| FUP | FUP Limits | View | +| Customers | Customer | View | +| Customers | Customers Online | View | +| Customers | Customer Internet services | View | +| Networking | Routers | View | +| Networking | Router contention | View | +| Networking | MikroTik | View | +| Networking | Monitoring | View | +| Networking | Network Sites | View | +| Networking | IPv4 Networks | View | +| Networking | IPv4 Networks IP | View | +| Networking | CPE | View | +| Networking | CPE AP | View | +| Networking | IPv6 Networks | View | +| Networking | IPv6 Networks IP (Addresses) | View | +| Administration | Locations | View | + +Para probar la integración con Splynx, use: + +```shell +python3 integrationSplynx.py +``` + +En la primera ejecución exitosa, se crearán los archivos ShapedDevices.csv y network.json. +ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración con Splynx. + +Para asegurarse de que network.json siempre se sobrescriba con la versión más reciente obtenida por la integración, edite `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. +Luego ejecute `sudo systemctl restart lqosd`. + +Tiene la opción de ejecutar integrationSplynx.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_splynx = true``` bajo la sección ```[splynx_integration]``` en `/etc/lqos.conf`. +Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. + +### Sobrescrituras de Splynx + +También puede modificar el archivo `integrationSplynxBandwidths.csv` para sobrescribir los anchos de banda predeterminados de cada Nodo (Sitio, AP). + +Hay una plantilla disponible en la carpeta `/opt/libreqos/src`. Para usarla, copie el archivo `integrationSplynxBandwidths.template.csv` (eliminando la parte `.template` del nombre) y edítelo con la información correspondiente. Por ejemplo, si desea cambiar el bando de ancha de un sitio, ejecutaría: +``` +sudo cp /opt/libreqos/src/integrationSplynxBandwidths.template.csv /opt/libreqos/src/integrationSplynxBandwidths.csv +``` +Y luego editaría el CSV con LibreOffice o el editor de CSV de su preferencia. + +## Integración con Netzur + +Los despliegues de Netzur proporcionan un endpoint REST con información de zonas y clientes protegido con token Bearer. Configure la sección `[netzur_integration]` en `/etc/lqos.conf`: + +```ini +[netzur_integration] +enable_netzur = true +api_key = "su-token-netzur" +api_url = "https://netzur.ejemplo.com/api/libreqos" +timeout_secs = 60 +use_mikrotik_ipv6 = false +``` + +- `enable_netzur` habilita la importación automática desde `lqos_scheduler`. +- `api_key` es el token Bearer generado dentro de Netzur. +- `api_url` debe devolver un JSON con los arreglos `zones` (convertidos en sitios) y `customers` (convertidos en circuitos y dispositivos). +- `timeout_secs` permite incrementar el tiempo de espera de la petición cuando el API responde lentamente (por defecto 60 segundos). +- `use_mikrotik_ipv6` agrega prefijos IPv6 obtenidos de `mikrotikDHCPRouterList.csv`. + +Para una importación manual: + +```bash +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`. + +### Estrategias de Topología + +LibreQoS soporta múltiples estrategias de topología para la integración con UISP para equilibrar el rendimiento del CPU con las necesidades de jerarquía de red: + +| Estrategia | Descripción | Impacto en CPU | Caso de Uso | +|------------|-------------|----------------|-------------| +| `flat` | Solo regula suscriptores por velocidad del plan de servicio | Mínimo | Máximo rendimiento, regulación simple solo de suscriptores | +| `ap_only` | Regula por plan de servicio y Punto de Acceso | Bajo | Buen equilibrio entre rendimiento y control a nivel de AP | +| `ap_site` | Regula por plan de servicio, Punto de Acceso y Sitio | Medio | Agregación a nivel de sitio con complejidad moderada | +| `full` | Regula toda la red incluyendo backhauls, Sitios, APs y clientes | Alto | **Recomendado para la mayoría de implementaciones**. Jerarquía completa de red con reconocimiento de backhaul | + +**Cómo Elegir la Estrategia Correcta:** +- Use `full` para la mayoría de implementaciones para obtener reconocimiento completo de la topología de red incluyendo enlaces de backhaul +- Use `ap_site` si necesita control a nivel de sitio pero no necesita regulación de backhaul +- Use `ap_only` para mejor rendimiento cuando no se necesita agregación de sitios +- Use `flat` solo cuando el máximo rendimiento es crítico y no necesita ninguna jerarquía + +**Nota de Rendimiento:** Cuando use la estrategia `full` con redes grandes, considere usar la función **promote_to_root** (vea [Promover Nodos a Raíz](#promover-nodos-a-raíz-optimización-de-rendimiento) arriba) para distribuir la carga del CPU entre múltiples núcleos. + +### Estrategias de Manejo de Suspensiones + +Configure cómo LibreQoS maneja las cuentas de clientes suspendidos: + +| Estrategia | Descripción | Caso de Uso | +|------------|-------------|-------------| +| `none` | No manejar suspensiones | Cuando el manejo de suspensiones se gestiona en otro lugar | +| `ignore` | No agregar clientes suspendidos al mapa de red | Reduce el número de colas y mejora el rendimiento para redes con muchas cuentas suspendidas | +| `slow` | Limitar clientes suspendidos a 0.1 Mbps | Mantiene conectividad mínima para cuentas suspendidas (por ejemplo, portales de pago) | + +**Cómo Elegir una Estrategia de Suspensión:** +- Use `none` si su router de borde u otro sistema maneja las suspensiones +- Use `ignore` para reducir la carga del sistema al no crear colas para clientes suspendidos +- Use `slow` para mantener conectividad mínima (útil para portales de pago o mensajes de servicio) + +### Burst + +- En UISP, las velocidades de Descarga y Subida (Download/Upload Speed) se configuran en Mbps (por ejemplo, 100 Mbps). +- En UISP, los valores de Burst de Descarga y Subida (Download/Upload Burst) se configuran en kilobytes por segundo (kB/s). +- Conversión y conformado: + - burst_mbps = kB/s × 8 / 1000 + - Download Min = Download Speed (Mbps) × commit_bandwidth_multiplier + - Download Max = (Download Speed (Mbps) + burst_mbps) × bandwidth_overhead_factor + - Upload Min/Max se calculan igual desde Upload Speed (Mbps) y Upload Burst (kB/s) +- Ejemplo: + - Valores en UISP: Download Speed = 100 Mbps, Download Burst = 12,500 kB/s + - El burst añade 12,500 × 8 / 1000 = 100 Mbps + - Download Min = 100 × commit_bandwidth_multiplier + - Download Max = (100 + 100) × bandwidth_overhead_factor +- Referencia rápida (burst kB/s → Mbps añadidos): + - 6,250 kB/s → +50 Mbps + - 12,500 kB/s → +100 Mbps + - 25,000 kB/s → +200 Mbps +- Notas: + - Deje el burst vacío/nulo en UISP para desactivarlo. + - Si suspended_strategy está en slow, Min y Max se fijan en 0.1 Mbps. + +### Ejemplo de Configuración + +```ini +[uisp_integration] +# Configuración Principal +enable_uisp = true +token = "su-token-api-aqui" +url = "https://uisp.su_dominio.com" +site = "Nombre_Sitio_Raiz" # Sitio raíz para perspectiva de topología + +# Estrategia de Topología (ver tabla arriba) +strategy = "full" # Recomendado para la mayoría de implementaciones + +# Manejo de Suspensiones (ver tabla arriba) +suspended_strategy = "none" + +# Ajustes de Capacidad +# Las capacidades de AP reportadas por UISP pueden ser optimistas +airmax_capacity = 0.65 # Usar 65% de la capacidad reportada de AirMax +ltu_capacity = 0.95 # Usar 95% de la capacidad reportada de LTU + +# Gestión de Sitios +exclude_sites = [] # Sitios a excluir, ej: ["Sitio_Prueba", "Sitio_Lab"] +use_ptmp_as_parent = true # Para sitios conectados a través de APs PtMP + +# Ajustes de Ancho de Banda +bandwidth_overhead_factor = 1.15 # Dar a clientes 15% sobre velocidad del plan +commit_bandwidth_multiplier = 0.98 # Establecer mínimo al 98% del máximo (CIR) + +# Opciones Avanzadas +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 WebUI (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 +cd /opt/libreqos/src +sudo /opt/libreqos/src/bin/uisp_integration +``` +En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. +Si ya existe un archivo network.json, no será sobrescrito a menos que configure ```always_overwrite_network_json = true```. + +ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración de UISP. + +Para asegurarse de que network.json siempre sea sobrescrito con la versión más reciente obtenida por la integración, edite el archivo `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. +Luego ejecute: `sudo systemctl restart lqosd`. + +Tiene la opción de ejecutar integrationUISP.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_uisp = true``` en `/etc/lqos.conf`. Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. + +### Sobrescrituras de UISP + +También puede modificar los siguientes archivos para reflejar su red con mayor precisión: +- integrationUISPbandwidths.csv +- integrationUISProutes.csv + +Cada uno de los archivos mencionados arriba tienen plantillas, las cuales están disponibles en la carpeta `/opt/libreqos/src`. Si no los encuentra, puede obtenerlos [aquí](https://github.com/LibreQoE/LibreQoS/tree/develop/src). Para utilizarlos, copie el archivo (eliminando la parte `.template` del nombre) y edítelo con la información correspondiente. +Por ejemplo, si desea cambiar el bando de ancha de un sitio, ejecutaría: +``` +sudo cp /opt/libreqos/src/integrationUISPbandwidths.template.csv /opt/libreqos/src/integrationUISPbandwidths.csv +``` +Y luego editaría el CSV con LibreOffice o el editor de CSV de su preferencia. + +#### Sobrescrituras de Rutas UISP + +El costo predeterminado entre nodos suele ser 10. La integración genera un archivo de gráfico en formato dot: `/opt/libreqos/src/graph.dot` el cuál puede visualizarse con [Graphviz](https://dreampuf.github.io/GraphvizOnline/). Esto genera un mapa con los costos de todos los enlaces. + +![image](https://github.com/user-attachments/assets/4edba4b5-c377-4659-8798-dfc40d50c859) + +Ejemplo: +Tiene Sitio 1, Sitio 2 y Sitio 3. +Existe un camino de respaldo entre Sitio 1 y Sitio 3, pero no es el preferido. +El camino preferido debería ser: Sitio 1 > Sitio 2 > Sitio 3, pero la integración conecta directamente Sitio 1 > Sitio 3 por predeterminado. + +Para solucionar esto, agregue un costo mayor al predeterminado entre Sitio 1 y Sitio 3: +``` +Site 1, Site 3, 100 +Site 3, Site 1, 100 +``` +De esta forma, el tráfico seguirá el camino: Sitio 1 > Sitio 2 > Sitio 3. + +Para aplicar el cambio, reinicie la integración ejecutando: ```sudo systemctl restart lqos_scheduler```. + +## Integración con WISPGate +Primero, configure los parámetros relevantes de WISPGate en `/etc/lqos.conf`. +Debería haber una sección como la siguiente: + +``` +[wispgate_integration] +enable_wispgate = false +wispgate_api_token = "token" +wispgate_api_url = "https://your_wispgate_url.com" +``` + +Si la sección no existe, agréguela copiando el bloque anterior. +Después, configure los valores apropiados para wispgate_api_token y wispgate_api_url, luego guarde el archivo. + +Para probar la integración con WISPGate, ejecute: + +```shell +python3 integrationWISPGate.py +``` + +En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. +ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración de WISPGate. + +Para asegurarse de que network.json siempre sea sobrescrito con la versión más reciente obtenida por la integración, edite el archivo `/etc/lqos.conf` con el comando `sudo nano /etc/lqos.conf` y configure el valor `always_overwrite_network_json` a `true`. +Luego ejecute: `sudo systemctl restart lqosd`. + +Tiene la opción de ejecutar integrationWISPGate.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_wispgate = true``` en `/etc/lqos.conf`. Una vez configurado, ejecute `sudo systemctl restart lqos_scheduler`. + +## Integración con Powercode + +Primero, configure los parámetros relevantes de Powercode (powercode_api_key, powercode_api_url, etc.) en `/etc/lqos.conf`. + +Para probar la integración con Powercode, ejecute: + +```shell +python3 integrationPowercode.py +``` + +En la primera ejecución exitosa, se creará el archivo ShapedDevices.csv. +Puede modificar el archivo network.json manualmente para reflejar los límites de ancho de banda de los Sitios/AP. +El archivo ShapedDevices.csv se sobrescribirá cada vez que se ejecute la integración de Powercode. +Tiene la opción de ejecutar integrationPowercode.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_powercode = true``` en `/etc/lqos.conf`. + +## Integración con Sonar + +Primero, configure los parámetros relevantes de Sonar (sonar_api_key, sonar_api_url, etc.) en `/etc/lqos.conf`. + +Para probar la integración con Sonar, ejecute: + +```shell +python3 integrationSonar.py +``` + +En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. +Si ya existe un archivo network.json, no será sobrescrito a menos que configure ```always_overwrite_network_json = true```. +Puede modificar el archivo network.json para reflejar con mayor precisión los límites de ancho de banda. +El archivo ShapedDevices.csv se sobrescribirá cada vez que se ejecute la integración de Sonar. +Tiene la opción de ejecutar integrationSonar.py automáticamente al iniciar el equipo y cada X minutos (configurado con el parámetro `queue_refresh_interval_mins`), lo cual es altamente recomendado. Esto se habilita estableciendo ```enable_sonar = true``` en `/etc/lqos.conf`. + +## Herramientas de Terceros + +### Jesync UI Tool Dashboard +Jesync UI Tool Dashboard es un panel de control moderno, basado en la web, diseñado para facilitar, agilizar y hacer más amigable la gestión de LibreQoS y de sus archivos de integración. + +[https://github.com/jesienazareth/jesync_dashboard](https://github.com/jesienazareth/jesync_dashboard) + +### Integración MikroTik PPPoE +Este script automatiza la sincronización de los secretos PPP de MikroTik (por ejemplo, usuarios PPPoE) y los usuarios activos de hotspot con un archivo CSV compatible con LibreQoS (ShapedDevices.csv). Supervisa continuamente el router MikroTik para detectar cambios en los secretos PPP y en los usuarios activos de hotspot, como adiciones, actualizaciones o eliminaciones, y actualiza el archivo CSV en consecuencia. +El script también calcula los límites de velocidad (descarga/carga) según el perfil PPP asignado y garantiza que el archivo CSV siempre esté actualizado. + +El script está diseñado para ejecutarse como un servicio en segundo plano utilizando systemd, asegurando que se inicie automáticamente al arrancar el sistema y se reinicie en caso de algún fallo. + +[https://github.com/Kintoyyy/MikroTik-LibreQos-Integration](https://github.com/Kintoyyy/MikroTik-LibreQos-Integration) diff --git a/docs-es/v2.0/integrations-sonar-es.md b/docs-es/v2.0/integrations-sonar-es.md new file mode 100644 index 00000000..4a184797 --- /dev/null +++ b/docs-es/v2.0/integrations-sonar-es.md @@ -0,0 +1,21 @@ +# Integración con Sonar + +## Resumen + +Use esta integración cuando Sonar sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure Sonar en `/etc/lqos.conf`. +2. Ejecute una importación manual de prueba. +3. Habilite sincronización por scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se regenera en cada sincronización. +- `network.json` depende de su configuración de sobrescritura. + +## Referencia completa + +- [Referencia detallada de Sonar](integrations-reference-es.md#integración-con-sonar) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-splynx-es.md b/docs-es/v2.0/integrations-splynx-es.md new file mode 100644 index 00000000..4685e6ad --- /dev/null +++ b/docs-es/v2.0/integrations-splynx-es.md @@ -0,0 +1,22 @@ +# Integración con Splynx + +## Resumen + +Use esta integración cuando Splynx sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure Splynx en `/etc/lqos.conf`. +2. Seleccione estrategia de topología (`flat`, `ap_only`, `ap_site`, `full`). +3. Habilite sincronización automática y reinicie scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se regenera en cada sincronización. +- `network.json` depende de `always_overwrite_network_json`. +- Use WebUI para ajustes operativos diarios. + +## Referencia completa + +- [Referencia detallada de Splynx](integrations-reference-es.md#integración-con-splynx) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-uisp-es.md b/docs-es/v2.0/integrations-uisp-es.md new file mode 100644 index 00000000..da1fc83b --- /dev/null +++ b/docs-es/v2.0/integrations-uisp-es.md @@ -0,0 +1,22 @@ +# Integración con UISP + +## Resumen + +Use esta integración cuando UISP sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure UISP en `/etc/lqos.conf`. +2. Elija estrategia de topología y estrategia de suspensión. +3. Habilite sincronización automática y reinicie scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se regenera en cada sincronización. +- `network.json` depende de `always_overwrite_network_json`. +- En modo integración, trate ediciones de archivos como temporales. + +## Referencia completa + +- [Referencia detallada de UISP](integrations-reference-es.md#integración-con-uisp) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-visp-es.md b/docs-es/v2.0/integrations-visp-es.md new file mode 100644 index 00000000..7ca23e16 --- /dev/null +++ b/docs-es/v2.0/integrations-visp-es.md @@ -0,0 +1,21 @@ +# Integración con VISP + +## Resumen + +Use esta integración cuando VISP sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure credenciales `[visp_integration]` en `/etc/lqos.conf`. +2. Ejecute una importación manual de prueba. +3. Habilite sincronización por scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se reescribe en cada ejecución. +- `network.json` se sobrescribe solo cuando está habilitado. + +## Referencia completa + +- [Referencia detallada de VISP](integrations-reference-es.md#integración-con-visp) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/integrations-wispgate-es.md b/docs-es/v2.0/integrations-wispgate-es.md new file mode 100644 index 00000000..34dd51cf --- /dev/null +++ b/docs-es/v2.0/integrations-wispgate-es.md @@ -0,0 +1,21 @@ +# Integración con WISPGate + +## Resumen + +Use esta integración cuando WISPGate sea su fuente de verdad CRM/NMS. + +## Configuración básica + +1. Configure WISPGate en `/etc/lqos.conf`. +2. Ejecute una importación manual de prueba. +3. Habilite sincronización por scheduler. + +## Notas operativas + +- `ShapedDevices.csv` se regenera en cada sincronización. +- `network.json` depende de su configuración de sobrescritura. + +## Referencia completa + +- [Referencia detallada de WISPGate](integrations-reference-es.md#integración-con-wispgate) +- [Modos de operación y fuente de verdad](operating-modes-es.md) diff --git a/docs-es/v2.0/node-manager-ui-es.md b/docs-es/v2.0/node-manager-ui-es.md index fe7f4352..d97a94fa 100644 --- a/docs-es/v2.0/node-manager-ui-es.md +++ b/docs-es/v2.0/node-manager-ui-es.md @@ -1,6 +1,6 @@ -# Interfaz Node Manager de LibreQoS +# Interfaz WebUI (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`). +Esta página documenta las vistas clave de la WebUI (Node Manager) y su comportamiento operativo en la interfaz local (`http://ip_del_shaper:9123`). ## Vistas principales @@ -29,13 +29,13 @@ Esta página documenta las vistas clave del Node Manager y su comportamiento ope - Incluye paginación y filtros en versiones actuales. ### Problemas urgentes -- Node Manager puede mostrar problemas operativos urgentes emitidos por servicios backend. +- WebUI 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. +- WebUI 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"` diff --git a/docs-es/v2.0/operating-modes-es.md b/docs-es/v2.0/operating-modes-es.md new file mode 100644 index 00000000..0a161acb --- /dev/null +++ b/docs-es/v2.0/operating-modes-es.md @@ -0,0 +1,35 @@ +# Modos de operación y fuente de verdad + +LibreQoS soporta dos modos de operación principales. + +## Integraciones incluidas (recomendado para la mayoría de operadores) + +En este modo, su CRM/NMS es la fuente de verdad y los jobs de integración de LibreQoS generan los insumos de shaping. + +Comportamiento clave: +- `ShapedDevices.csv` se regenera en ciclos de sincronización. +- El comportamiento de sobrescritura de `network.json` depende de la configuración de integración (por ejemplo `always_overwrite_network_json`). +- Las ediciones manuales directas pueden sobrescribirse en el siguiente refresco del scheduler. + +## Fuente-de-verdad personalizada + +En este modo, sus propios scripts/sistemas generan `network.json` y `ShapedDevices.csv`. + +Comportamiento clave: +- Su flujo externo controla la persistencia. +- Las ediciones por WebUI son válidas para cambios operativos rápidos. +- Los cambios permanentes deben mantenerse en su flujo externo de fuente de verdad. + +## Lista de verificación de modo (antes de producción) + +1. Elija una fuente de verdad principal. +2. Confirme qué sistema puede escribir insumos de shaping en producción. +3. Confirme el comportamiento de refresco del scheduler y la cadencia de sobrescritura. +4. Documente su flujo de cambios rápidos (WebUI, editor externo, o ambos). +5. No mantenga ediciones en competencia en varios sistemas para los mismos objetos. + +## Páginas relacionadas + +- [Configurar LibreQoS](configuration-es.md) +- [Integraciones CRM/NMS](integrations-es.md) +- [Referencia avanzada de configuración](configuration-advanced-es.md) diff --git a/docs-es/v2.0/performance-tuning-es.md b/docs-es/v2.0/performance-tuning-es.md index b1125d84..8308bf02 100644 --- a/docs-es/v2.0/performance-tuning-es.md +++ b/docs-es/v2.0/performance-tuning-es.md @@ -23,7 +23,7 @@ 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. +- Valide CPU Tree/CPU Weights en WebUI después de cambios topológicos importantes. Consulte también [Escalado y diseño de topología](scale-topology-es.md). @@ -35,7 +35,7 @@ La cadencia de `lqos_scheduler` afecta carga del plano de control y velocidad de - 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 + - estado del scheduler en WebUI ## Despliegue de StormGuard @@ -69,3 +69,10 @@ Para despliegues enrutados, ajuste timers OSPF entre core y edge para reducir ve - hello interval - dead interval + +## Páginas relacionadas de optimización y resiliencia + +- [Escalado y diseño de topología](scale-topology-es.md) +- [StormGuard](stormguard-es.md) +- [Alta Disponibilidad y Dominios de Falla](high-availability-es.md) +- [Solución de problemas](troubleshooting-es.md) diff --git a/docs-es/v2.0/quickstart-es.md b/docs-es/v2.0/quickstart-es.md index 4b7a0c4a..872818bb 100644 --- a/docs-es/v2.0/quickstart-es.md +++ b/docs-es/v2.0/quickstart-es.md @@ -1,21 +1,29 @@ -# Instalar LibreQoS +# Quickstart: Elija su ruta de despliegue -## Paso 1 - Validar Suposiciones de Diseño de Red y Selección de Hardware +LibreQoS soporta múltiples rutas reales de despliegue. Comience eligiendo una ruta y mantenga un único modelo de fuente de verdad para los datos de shaping. -- [Suposiciones de Diseño de Red](design-es.md) -- [Requisitos del Sistema](requirements-es.md) +## Antes de empezar -## Paso 2 - Completar los Prerrequisitos de Instalación +- La WebUI es la interfaz operativa principal después de instalar. +- Elija un modelo de fuente de verdad para `network.json` y `ShapedDevices.csv`. +- Evite ediciones en competencia entre múltiples sistemas para los mismos objetos. -- [Configuración del Servidor - Prerrequisitos](prereq-es.md) -- [Instalar Ubuntu Server 24.04](ubuntu-server-es.md) -- [Configurar Puente de Regulación](bridge-es.md) +## Testbed / Lab -## Paso 3 - Instalar LibreQoS v1.5 / Actualizar a LibreQoS v1.5 +Use esta ruta cuando quiera validar el comportamiento de LibreQoS en un entorno controlado antes de desplegar inline en producción. -### Usar Paquete .DEB (Método Recomendado) +### Flujo de configuración de laboratorio -``` +1. Arme una topología de laboratorio (caja LibreQoS + endpoints generadores de tráfico + routers opcionales para simular rutas OSPF/BGP). +2. Complete plataforma y prerrequisitos de instalación: + - [Escenarios de Despliegue](design-es.md) + - [Requisitos del Sistema](requirements-es.md) + - [Configuración del Servidor - Prerrequisitos](prereq-es.md) + - [Instalar Ubuntu Server 24.04](ubuntu-server-es.md) + - [Configurar Puente de Regulación](bridge-es.md) +3. Instale LibreQoS con paquete `.deb` (recomendado): + +```bash cd ~ sudo apt-get update sudo apt-get upgrade @@ -23,10 +31,87 @@ wget https://download.libreqos.com/{deb_url_v1_5} sudo apt install ./{deb_url_v1_5} ``` -### Instalación con Git (Solo para Desarrolladores - No Recomendado) +4. Elija una pista de prueba: + - **Lab con archivos manuales**: use `network.json` y `ShapedDevices.csv` manuales/de ejemplo. + - **Lab con integración soportada**: configure integración y valide datos importados. +5. Genere tráfico de prueba y valide en WebUI: + - comportamiento de Dashboard/Tree/Flow + - estado del scheduler + - problemas urgentes +6. Cuando el comportamiento sea el esperado, avance a una ruta de piloto inline. -[Instalación Compleja](git-install-es.md) +### Después de esta ruta -## Paso 4 - Configurar LibreQoS +- [Configurar LibreQoS](configuration-es.md) +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Integraciones CRM/NMS](integrations-es.md) +- [Solución de problemas](troubleshooting-es.md) -¡Ahora estás listo para [Configurar](configuration-es.md) LibreQoS! +## Integración Soportada + +Use esta ruta cuando su CRM/NMS esté soportado por las integraciones incluidas de LibreQoS. + +1. Complete prerrequisitos e instale LibreQoS (mismos enlaces/pasos anteriores). +2. Configure la integración en WebUI. +3. Valide en WebUI los datos importados de shaping y topología. +4. Coloque la caja LibreQoS inline para tráfico piloto. +5. Monitoree en WebUI la salud del scheduler, comportamiento de shaping y problemas urgentes. +6. Expanda del piloto a un despliegue más amplio tras observar estabilidad. + +Nota: +- En modo integración, `ShapedDevices.csv` normalmente se regenera por los jobs de sincronización. +- El comportamiento de sobrescritura de `network.json` depende de la configuración (por ejemplo `always_overwrite_network_json`). + +### Después de esta ruta + +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Integraciones CRM/NMS](integrations-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Solución de problemas](troubleshooting-es.md) + +## Integración con Script Personalizado + +Use esta ruta cuando su CRM/NMS no esté soportado y usted generará `network.json` y `ShapedDevices.csv` con scripts propios. + +1. Complete prerrequisitos e instale LibreQoS (mismos enlaces/pasos anteriores). +2. Implemente script/proceso para generar y refrescar `network.json` y `ShapedDevices.csv`. +3. Trate las salidas del script como fuente de verdad para persistencia de largo plazo. +4. Coloque la caja LibreQoS inline para tráfico piloto. +5. Use WebUI para verificaciones operativas y cambios rápidos. +6. Lleve cambios lógicos/de datos permanentes de vuelta a su pipeline de scripts. + +Nota: +- Las ediciones por WebUI son útiles para cambios operativos rápidos. +- El estado de largo plazo debe mantenerse en su flujo externo de fuente de verdad. + +### Después de esta ruta + +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Referencia avanzada de configuración](configuration-advanced-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Solución de problemas](troubleshooting-es.md) + +## Archivos Manuales (<100 suscriptores) + +Use esta ruta cuando mantenga intencionalmente `network.json` y `ShapedDevices.csv` de forma directa, sin sincronización CRM/NMS. + +Recomendado solo para redes menores a 100 suscriptores. + +1. Complete prerrequisitos e instale LibreQoS (mismos enlaces/pasos anteriores). +2. Construya y mantenga `network.json` y `ShapedDevices.csv` directamente. +3. Coloque la caja LibreQoS inline para tráfico piloto. +4. Use WebUI para validar shaping, estado del scheduler y comportamiento de topología. +5. Mantenga disciplina estricta en actualizaciones manuales (calidad de datos, consistencia y cadencia). +6. Si crece el número de suscriptores o el volumen de cambios, planifique migrar a integración soportada o integración con scripts. + +### Después de esta ruta + +- [Referencia avanzada de configuración](configuration-advanced-es.md) +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Solución de problemas](troubleshooting-es.md) + +## Instalación para desarrolladores (No recomendada para operadores) + +La instalación basada en Git sigue disponible aquí: +- [Git Install (Para Desarrolladores)](git-install-es.md) diff --git a/docs-es/v2.0/scale-topology-es.md b/docs-es/v2.0/scale-topology-es.md index 687a5c24..1d02c3bf 100644 --- a/docs-es/v2.0/scale-topology-es.md +++ b/docs-es/v2.0/scale-topology-es.md @@ -34,7 +34,7 @@ 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. +- CPU Tree de WebUI con distribución muy sesgada. ## Nodos virtuales y agrupación lógica @@ -59,7 +59,7 @@ Consulte [Solución de Problemas](troubleshooting-es.md#códigos-de-problemas-ur 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: +4. Validar en WebUI: - CPU Tree / CPU Weights - comportamiento de mapa de flujos/ASN/árbol - estado del scheduler y problemas urgentes @@ -69,5 +69,7 @@ Consulte [Solución de Problemas](troubleshooting-es.md#códigos-de-problemas-ur - [Integraciones](integrations-es.md) - [Ajuste de rendimiento](performance-tuning-es.md) +- [StormGuard](stormguard-es.md) +- [Alta Disponibilidad y Dominios de Falla](high-availability-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 index c3b0110d..52a09bef 100644 --- a/docs-es/v2.0/stormguard-es.md +++ b/docs-es/v2.0/stormguard-es.md @@ -6,7 +6,7 @@ StormGuard es el subsistema de ajuste adaptativo de colas de LibreQoS para event - 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. +- Expone estado y depuración en WebUI. ## Configuración @@ -37,7 +37,7 @@ Si está probando, comience con `dry_run = true`. ## UI y depuración -- Node Manager incluye vistas de estado y depuración de StormGuard. +- WebUI (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 @@ -70,5 +70,8 @@ También verifique: ## Páginas relacionadas - [Configuración](configuration-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Ajuste de rendimiento](performance-tuning-es.md) +- [Alta Disponibilidad y Dominios de Falla](high-availability-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 de1fa6a9..718cc8bc 100644 --- a/docs-es/v2.0/troubleshooting-es.md +++ b/docs-es/v2.0/troubleshooting-es.md @@ -1,7 +1,28 @@ # Solución de problemas +## Empiece aquí: triage por síntoma + +Use esta tabla para ir al primer check rápidamente. + +| Síntoma | Primer check | Ubicación en WebUI | Siguiente sección | +|---|---|---|---| +| No se puede acceder a la WebUI | `systemctl status lqosd` | N/A (UI no disponible) | No hay WebUI en x.x.x.x:9123 | +| Hay tráfico pero no hace shaping | verificar `to_internet` / `to_network` y servicios | WebUI Dashboard | LibreQoS está en ejecución, pero no hace shaping | +| Scheduler no saludable | revisar logs de `lqosd` y `lqos_scheduler` | WebUI -> Scheduler Status | El estado del scheduler en WebUI aparece no saludable | +| Vistas de topología/flujo vacías | confirmar tráfico reciente y estado de `lqosd` | WebUI -> Flow Map / Tree / ASN Explorer | Flow Map / Tree Overview / ASN Explorer aparecen en blanco | +| Aparece código urgente | abrir detalle y mapear código | WebUI -> Urgent Issues | Códigos de problemas urgentes y primeras acciones | +| Eventos de límite de circuitos | validar licencia y conteos mapped | Insight UI + WebUI -> Urgent Issues | Se alcanzó el límite de circuitos mapeados | + ## Problemas comunes +### Dónde en la WebUI + +- Estado de servicios y salud general: `WebUI -> Dashboard` +- Estado/readiness del scheduler: `WebUI -> Scheduler Status` +- Alertas prioritarias: `WebUI -> Urgent Issues` +- Visualización de topología/tráfico: `WebUI -> Network Tree Overview` y `Flow Map` +- Revisión de datos de shaping: `WebUI -> Shaped Devices Editor` + ### La contraseña de usuario no funciona Elimine el archivo de usuarios: @@ -62,9 +83,9 @@ sudo RUST_LOG=info /opt/libreqos/src/bin/lqosd 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 +### El estado del scheduler en WebUI aparece no saludable -Versiones recientes muestran estado/readiness del scheduler en Node Manager. +Versiones recientes muestran estado/readiness del scheduler en WebUI. Si aparece caído/desactualizado: @@ -152,7 +173,7 @@ Checks recomendados: ### Códigos de problemas urgentes y primeras acciones -Node Manager muestra códigos legibles por máquina para triage rápido. +WebUI muestra códigos legibles por máquina para triage rápido. | Código | Significado | Primeros checks | Ruta de corrección típica | |---|---|---|---| @@ -161,7 +182,7 @@ Node Manager muestra códigos legibles por máquina para triage rápido. Patrón operativo: -1. Abra el detalle del problema urgente en Node Manager (código/mensaje/contexto). +1. Abra el detalle del problema urgente en WebUI (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. @@ -195,3 +216,11 @@ Luego reinicie y valide con: ```bash systemctl --version ``` + +## Páginas relacionadas + +- [Quickstart](quickstart-es.md) +- [Configurar LibreQoS](configuration-es.md) +- [Integraciones CRM/NMS](integrations-es.md) +- [Escalado y diseño de topología](scale-topology-es.md) +- [Ajuste de rendimiento](performance-tuning-es.md) diff --git a/docs/v2.0/components.md b/docs/v2.0/components.md index 4016bc06..273783b2 100644 --- a/docs/v2.0/components.md +++ b/docs/v2.0/components.md @@ -6,7 +6,7 @@ - Manages actual XDP code. - Coded in Rust. - Runs the GUI available at http://a.b.c.d:9123 -- Hosts Node Manager pages such as: +- Hosts WebUI pages such as: - Flow Map - Network Tree Overview - ASN Explorer @@ -78,9 +78,9 @@ sudo systemctl start lqos_scheduler ### Troubleshooting Service Components Please see [Troubleshooting](troubleshooting.md). -## Node Manager privacy mode +## WebUI privacy mode -Node Manager includes a client-side redaction mode for demos/screenshots: +WebUI (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. @@ -89,7 +89,7 @@ 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). +WebUI (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. @@ -97,7 +97,7 @@ Node Manager includes an urgent issue channel for high-priority events (for exam ## Scheduler status indicator -Node Manager includes scheduler status visibility for operator awareness. +WebUI (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. diff --git a/docs/v2.0/configuration-advanced.md b/docs/v2.0/configuration-advanced.md new file mode 100644 index 00000000..6d7a3fa8 --- /dev/null +++ b/docs/v2.0/configuration-advanced.md @@ -0,0 +1,251 @@ +# Advanced Configuration Reference + +Use this page when you need CLI-driven configuration, direct file editing, or deep reference details. + +## Configuration via Command Line + +You can also modify settings using the command line. + +### Main Configuration File +#### /etc/lqos.conf + +The configuration for each LibreQoS shaper box is stored in the file `/etc/lqos.conf`. + +Edit the file to match your setup with + +```shell +sudo nano /etc/lqos.conf +``` + +In the ```[bridge]``` section, change `to_internet` and `to_network` to match your network interfaces. +- `to_internet = "enp1s0f1"` +- `to_network = "enp1s0f2"` + +In the `[bridge]` section of the lqos.conf file, you can enable or disable the XDP Bridge with the setting `use_xdp_bridge`. The default value is `false` - because the default setup assumes a [Linux Bridge](prereq.md). If you chose to use the XDP Bridge during that pre-requisites setup, please set `use_xdp_bridge = true` instead. + +- Set downlink_bandwidth_mbps and uplink_bandwidth_mbps to match the bandwidth in Mbps of your network's upstream / WAN internet connection. The same can be done for generated_pn_download_mbps and generated_pn_upload_mbps. +- to_internet would be the interface facing your edge router and the broader internet +- to_network would be the interface facing your core router (or bridged internal network if your network is bridged) + +Note: If you find that traffic is not being shaped when it should, please make sure to swap the interface order and restart lqosd as well as lqos_scheduler with ```sudo systemctl restart lqosd lqos_scheduler```. + +After changing any part of `/etc/lqos.conf` it is highly recommended to always restart lqosd, using `sudo systemctl restart lqosd`. This re-parses any new values in lqos.conf, making those new values accessible to both the Rust and Python sides of the code. + +#### Netflow (optional) +To enable netflow, add the following `[flows]` section to the `/etc/lqos.conf` configuration file, setting the appropriate `netflow_ip`: +``` +[flows] +flow_timeout_seconds = 30 +netflow_enabled = true +netflow_port = 2055 +netflow_ip = "100.100.100.100" +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 + +Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology. + +If you plan to use the built-in UISP, Splynx, or Netzur integrations, you do not need to create a network.json file quite yet. +If you plan to use the built-in UISP integration, it will create this automatically on its first run (assuming network.json is not already present). + +If you will not be using an integration, you can manually define the network.json following the template file - [network.example.json](https://github.com/LibreQoE/LibreQoS/blob/develop/src/network.example.json). Below is a table illustration of network.example.json. + +
Entire Network
Site_1Site_2
AP_ASite_3Pop_1AP_1
PoP_5AP_7
AP_9PoP_6
AP_11
+ +For networks with no Parent Nodes (no strictly defined Access Points or Sites) edit the network.json to use a Flat Network Topology with +``` +echo "{}" > network.json +``` + +##### Virtual (logical-only) nodes + +LibreQoS supports **virtual nodes** in `network.json` for organizational grouping and monitoring/aggregation in the WebUI/Insight. Virtual nodes are **not** included in the physical HTB shaping tree (they won’t create HTB classes and won’t enforce bandwidth limits). + +To mark a node as virtual, set `"virtual": true` on that node. (Legacy compatibility: `"type": "virtual"` is also recognized, but `"virtual": true` is recommended so you can keep a real `"type"` like `"Site"` or `"AP"`.) + +Example: + +```json +{ + "Region": { + "downloadBandwidthMbps": 1000, + "uploadBandwidthMbps": 1000, + "children": { + "Town": { + "virtual": true, + "downloadBandwidthMbps": 500, + "uploadBandwidthMbps": 500, + "children": { + "AP_A": { + "downloadBandwidthMbps": 200, + "uploadBandwidthMbps": 200 + } + } + } + } + } +} +``` + +Notes: +- During shaping, virtual nodes are removed and their children are promoted to the nearest non-virtual ancestor (see `queuingStructure.json` for the active physical plan). +- `ShapedDevices.csv` can still use a virtual node as a `Parent Node` for display/grouping; LibreQoS will attach those circuits for shaping to the nearest non-virtual ancestor (top-level virtual nodes will be treated as unparented for shaping). +- Avoid name collisions after promotion (two nodes with the same name ending up at the same level). + +#### CPU Considerations + +cpu + +##### CSV to JSON conversion helper + +You can use + +```shell +python3 csvToNetworkJSON.py +``` + +to convert manualNetwork.csv to a network.json file. +manualNetwork.csv can be copied from the template file, manualNetwork.template.csv + +Note: The parent node name must match that used for clients in ShapedDevices.csv + +### Circuits + +LibreQoS shapes individual devices by their IP addresses, which are grouped into "circuits". + +A circuit represents an ISP subscriber's internet service, which may have just one associated IP (the subscriber's router may be assigned a single /32 IPv4 for example) or it might have multiple IPs associated (maybe their router has a /29 assigned, or multiple /32s). + +LibreQoS knows how to shape these devices, and what Node (AP, Site, etc) they are contained by, with the ShapedDevices.csv file. + +#### ShapedDevices.csv + +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 | +|------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| +| 1 | 968 Circle St., Gurnee, IL 60031 | 1 | Device 1 | AP_A | | 100.64.0.1, 100.64.0.14 | fdd7:b724:0:100::/56 | 1 | 1 | 155 | 20 | | +| 2 | 31 Marconi Street, Lake In The Hills, IL 60156 | 2 | Device 2 | AP_A | | 100.64.0.2 | fdd7:b724:0:200::/56 | 1 | 1 | 105 | 18 | | +| 3 | 255 NW. Newport Ave., Jamestown, NY 14701 | 3 | Device 3 | AP_9 | | 100.64.0.3 | fdd7:b724:0:300::/56 | 1 | 1 | 105 | 18 | | +| 4 | 8493 Campfire Street, Peabody, MA 01960 | 4 | Device 4 | AP_9 | | 100.64.0.4 | fdd7:b724:0:400::/56 | 1 | 1 | 105 | 18 | | +| 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 | | +| 2794 | 6 Littleton Drive, Ringgold, GA 30736 | 6 | Device 6 | AP_11 | | 100.64.0.6 | fdd7:b724:0:600::/56 | 1 | 1 | 105 | 18 | | +| 5 | 93 Oklahoma Ave., Parsippany, NJ 07054 | 7 | Device 7 | AP_1 | | 100.64.0.7 | fdd7:b724:0:700::/56 | 1 | 1 | 155 | 20 | | +| 6 | 74 Bishop Ave., Bakersfield, CA 93306 | 8 | Device 8 | AP_1 | | 100.64.0.8 | fdd7:b724:0:800::/56 | 1 | 1 | 105 | 18 | | +| 7 | 9598 Peg Shop Drive, Lutherville Timonium, MD 21093 | 9 | Device 9 | AP_7 | | 100.64.0.9 | fdd7:b724:0:900::/56 | 1 | 1 | 105 | 18 | | +| 8 | 115 Gartner Rd., Gettysburg, PA 17325 | 10 | Device 10 | AP_7 | | 100.64.0.10 | fdd7:b724:0:a00::/56 | 1 | 1 | 105 | 18 | | +| 9 | 525 Birchpond St., Romulus, MI 48174 | 11 | Device 11 | Site_1 | | 100.64.0.11 | fdd7:b724:0:b00::/56 | 1 | 1 | 105 | 18 | | + +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. + +``` +2794,"6 Littleton Drive, Ringgold, GA 30736",5,Device 5,AP_11,,100.64.0.5,"fdd7:b724:0:500::/56,fdd7:b724:0:600::/56",1,1,105,18,"" +``` + +##### Manual Editing by WebUI +Navigate to the LibreQoS WebUI (http://a.b.c.d:9123) and select Configuration > Shaped Devices. + +##### Manual Editing by CLI + +- Modify the ShapedDevices.csv file using your preferred spreadsheet editor (LibreOffice Calc, Excel, etc), following the template file - ShapedDevices.example.csv +- Circuit ID is required. The Circuit ID can be a number or string. This field must NOT include any number symbols (#). Every circuit requires a unique CircuitID - they cannot be reused. Here, circuit essentially refers to a customer's service. If a customer has multiple locations on different parts of your network, use a unique CircuitID for each of those locations. +- At least one IPv4 address or IPv6 address is required for each entry. +- The Access Point or Site name should be set in the Parent Node field. Parent Node can be left blank for flat networks. +- The ShapedDevices.csv file allows you to set minimum (guaranteed), and maximum allowed bandwidth per subscriber. +- The Download Min and Upload Min for each Circuit must be 1 Mbps or greater. Generally, these should be set to 1 Mbps by default. +- The Download Max and Upload Max for each Circuit must be 2 Mbps or greater. Generally, these correspond to the customer's speed plan. +- Recommendation: set the min bandwidth to 1/1 and max to 1.15X advertised plan rate: + - This way, when an AP hits its ceiling, users have any remaining AP capacity fairly distributed between them. + - By setting the max to 1.15X the speed plan, this makes it more likely that the subscriber will see a satisfactory speed test result, even if there is some small light traffic on their circuit running in the background - such as an HD video stream, software updates, etc. + - This allows subscribers to utilize up to the maximum rate when AP has the capacity to allow that. + +Note regarding SLAs: For customers with SLA contracts that guarantee them a minimum bandwidth, you can set their plan rate as the minimum bandwidth. That way when an AP approaches its ceiling, SLA customers will always see that rate available. Make sure that the combined minimum rates for circuits connected to a parent node do not exceed the rate of the parent node. If that happens, LibreQoS has a fail-safe that will [reduce the minimums to 1/1](https://github.com/LibreQoE/LibreQoS/pull/643) for all affected circuits. + +Once your configuration is complete. You're ready to run the application and start the [systemd services](./components.md#systemd-services) diff --git a/docs/v2.0/configuration.md b/docs/v2.0/configuration.md index 131e3e95..3d74e1e1 100644 --- a/docs/v2.0/configuration.md +++ b/docs/v2.0/configuration.md @@ -3,85 +3,53 @@ ## Initial Configuration Via Setup Tool (From the .deb installer) setup_tool -NOTES: -- The LibreQoS Setup Tool can only be controlled with a keyboard. Use the arrows to move around the tool, and click ```Enter``` to Select. -- Clicking the ```Q``` key will close the setup tool without saving. -- If you are in the process of using the setup tool and it closes beforehand, in order to launch again the setup tool you will have to run the following commands: +The setup tool configures initial bridge, interface, bandwidth, IP range, and WebUI user settings. + +Notes: +- The setup tool is keyboard-driven (`Enter` to select, `Q` to quit without saving). +- If you need to relaunch it after closing: ``` sudo apt remove libreqos sudo apt install ./{deb_url_v1_5} - ``` - -The first step is to give a name to your Shaper Box (Node), by default it is named LibreQoS. -Then, you can use the arrow keys on your keyboard to go over the different setup sections, as follows: - -### Bridge Mode -bridge_mode - -By default, the Linux Bridge is selected. If you chose the XDP Bridge in previous step, please make the adjustment. - -NOTE: Single Interface mode, as it name implies, its for users that can only use 1 interface, and require special support. For more information regarding Single Interface mode, please vistit our [Zulip Chat]. - -### Interfaces -interfaces - -Following the recommended setup diagram mentioned above, the "To Internet" interface should be the one facing the Edge Router (and therefore, the Internet) and the "To Network" interface should be the one facing the Core Router. - -### Bandwidth -bandwidth - -In the context of bandwidth hired from your upstream provider, ```To Internet``` means the Upload Bandwidth, and ```To Network``` means the download bandwidth. - -### IP Range -ip_ranges - -In this section, you should specify all the ip ranges utilized by your customers' routers, including ranges for static IPs. By default, we include 4 common IP Ranges, as seen in the image above. - -*Tip: In this section, in order to remove an IP range, you have to highlight the IP range with the keyboard arrows, and then click the ```Tab``` key until `````` is highlighted, then click ```Enter```. - -### Web Users -web_users - -In this section, you can create users to access the LibreQoS Web Dashboard, with their respective roles. There's 2 different types of roles: ```Admin``` and ```Read Only```. -*** -After clicking on save file, you may see the following message on the terminal -``` -No VM guests are running outdated hypervisor (qemu) binaries on this host. -N: Download is performed unsandboxed as root as file '/home/libreqos/libreqos_1.5-RC2.202510052233-1_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied) -``` -This error is benign and does not reflect any issues. Please disregard it. + ``` ### Next Steps -If the installation is successful, you will be able to access the LibreQoS WebUI at ```http://your_shaper_ip:9123```. Upon first visit, you can specify your preferred username and password. +After install, sign in to WebUI at `http://your_shaper_ip:9123`. -Next, you will want to configure your [CRM or NMS integration](integrations.md) using the Web Interface Configuration page. If you do not use a supported CRM/NMS, you will need to create a script or process to produce the needed files for LibreQoS to shape traffic - specifically network.json and ShapedDevices.csv. The format of these files are explained in further detail in later sections of this page. +For most operators: +1. Choose your operating mode: [Operating Modes and Source of Truth](operating-modes.md) +2. Configure integration settings in WebUI: [CRM/NMS Integrations](integrations.md) +3. Validate scheduler and shaping behavior in WebUI: [LibreQoS WebUI (Node Manager)](node-manager-ui.md) ## Configuration Via Web Interface -Most LibreQoS shaper settings can be modified via the Configuration page on the WebUI (http://your_shaper_ip:9123/config_general.html). +Most day-to-day LibreQoS configuration is handled in WebUI (`http://your_shaper_ip:9123/config_general.html`). -### QoO (Quality of Outcome) profiles (`qoo_profiles.json`) +### Where in WebUI -LibreQoS displays **QoO** (Quality of Outcome) as an estimate of “Internet Quality” based on latency and loss, aligned with the IETF IPPM QoO draft: -https://datatracker.ietf.org/doc/draft-ietf-ippm-qoo/ +- General settings: `Configuration -> General` +- Integration settings: `Configuration -> Integrations` +- Shaped devices editor: `Configuration -> Shaped Devices` +- Runtime operational validation: `WebUI (Node Manager)` pages (dashboard/tree/flow/scheduler) -LibreQoS uses a **QoO profile** to define what “good” and “bad” look like for your network. Profiles are configured in `qoo_profiles.json`. +## Operating Modes and Source of Truth -#### Where the file lives +Read this first before production changes: +- [Operating Modes and Source of Truth](operating-modes.md) -LibreQoS loads profiles from: +## QoO (Quality of Outcome) profiles (`qoo_profiles.json`) + +LibreQoS displays QoO as an estimate of internet quality based on latency and loss. + +### Where the file lives `/qoo_profiles.json` -This is the same directory where LibreQoS reads/writes `network.json` and `ShapedDevices.csv` (your `lqos_directory` is set in `/etc/lqos.conf`). The WebUI also displays the resolved path on the Configuration → General page. +### Selecting a profile -#### Selecting a profile - -You can select the active profile in either place: - -- **WebUI**: Configuration → General → “QoO Profile” -- **Config file**: set `qoo_profile_id` in `/etc/lqos.conf` (top-level key) +- **WebUI**: Configuration -> General -> QoO Profile +- **Config file**: set `qoo_profile_id` in `/etc/lqos.conf` Example: @@ -90,289 +58,32 @@ Example: qoo_profile_id = "web_browsing" ``` -If `qoo_profile_id` is not set, LibreQoS uses the default profile from `qoo_profiles.json` (and otherwise falls back to `web_browsing` / first available profile). +### Applying changes -#### File format (schema v2) +- Changes to `qoo_profiles.json` are picked up automatically. +- If you change `/etc/lqos.conf`, restart `lqosd`. -`qoo_profiles.json` is strictly validated. It must contain `schema_version: 2`, an optional `default_profile_id`, and a `profiles` list. Each profile defines: +## Advanced Configuration Reference -- `latency`: one or more RTT percentiles with thresholds in **milliseconds** - - `high_ms` = good/target - - `low_ms` = bad/unacceptable -- `loss_percent`: thresholds in **percent** (0..100) (LibreQoS uses TCP retransmit fraction as a loss proxy) - - `high` = good/target - - `low` = bad/unacceptable - -Minimal example (one profile): - -```json -{ - "schema_version": 2, - "default_profile_id": "web_browsing", - "profiles": [ - { - "id": "web_browsing", - "name": "Web browsing", - "description": "Targets responsive page loads; defines acceptable interactivity.", - "latency": [{ "percentile": 95, "low_ms": 150.0, "high_ms": 50.0 }], - "loss_percent": { "low": 1.0, "high": 0.5 }, - "latency_normalization": { "mode": "none" }, - "loss_handling": "confidence_weighted" - } - ] -} -``` - -#### Applying changes - -- Changes to `qoo_profiles.json` are picked up automatically (no restart required). -- If you change `/etc/lqos.conf` (including `qoo_profile_id`), restart with `sudo systemctl restart lqosd`. -- If the profile file is missing/invalid, QoO may show as unknown (and errors will appear in `journalctl -u lqosd`). +CLI-driven configuration, direct file editing, and deep reference content were moved here: +- [Advanced Configuration Reference](configuration-advanced.md) ## Configuration via Command Line -You can also modify settings using the command line. +This section moved to [Advanced Configuration Reference](configuration-advanced.md#configuration-via-command-line). -### Main Configuration File -#### /etc/lqos.conf +## Network Hierarchy -The configuration for each LibreQoS shaper box is stored in the file `/etc/lqos.conf`. +This section moved to [Advanced Configuration Reference](configuration-advanced.md#network-hierarchy). -Edit the file to match your setup with +## Circuits -```shell -sudo nano /etc/lqos.conf -``` +This section moved to [Advanced Configuration Reference](configuration-advanced.md#circuits). -In the ```[bridge]``` section, change `to_internet` and `to_network` to match your network interfaces. -- `to_internet = "enp1s0f1"` -- `to_network = "enp1s0f2"` +## Related Pages -In the `[bridge]` section of the lqos.conf file, you can enable or disable the XDP Bridge with the setting `use_xdp_bridge`. The default value is `false` - because the default setup assumes a [Linux Bridge](prereq.md). If you chose to use the XDP Bridge during that pre-requisites setup, please set `use_xdp_bridge = true` instead. - -- Set downlink_bandwidth_mbps and uplink_bandwidth_mbps to match the bandwidth in Mbps of your network's upstream / WAN internet connection. The same can be done for generated_pn_download_mbps and generated_pn_upload_mbps. -- to_internet would be the interface facing your edge router and the broader internet -- to_network would be the interface facing your core router (or bridged internal network if your network is bridged) - -Note: If you find that traffic is not being shaped when it should, please make sure to swap the interface order and restart lqosd as well as lqos_scheduler with ```sudo systemctl restart lqosd lqos_scheduler```. - -After changing any part of `/etc/lqos.conf` it is highly recommended to always restart lqosd, using `sudo systemctl restart lqosd`. This re-parses any new values in lqos.conf, making those new values accessible to both the Rust and Python sides of the code. - -#### Netflow (optional) -To enable netflow, add the following `[flows]` section to the `/etc/lqos.conf` configuration file, setting the appropriate `netflow_ip`: -``` -[flows] -flow_timeout_seconds = 30 -netflow_enabled = true -netflow_port = 2055 -netflow_ip = "100.100.100.100" -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 - -Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology. - -If you plan to use the built-in UISP, Splynx, or Netzur integrations, you do not need to create a network.json file quite yet. -If you plan to use the built-in UISP integration, it will create this automatically on its first run (assuming network.json is not already present). - -If you will not be using an integration, you can manually define the network.json following the template file - [network.example.json](https://github.com/LibreQoE/LibreQoS/blob/develop/src/network.example.json). Below is a table illustration of network.example.json. - -
Entire Network
Site_1Site_2
AP_ASite_3Pop_1AP_1
PoP_5AP_7
AP_9PoP_6
AP_11
- -For networks with no Parent Nodes (no strictly defined Access Points or Sites) edit the network.json to use a Flat Network Topology with -``` -echo "{}" > network.json -``` - -##### Virtual (logical-only) nodes - -LibreQoS supports **virtual nodes** in `network.json` for organizational grouping and monitoring/aggregation in the WebUI/Insight. Virtual nodes are **not** included in the physical HTB shaping tree (they won’t create HTB classes and won’t enforce bandwidth limits). - -To mark a node as virtual, set `"virtual": true` on that node. (Legacy compatibility: `"type": "virtual"` is also recognized, but `"virtual": true` is recommended so you can keep a real `"type"` like `"Site"` or `"AP"`.) - -Example: - -```json -{ - "Region": { - "downloadBandwidthMbps": 1000, - "uploadBandwidthMbps": 1000, - "children": { - "Town": { - "virtual": true, - "downloadBandwidthMbps": 500, - "uploadBandwidthMbps": 500, - "children": { - "AP_A": { - "downloadBandwidthMbps": 200, - "uploadBandwidthMbps": 200 - } - } - } - } - } -} -``` - -Notes: -- During shaping, virtual nodes are removed and their children are promoted to the nearest non-virtual ancestor (see `queuingStructure.json` for the active physical plan). -- `ShapedDevices.csv` can still use a virtual node as a `Parent Node` for display/grouping; LibreQoS will attach those circuits for shaping to the nearest non-virtual ancestor (top-level virtual nodes will be treated as unparented for shaping). -- Avoid name collisions after promotion (two nodes with the same name ending up at the same level). - -#### CPU Considerations - -cpu - -##### CSV to JSON conversion helper - -You can use - -```shell -python3 csvToNetworkJSON.py -``` - -to convert manualNetwork.csv to a network.json file. -manualNetwork.csv can be copied from the template file, manualNetwork.template.csv - -Note: The parent node name must match that used for clients in ShapedDevices.csv - -### Circuits - -LibreQoS shapes individual devices by their IP addresses, which are grouped into "circuits". - -A circuit represents an ISP subscriber's internet service, which may have just one associated IP (the subscriber's router may be assigned a single /32 IPv4 for example) or it might have multiple IPs associated (maybe their router has a /29 assigned, or multiple /32s). - -LibreQoS knows how to shape these devices, and what Node (AP, Site, etc) they are contained by, with the ShapedDevices.csv file. - -#### ShapedDevices.csv - -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 | -|------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| -| 1 | 968 Circle St., Gurnee, IL 60031 | 1 | Device 1 | AP_A | | 100.64.0.1, 100.64.0.14 | fdd7:b724:0:100::/56 | 1 | 1 | 155 | 20 | | -| 2 | 31 Marconi Street, Lake In The Hills, IL 60156 | 2 | Device 2 | AP_A | | 100.64.0.2 | fdd7:b724:0:200::/56 | 1 | 1 | 105 | 18 | | -| 3 | 255 NW. Newport Ave., Jamestown, NY 14701 | 3 | Device 3 | AP_9 | | 100.64.0.3 | fdd7:b724:0:300::/56 | 1 | 1 | 105 | 18 | | -| 4 | 8493 Campfire Street, Peabody, MA 01960 | 4 | Device 4 | AP_9 | | 100.64.0.4 | fdd7:b724:0:400::/56 | 1 | 1 | 105 | 18 | | -| 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 | | -| 2794 | 6 Littleton Drive, Ringgold, GA 30736 | 6 | Device 6 | AP_11 | | 100.64.0.6 | fdd7:b724:0:600::/56 | 1 | 1 | 105 | 18 | | -| 5 | 93 Oklahoma Ave., Parsippany, NJ 07054 | 7 | Device 7 | AP_1 | | 100.64.0.7 | fdd7:b724:0:700::/56 | 1 | 1 | 155 | 20 | | -| 6 | 74 Bishop Ave., Bakersfield, CA 93306 | 8 | Device 8 | AP_1 | | 100.64.0.8 | fdd7:b724:0:800::/56 | 1 | 1 | 105 | 18 | | -| 7 | 9598 Peg Shop Drive, Lutherville Timonium, MD 21093 | 9 | Device 9 | AP_7 | | 100.64.0.9 | fdd7:b724:0:900::/56 | 1 | 1 | 105 | 18 | | -| 8 | 115 Gartner Rd., Gettysburg, PA 17325 | 10 | Device 10 | AP_7 | | 100.64.0.10 | fdd7:b724:0:a00::/56 | 1 | 1 | 105 | 18 | | -| 9 | 525 Birchpond St., Romulus, MI 48174 | 11 | Device 11 | Site_1 | | 100.64.0.11 | fdd7:b724:0:b00::/56 | 1 | 1 | 105 | 18 | | - -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. - -``` -2794,"6 Littleton Drive, Ringgold, GA 30736",5,Device 5,AP_11,,100.64.0.5,"fdd7:b724:0:500::/56,fdd7:b724:0:600::/56",1,1,105,18,"" -``` - -##### Manual Editing by WebUI -Navigate to the LibreQoS WebUI (http://a.b.c.d:9123) and select Configuration > Shaped Devices. - -##### Manual Editing by CLI - -- Modify the ShapedDevices.csv file using your preferred spreadsheet editor (LibreOffice Calc, Excel, etc), following the template file - ShapedDevices.example.csv -- Circuit ID is required. The Circuit ID can be a number or string. This field must NOT include any number symbols (#). Every circuit requires a unique CircuitID - they cannot be reused. Here, circuit essentially refers to a customer's service. If a customer has multiple locations on different parts of your network, use a unique CircuitID for each of those locations. -- At least one IPv4 address or IPv6 address is required for each entry. -- The Access Point or Site name should be set in the Parent Node field. Parent Node can be left blank for flat networks. -- The ShapedDevices.csv file allows you to set minimum (guaranteed), and maximum allowed bandwidth per subscriber. -- The Download Min and Upload Min for each Circuit must be 1 Mbps or greater. Generally, these should be set to 1 Mbps by default. -- The Download Max and Upload Max for each Circuit must be 2 Mbps or greater. Generally, these correspond to the customer's speed plan. -- Recommendation: set the min bandwidth to 1/1 and max to 1.15X advertised plan rate: - - This way, when an AP hits its ceiling, users have any remaining AP capacity fairly distributed between them. - - By setting the max to 1.15X the speed plan, this makes it more likely that the subscriber will see a satisfactory speed test result, even if there is some small light traffic on their circuit running in the background - such as an HD video stream, software updates, etc. - - This allows subscribers to utilize up to the maximum rate when AP has the capacity to allow that. - -Note regarding SLAs: For customers with SLA contracts that guarantee them a minimum bandwidth, you can set their plan rate as the minimum bandwidth. That way when an AP approaches its ceiling, SLA customers will always see that rate available. Make sure that the combined minimum rates for circuits connected to a parent node do not exceed the rate of the parent node. If that happens, LibreQoS has a fail-safe that will [reduce the minimums to 1/1](https://github.com/LibreQoE/LibreQoS/pull/643) for all affected circuits. - -Once your configuration is complete. You're ready to run the application and start the [systemd services](./components.md#systemd-services) +- [Quickstart](quickstart.md) +- [Operating Modes and Source of Truth](operating-modes.md) +- [CRM/NMS Integrations](integrations.md) +- [Advanced Configuration Reference](configuration-advanced.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/high-availability.md b/docs/v2.0/high-availability.md index ac118fbb..0680bd63 100644 --- a/docs/v2.0/high-availability.md +++ b/docs/v2.0/high-availability.md @@ -74,6 +74,8 @@ If you run BGP, use standard preference controls to make one path primary and on ## Related Documentation - [Scale Planning and Topology Design](scale-topology.md) +- [Performance Tuning](performance-tuning.md) +- [StormGuard](stormguard.md) - [Configuration](configuration.md) - [Integrations](integrations.md) - [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/insight.md b/docs/v2.0/insight.md index c8386fdd..5159f351 100644 --- a/docs/v2.0/insight.md +++ b/docs/v2.0/insight.md @@ -3,34 +3,6 @@ ## 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 @@ -126,3 +98,31 @@ LibreQoS Insight enables you to trigger AI-generated reports on specific subscri 11 alerts The Alerts section provides you with automated warnings of out-of-norm performance for nodes across the network (Access Points, OLTs, Sites). + +## 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. diff --git a/docs/v2.0/integrations-netzur.md b/docs/v2.0/integrations-netzur.md new file mode 100644 index 00000000..efa277f9 --- /dev/null +++ b/docs/v2.0/integrations-netzur.md @@ -0,0 +1,21 @@ +# Netzur Integration + +## Summary + +Use this when Netzur is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure `[netzur_integration]` values in `/etc/lqos.conf`. +2. Run a manual import test. +3. Enable scheduler-driven sync. + +## Operational Notes + +- Integration regenerates `ShapedDevices.csv`. +- `network.json` updates depend on overwrite settings. + +## Full Reference + +- [Detailed Netzur Reference](integrations-reference.md#netzur-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-powercode.md b/docs/v2.0/integrations-powercode.md new file mode 100644 index 00000000..7a1654d6 --- /dev/null +++ b/docs/v2.0/integrations-powercode.md @@ -0,0 +1,21 @@ +# Powercode Integration + +## Summary + +Use this when Powercode is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure Powercode integration settings in `/etc/lqos.conf`. +2. Run a manual import test. +3. Enable scheduler-driven sync. + +## Operational Notes + +- `ShapedDevices.csv` is regenerated on sync. +- Review how you want `network.json` handled for your topology workflow. + +## Full Reference + +- [Detailed Powercode Reference](integrations-reference.md#powercode-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-reference.md b/docs/v2.0/integrations-reference.md new file mode 100644 index 00000000..f409da6c --- /dev/null +++ b/docs/v2.0/integrations-reference.md @@ -0,0 +1,453 @@ +# CRM/NMS Integrations + +This page preserves the detailed legacy integration reference. +For the task-oriented entrypoint, use [CRM/NMS Integrations](integrations.md). + + * [Splynx Integration](#splynx-integration) + + [Topology Strategies](#topology-strategies) + + [Promote to Root Nodes (Performance Optimization)](#promote-to-root-nodes-performance-optimization) + + [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) + + [Burst](#burst) + + [Configuration Example](#configuration-example) + + [UISP Overrides](#uisp-overrides) + - [UISP Route Overrides](#uisp-route-overrides) + * [WISPGate Integration](#wispgate-integration) + * [Powercode Integration](#powercode-integration) + * [Sonar Integration](#sonar-integration) + +Most operators use this built-in integration path. +If you use your own scripts as the source of truth for `network.json` and `ShapedDevices.csv`, start with [Operating Modes and Source of Truth](configuration.md#operating-modes-and-source-of-truth). + +## What these integrations do + +These integrations work by synchronizing with your CRM/NMS system to produce the two files LibreQoS requires for shaping - [network.json](configuration.md#network-hierarchy) and [ShapedDevices.csv](configuration.md#circuits). + +Important behavior when integrations are enabled: +- `ShapedDevices.csv` is typically regenerated by integration sync jobs. +- `network.json` overwrite behavior depends on your integration settings (for example `always_overwrite_network_json`). +- Manual edits may be overwritten on the next refresh cycle. + +## Splynx Integration + +> **⚠️ Breaking Change Notice**: Prior to v1.5-RC-2, the default Splynx strategy was `full`. Starting with v1.5-RC-2, the default strategy is `ap_only` for improved CPU performance. If you require the previous behavior, explicitly set `strategy = "full"` in your Splynx configuration section. + +First, set the relevant parameters for Splynx (splynx_api_key, splynx_api_secret, etc.) in `/etc/lqos.conf`. + +### Topology Strategies + +LibreQoS supports multiple topology strategies for Splynx integration to balance CPU performance with network hierarchy needs: + +| Strategy | Description | CPU Impact | Use Case | +|----------|-------------|------------|----------| +| `flat` | Only shapes subscribers, no hierarchy | Lowest | Maximum performance, simple subscriber-only shaping | +| `ap_only` | Single layer: AP → Clients | Low | **Default**. Best balance of performance and structure | +| `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_integration]` section: + +```ini +[splynx_integration] +# ... other splynx settings ... +strategy = "ap_only" +``` + +**Performance Considerations:** +- `flat` and `ap_only` strategies significantly reduce CPU load by limiting network depth +- Choose `ap_only` for most deployments unless you need site-level traffic aggregation +- Only use `full` if you require complete network topology representation and have adequate CPU resources + +### Promote to Root Nodes (Performance Optimization) + +When using `full` topology strategy, you may encounter CPU performance bottlenecks where all traffic flows through a single root site, limiting throughput to what one CPU core can handle. + +The **promote_to_root** feature solves this by promoting specific sites to root-level nodes, distributing traffic shaping across multiple CPU cores. + +**Configuration:** +1. Navigate to Integration → Common in the WebUI +2. In the "Promote to Root Nodes" field, enter one site name per line: +``` +Remote_Site_Alpha +Remote_Site_Beta +Datacenter_West +``` + +**Benefits:** +- Eliminates single-CPU bottleneck for networks with remote sites +- Distributes traffic shaping across multiple CPU cores +- Improves overall network performance for large topologies +- Works with both Splynx and UISP integrations + +**When to Use:** +- Networks with multiple high-capacity remote sites +- When using `full` topology strategy and experiencing CPU limitations +- Large networks where root site traffic exceeds single-core capacity + +### Splynx API Access + +The Splynx Integration uses Basic authentication. For using this type of authentication, please make sure you enable [Unsecure access](https://splynx.docs.apiary.io/#introduction/authentication) in your Splynx API key settings. Also the Splynx API key should be granted access to the necessary permissions. + +| Category | Name | Permission | +|----------------|------------------------------|------------| +| Tariff Plans | Internet | View | +| FUP | Compiler | View | +| FUP | Policies | View | +| FUP | Capped Data | View | +| FUP | CAP Tariff | View | +| FUP | FUP Limits | View | +| Customers | Customer | View | +| Customers | Customers Online | View | +| Customers | Customer Internet services | View | +| Networking | Routers | View | +| Networking | Router contention | View | +| Networking | MikroTik | View | +| Networking | Monitoring | View | +| Networking | Network Sites | View | +| Networking | IPv4 Networks | View | +| Networking | IPv4 Networks IP | View | +| Networking | CPE | View | +| Networking | CPE AP | View | +| Networking | IPv6 Networks | View | +| Networking | IPv6 Networks IP (Addresses) | View | +| Administration | Locations | View | + +To test the Splynx Integration, use + +```shell +python3 integrationSplynx.py +``` + +On the first successful run, it will create a ShapedDevices.csv file and network.json. +ShapedDevices.csv will be overwritten every time the Splynx integration is run. + +To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. +Edit the file to set the value of `always_overwrite_network_json` to `true`. +Then, run `sudo systemctl restart lqosd`. + +You have the option to run integrationSplynx.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_splynx = true``` under the ```[splynx_integration]``` section in `/etc/lqos.conf`. +Once set, run `sudo systemctl restart lqos_scheduler`. + +### Splynx Overrides + +You can also modify the the file `integrationSplynxBandwidths.csv` to override the default bandwidths for each Node (Site, AP). + +A template is available in the `/opt/libreqos/src` folder. To utilize the template, copy the file `integrationSplynxBandwidths.template.csv` (removing the `.template` part of the filename) and set the appropriate information inside each file. For example, if you want to change the set bandwidth for a site, you would do: +``` +sudo cp /opt/libreqos/src/integrationSplynxBandwidths.template.csv /opt/libreqos/src/integrationSplynxBandwidths.csv +``` +And edit the CSV using LibreOffice or your preferred CSV editor. + +## Netzur Integration + +Netzur deployments expose subscriber and zone inventories via a REST endpoint secured with a Bearer token. Configure `/etc/lqos.conf` as follows: + +```ini +[netzur_integration] +enable_netzur = true +api_key = "your-netzur-token" +api_url = "https://netzur.example.com/api/libreqos" +timeout_secs = 60 +use_mikrotik_ipv6 = false +``` + +- `enable_netzur` toggles automatic imports by `lqos_scheduler`. +- `api_key` is the Bearer token generated inside Netzur. +- `api_url` must return JSON containing `zones` (mapped to sites) and `customers` (mapped to client circuits and devices). +- `timeout_secs` overrides the default HTTP timeout (60 seconds) when the API is slow. +- `use_mikrotik_ipv6` enriches subscriber devices with IPv6 prefixes discovered via `mikrotikDHCPRouterList.csv`. + +Run a manual import with: + +```bash +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`. + +### Topology Strategies + +LibreQoS supports multiple topology strategies for UISP integration to balance CPU performance with network hierarchy needs: + +| Strategy | Description | CPU Impact | Use Case | +|----------|-------------|------------|----------| +| `flat` | Only shapes subscribers by service plan speed | Lowest | Maximum performance, simple subscriber-only shaping | +| `ap_only` | Shapes by service plan and Access Point | Low | Good balance of performance and AP-level control | +| `ap_site` | Shapes by service plan, Access Point, and Site | Medium | Site-level aggregation with moderate complexity | +| `full` | Shapes entire network including backhauls, Sites, APs, and clients | Highest | **Recommended for most deployments**. Complete network hierarchy with backhaul awareness | + +**Choosing the Right Strategy:** +- Use `full` for most deployments to get complete network topology awareness including backhaul links +- Use `ap_site` if you need site-level control but don't need backhaul shaping +- Use `ap_only` for better performance when site aggregation isn't needed +- Use `flat` only when maximum performance is critical and you don't need any hierarchy + +**Performance Note:** When using `full` strategy with large networks, consider using the **promote_to_root** feature (see [Promote to Root Nodes](#promote-to-root-nodes-performance-optimization) above) to distribute CPU load across multiple cores. + +### Suspension Handling Strategies + +Configure how LibreQoS handles suspended customer accounts: + +| Strategy | Description | Use Case | +|----------|-------------|----------| +| `none` | Do not handle suspensions | When suspension handling is managed elsewhere | +| `ignore` | Do not add suspended customers to network map | Reduces queue count and improves performance for networks with many suspended accounts | +| `slow` | Limit suspended customers to 0.1 Mbps | Maintains minimal connectivity for suspended accounts (e.g., payment portals) | + +**Choosing a Suspension Strategy:** +- Use `none` if your edge router or another system handles suspensions +- Use `ignore` to reduce system load by not creating queues for suspended customers +- Use `slow` to maintain minimal connectivity (useful for payment portals or service messages) + +### Burst + +- In UISP, Download Speed and Upload Speed are configured in Mbps (for example, 100 Mbps). +- In UISP, Download Burst and Upload Burst are configured in kilobytes per second (kB/s). +- Conversion and shaping: + - burst_mbps = kB/s × 8 / 1000 + - Download Min = Download Speed (Mbps) × commit_bandwidth_multiplier + - Download Max = (Download Speed (Mbps) + burst_mbps) × bandwidth_overhead_factor + - Upload Min/Max are computed the same way from Upload Speed (Mbps) and Upload Burst (kB/s) +- Example: + - UISP values: Download Speed = 100 Mbps, Download Burst = 12,500 kB/s + - Burst adds 12,500 × 8 / 1000 = 100 Mbps + - Download Min = 100 × commit_bandwidth_multiplier + - Download Max = (100 + 100) × bandwidth_overhead_factor +- Quick reference (burst kB/s → added Mbps): + - 6,250 kB/s → +50 Mbps + - 12,500 kB/s → +100 Mbps + - 25,000 kB/s → +200 Mbps +- Notes: + - Leave burst empty/null in UISP to disable burst. + - If suspended_strategy is set to slow, both Min and Max are set to 0.1 Mbps. + +### Configuration Example + +```ini +[uisp_integration] +# Core Settings +enable_uisp = true +token = "your-api-token-here" +url = "https://uisp.your_domain.com" +site = "Root_Site_Name" # Root site for topology perspective + +# Topology Strategy (see table above) +strategy = "full" # Recommended for most deployments + +# Suspension Handling (see table above) +suspended_strategy = "none" + +# Capacity Adjustments +# UISP's reported AP capacities can be optimistic +airmax_capacity = 0.65 # Use 65% of reported AirMax capacity +ltu_capacity = 0.95 # Use 95% of reported LTU capacity + +# Site Management +exclude_sites = [] # Sites to exclude, e.g., ["Test_Site", "Lab_Site"] +use_ptmp_as_parent = true # For sites branched off PtMP Access Points + +# Bandwidth Adjustments +bandwidth_overhead_factor = 1.15 # Give customers 15% above plan speed +commit_bandwidth_multiplier = 0.98 # Set minimum to 98% of maximum (CIR) + +# Advanced Options +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 WebUI (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 +cd /opt/libreqos/src +sudo /opt/libreqos/src/bin/uisp_integration +``` + +On the first successful run, it will create a network.json and ShapedDevices.csv file. +If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```. + +ShapedDevices.csv will be overwritten every time the UISP integration is run. + +To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. +Edit the file to set the value of `always_overwrite_network_json` to `true`. +Then, run `sudo systemctl restart lqosd`. + +You have the option to run integrationUISP.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_uisp = true``` in `/etc/lqos.conf`. Once set, run `sudo systemctl restart lqos_scheduler`. + +### UISP Overrides + +You can also modify the the following files to more accurately reflect your network: +- integrationUISPbandwidths.csv +- integrationUISProutes.csv + +Each of the files above have templates available in the `/opt/libreqos/src` folder. If you don't find them there, you can navigate [here](https://github.com/LibreQoE/LibreQoS/tree/develop/src). To utilize the template, copy the file (removing the `.template` part of the filename) and set the appropriate information inside each file. +For example, if you want to change the set bandwidth for a site, you would do: +``` +sudo cp /opt/libreqos/src/integrationUISPbandwidths.template.csv /opt/libreqos/src/integrationUISPbandwidths.csv +``` +And edit the CSV using LibreOffice or your preferred CSV editor. + +#### UISP Route Overrides + +The default cost between nodes is typically 10. The integration creates a dot graph file `/opt/libreqos/src/graph.dot` which can be rendered using [Graphviz](https://dreampuf.github.io/GraphvizOnline/). This renders a map with the associated costs of all links. + +![image](https://github.com/user-attachments/assets/4edba4b5-c377-4659-8798-dfc40d50c859) + +Say you have Site 1, Site 2, and Site 3. +A backup path exists between Site 1 and Site 3, but is not the preferred path. +Your preference is Site 1 > Site 2 > Site 3, but the integration by default connects Site 1 > Site 3 directly. + +To fix this, add a cost above the default for the path between Site 1 and Site 3. +``` +Site 1, Site 3, 100 +Site 3, Site 1, 100 +``` +With this, data will flow Site 1 > Site 2 > Site 3. + +To make the change, perform a reload of the integration with ```sudo systemctl restart lqos_scheduler```. + +## WISPGate Integration + +First, set the relevant parameters for WISPGate in `/etc/lqos.conf`. +There should be a section as follows: + +``` +[wispgate_integration] +enable_wispgate = false +wispgate_api_token = "token" +wispgate_api_url = "https://your_wispgate_url.com" +``` + +If the section is missing, you can add it by copying the section above. +Set the appropriate values for wispgate_api_token and wispgate_api_url, then save the file. + +To test the WISPGate Integration, use + +```shell +python3 integrationWISPGate.py +``` + +On the first successful run, it will create a ShapedDevices.csv file and network.json. +ShapedDevices.csv will be overwritten every time the WISPGate integration is run. + +To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. +Edit the file to set the value of `always_overwrite_network_json` to `true`. +Then, run `sudo systemctl restart lqosd`. + +You have the option to run integrationWISPGate.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_wispgate = true``` in `/etc/lqos.conf`. +Once set, run `sudo systemctl restart lqos_scheduler`. + +## Powercode Integration + +First, set the relevant parameters for Powercode (powercode_api_key, powercode_api_url, etc.) in `/etc/lqos.conf`. + +To test the Powercode Integration, use + +```shell +python3 integrationPowercode.py +``` + +On the first successful run, it will create a ShapedDevices.csv file. +You can modify the network.json file manually to reflect Site/AP bandwidth limits. +ShapedDevices.csv will be overwritten every time the Powercode integration is run. +You have the option to run integrationPowercode.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_powercode = true``` in `/etc/lqos.conf`. + +## Sonar Integration + +First, set the relevant parameters for Sonar (sonar_api_key, sonar_api_url, etc.) in `/etc/lqos.conf`. + +To test the Sonar Integration, use + +```shell +python3 integrationSonar.py +``` + +On the first successful run, it will create a ShapedDevices.csv file. +If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```. +You can modify the network.json file to more accurately reflect bandwidth limits. +ShapedDevices.csv will be overwritten every time the Sonar integration is run. +You have the option to run integrationSonar.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_sonar = true``` in `/etc/lqos.conf`. + +## Third-Party Tools + +### Jesync UI Tool Dashboard +Jesync UI Tool Dashboard is a modern, web-based control panel designed to make managing LibreQoS and its integration files easier, faster, and more user-friendly. + +[https://github.com/jesienazareth/jesync_dashboard](https://github.com/jesienazareth/jesync_dashboard) + +### MikroTik PPPoE Integration +This script automates the synchronization of MikroTik PPP secrets (e.g., PPPoE users) and active hotspot users with a LibreQoS-compatible CSV file (ShapedDevices.csv). It continuously monitors the MikroTik router for changes to PPP secrets and active hotspot users, such as additions, updates, or deletions, and updates the CSV file accordingly. The script also calculates rate limits (download/upload speeds) based on the assigned PPP profile and ensures the CSV file is always up-to-date. + +The script is designed to run as a background service using systemd, ensuring it starts automatically on boot and restarts in case of failures. + +[https://github.com/Kintoyyy/MikroTik-LibreQos-Integration](https://github.com/Kintoyyy/MikroTik-LibreQos-Integration) diff --git a/docs/v2.0/integrations-sonar.md b/docs/v2.0/integrations-sonar.md new file mode 100644 index 00000000..8ab4edd8 --- /dev/null +++ b/docs/v2.0/integrations-sonar.md @@ -0,0 +1,21 @@ +# Sonar Integration + +## Summary + +Use this when Sonar is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure Sonar integration settings in `/etc/lqos.conf`. +2. Run a manual import test. +3. Enable scheduler-driven sync. + +## Operational Notes + +- `ShapedDevices.csv` is regenerated on sync. +- `network.json` behavior depends on overwrite settings. + +## Full Reference + +- [Detailed Sonar Reference](integrations-reference.md#sonar-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-splynx.md b/docs/v2.0/integrations-splynx.md new file mode 100644 index 00000000..ec1aeae9 --- /dev/null +++ b/docs/v2.0/integrations-splynx.md @@ -0,0 +1,22 @@ +# Splynx Integration + +## Summary + +Use this when Splynx is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure Splynx settings in `/etc/lqos.conf`. +2. Select topology strategy (`flat`, `ap_only`, `ap_site`, `full`). +3. Enable automatic sync and restart scheduler. + +## Operational Notes + +- `ShapedDevices.csv` is regenerated each sync. +- `network.json` overwrite depends on `always_overwrite_network_json`. +- Use WebUI Integration settings for day-to-day adjustments. + +## Full Reference + +- [Detailed Splynx Reference](integrations-reference.md#splynx-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-uisp.md b/docs/v2.0/integrations-uisp.md new file mode 100644 index 00000000..ed49fb5b --- /dev/null +++ b/docs/v2.0/integrations-uisp.md @@ -0,0 +1,22 @@ +# UISP Integration + +## Summary + +Use this when UISP is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure UISP settings in `/etc/lqos.conf`. +2. Choose topology strategy and suspension handling strategy. +3. Enable automatic sync and restart scheduler. + +## Operational Notes + +- `ShapedDevices.csv` is regenerated each sync. +- `network.json` overwrite depends on `always_overwrite_network_json`. +- Use WebUI for operational changes; treat file edits as temporary in integration mode. + +## Full Reference + +- [Detailed UISP Reference](integrations-reference.md#uisp-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-visp.md b/docs/v2.0/integrations-visp.md new file mode 100644 index 00000000..b3feadea --- /dev/null +++ b/docs/v2.0/integrations-visp.md @@ -0,0 +1,21 @@ +# VISP Integration + +## Summary + +Use this when VISP is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure `[visp_integration]` credentials in `/etc/lqos.conf`. +2. Run a manual import test. +3. Enable scheduler-driven sync. + +## Operational Notes + +- `ShapedDevices.csv` is rewritten each run. +- `network.json` is overwritten only when enabled in integration common settings. + +## Full Reference + +- [Detailed VISP Reference](integrations-reference.md#visp-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations-wispgate.md b/docs/v2.0/integrations-wispgate.md new file mode 100644 index 00000000..c8883b3c --- /dev/null +++ b/docs/v2.0/integrations-wispgate.md @@ -0,0 +1,21 @@ +# WISPGate Integration + +## Summary + +Use this when WISPGate is your CRM/NMS source of truth. + +## Basic Setup + +1. Configure WISPGate integration settings in `/etc/lqos.conf`. +2. Run a manual import test. +3. Enable scheduler-driven sync. + +## Operational Notes + +- `ShapedDevices.csv` is regenerated on sync. +- `network.json` behavior depends on your overwrite settings. + +## Full Reference + +- [Detailed WISPGate Reference](integrations-reference.md#wispgate-integration) +- [Operating Modes and Source of Truth](operating-modes.md) diff --git a/docs/v2.0/integrations.md b/docs/v2.0/integrations.md index 65a09660..cc066229 100644 --- a/docs/v2.0/integrations.md +++ b/docs/v2.0/integrations.md @@ -1,442 +1,47 @@ # CRM/NMS Integrations - * [Splynx Integration](#splynx-integration) - + [Topology Strategies](#topology-strategies) - + [Promote to Root Nodes (Performance Optimization)](#promote-to-root-nodes-performance-optimization) - + [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) - + [Burst](#burst) - + [Configuration Example](#configuration-example) - + [UISP Overrides](#uisp-overrides) - - [UISP Route Overrides](#uisp-route-overrides) - * [WISPGate Integration](#wispgate-integration) - * [Powercode Integration](#powercode-integration) - * [Sonar Integration](#sonar-integration) +Most operators use built-in integrations. If you use your own scripts as the source of truth for `network.json` and `ShapedDevices.csv`, start with [Operating Modes and Source of Truth](operating-modes.md). -## What these integrations do +## Choose Your Integration Path -These integrations work by synchronizing with your CRM/NMS system to produce the two files LibreQoS requires for shaping - [network.json](configuration.md#network-hierarchy) and [ShapedDevices.csv](configuration.md#circuits). +| Path | Best fit | Primary source of truth | +|---|---|---| +| Built-in integration | Most operators using supported systems | CRM/NMS via LibreQoS integration jobs | +| Custom source-of-truth | Operators with in-house CRM/NMS sync logic | External generated files (`network.json`, `ShapedDevices.csv`) | -## Splynx Integration +## Where in WebUI -> **⚠️ Breaking Change Notice**: Prior to v1.5-RC-2, the default Splynx strategy was `full`. Starting with v1.5-RC-2, the default strategy is `ap_only` for improved CPU performance. If you require the previous behavior, explicitly set `strategy = "full"` in your Splynx configuration section. +- Integration defaults/common behavior: `Configuration -> Integrations` +- Per-integration configuration fields: `Configuration -> Integrations` +- Operational health checks after sync changes: `WebUI -> Scheduler Status` and `WebUI -> Urgent Issues` +- Topology/result validation: `WebUI -> Network Tree Overview` and `Flow Map` -First, set the relevant parameters for Splynx (splynx_api_key, splynx_api_secret, etc.) in `/etc/lqos.conf`. +## Built-In Integrations -### Topology Strategies +- [Splynx Integration](integrations-splynx.md) +- [UISP Integration](integrations-uisp.md) +- [Netzur Integration](integrations-netzur.md) +- [VISP Integration](integrations-visp.md) +- [WISPGate Integration](integrations-wispgate.md) +- [Powercode Integration](integrations-powercode.md) +- [Sonar Integration](integrations-sonar.md) -LibreQoS supports multiple topology strategies for Splynx integration to balance CPU performance with network hierarchy needs: +## Important Overwrite Behavior -| Strategy | Description | CPU Impact | Use Case | -|----------|-------------|------------|----------| -| `flat` | Only shapes subscribers, no hierarchy | Lowest | Maximum performance, simple subscriber-only shaping | -| `ap_only` | Single layer: AP → Clients | Low | **Default**. Best balance of performance and structure | -| `ap_site` | Two layers: Site → AP → Clients | Medium | Site-level aggregation with moderate complexity | -| `full` | Complete topology mapping | Highest | Full network hierarchy representation | +When integrations are enabled: +- `ShapedDevices.csv` is typically regenerated by integration sync jobs. +- `network.json` may also be overwritten depending on integration settings (for example `always_overwrite_network_json`). +- Manual edits may be overwritten on the next refresh cycle. -Configure the strategy in `/etc/lqos.conf` under the `[splynx_integration]` section: +## Need Full Legacy Reference? -```ini -[splynx_integration] -# ... other splynx settings ... -strategy = "ap_only" -``` +Detailed legacy integration content is preserved here: +- [Integration Reference (Detailed)](integrations-reference.md) -**Performance Considerations:** -- `flat` and `ap_only` strategies significantly reduce CPU load by limiting network depth -- Choose `ap_only` for most deployments unless you need site-level traffic aggregation -- Only use `full` if you require complete network topology representation and have adequate CPU resources +## Related Pages -### Promote to Root Nodes (Performance Optimization) - -When using `full` topology strategy, you may encounter CPU performance bottlenecks where all traffic flows through a single root site, limiting throughput to what one CPU core can handle. - -The **promote_to_root** feature solves this by promoting specific sites to root-level nodes, distributing traffic shaping across multiple CPU cores. - -**Configuration:** -1. Navigate to Integration → Common in the WebUI -2. In the "Promote to Root Nodes" field, enter one site name per line: -``` -Remote_Site_Alpha -Remote_Site_Beta -Datacenter_West -``` - -**Benefits:** -- Eliminates single-CPU bottleneck for networks with remote sites -- Distributes traffic shaping across multiple CPU cores -- Improves overall network performance for large topologies -- Works with both Splynx and UISP integrations - -**When to Use:** -- Networks with multiple high-capacity remote sites -- When using `full` topology strategy and experiencing CPU limitations -- Large networks where root site traffic exceeds single-core capacity - -### Splynx API Access - -The Splynx Integration uses Basic authentication. For using this type of authentication, please make sure you enable [Unsecure access](https://splynx.docs.apiary.io/#introduction/authentication) in your Splynx API key settings. Also the Splynx API key should be granted access to the necessary permissions. - -| Category | Name | Permission | -|----------------|------------------------------|------------| -| Tariff Plans | Internet | View | -| FUP | Compiler | View | -| FUP | Policies | View | -| FUP | Capped Data | View | -| FUP | CAP Tariff | View | -| FUP | FUP Limits | View | -| Customers | Customer | View | -| Customers | Customers Online | View | -| Customers | Customer Internet services | View | -| Networking | Routers | View | -| Networking | Router contention | View | -| Networking | MikroTik | View | -| Networking | Monitoring | View | -| Networking | Network Sites | View | -| Networking | IPv4 Networks | View | -| Networking | IPv4 Networks IP | View | -| Networking | CPE | View | -| Networking | CPE AP | View | -| Networking | IPv6 Networks | View | -| Networking | IPv6 Networks IP (Addresses) | View | -| Administration | Locations | View | - -To test the Splynx Integration, use - -```shell -python3 integrationSplynx.py -``` - -On the first successful run, it will create a ShapedDevices.csv file and network.json. -ShapedDevices.csv will be overwritten every time the Splynx integration is run. - -To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. -Edit the file to set the value of `always_overwrite_network_json` to `true`. -Then, run `sudo systemctl restart lqosd`. - -You have the option to run integrationSplynx.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_splynx = true``` under the ```[splynx_integration]``` section in `/etc/lqos.conf`. -Once set, run `sudo systemctl restart lqos_scheduler`. - -### Splynx Overrides - -You can also modify the the file `integrationSplynxBandwidths.csv` to override the default bandwidths for each Node (Site, AP). - -A template is available in the `/opt/libreqos/src` folder. To utilize the template, copy the file `integrationSplynxBandwidths.template.csv` (removing the `.template` part of the filename) and set the appropriate information inside each file. For example, if you want to change the set bandwidth for a site, you would do: -``` -sudo cp /opt/libreqos/src/integrationSplynxBandwidths.template.csv /opt/libreqos/src/integrationSplynxBandwidths.csv -``` -And edit the CSV using LibreOffice or your preferred CSV editor. - -## Netzur Integration - -Netzur deployments expose subscriber and zone inventories via a REST endpoint secured with a Bearer token. Configure `/etc/lqos.conf` as follows: - -```ini -[netzur_integration] -enable_netzur = true -api_key = "your-netzur-token" -api_url = "https://netzur.example.com/api/libreqos" -timeout_secs = 60 -use_mikrotik_ipv6 = false -``` - -- `enable_netzur` toggles automatic imports by `lqos_scheduler`. -- `api_key` is the Bearer token generated inside Netzur. -- `api_url` must return JSON containing `zones` (mapped to sites) and `customers` (mapped to client circuits and devices). -- `timeout_secs` overrides the default HTTP timeout (60 seconds) when the API is slow. -- `use_mikrotik_ipv6` enriches subscriber devices with IPv6 prefixes discovered via `mikrotikDHCPRouterList.csv`. - -Run a manual import with: - -```bash -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`. - -### Topology Strategies - -LibreQoS supports multiple topology strategies for UISP integration to balance CPU performance with network hierarchy needs: - -| Strategy | Description | CPU Impact | Use Case | -|----------|-------------|------------|----------| -| `flat` | Only shapes subscribers by service plan speed | Lowest | Maximum performance, simple subscriber-only shaping | -| `ap_only` | Shapes by service plan and Access Point | Low | Good balance of performance and AP-level control | -| `ap_site` | Shapes by service plan, Access Point, and Site | Medium | Site-level aggregation with moderate complexity | -| `full` | Shapes entire network including backhauls, Sites, APs, and clients | Highest | **Recommended for most deployments**. Complete network hierarchy with backhaul awareness | - -**Choosing the Right Strategy:** -- Use `full` for most deployments to get complete network topology awareness including backhaul links -- Use `ap_site` if you need site-level control but don't need backhaul shaping -- Use `ap_only` for better performance when site aggregation isn't needed -- Use `flat` only when maximum performance is critical and you don't need any hierarchy - -**Performance Note:** When using `full` strategy with large networks, consider using the **promote_to_root** feature (see [Promote to Root Nodes](#promote-to-root-nodes-performance-optimization) above) to distribute CPU load across multiple cores. - -### Suspension Handling Strategies - -Configure how LibreQoS handles suspended customer accounts: - -| Strategy | Description | Use Case | -|----------|-------------|----------| -| `none` | Do not handle suspensions | When suspension handling is managed elsewhere | -| `ignore` | Do not add suspended customers to network map | Reduces queue count and improves performance for networks with many suspended accounts | -| `slow` | Limit suspended customers to 0.1 Mbps | Maintains minimal connectivity for suspended accounts (e.g., payment portals) | - -**Choosing a Suspension Strategy:** -- Use `none` if your edge router or another system handles suspensions -- Use `ignore` to reduce system load by not creating queues for suspended customers -- Use `slow` to maintain minimal connectivity (useful for payment portals or service messages) - -### Burst - -- In UISP, Download Speed and Upload Speed are configured in Mbps (for example, 100 Mbps). -- In UISP, Download Burst and Upload Burst are configured in kilobytes per second (kB/s). -- Conversion and shaping: - - burst_mbps = kB/s × 8 / 1000 - - Download Min = Download Speed (Mbps) × commit_bandwidth_multiplier - - Download Max = (Download Speed (Mbps) + burst_mbps) × bandwidth_overhead_factor - - Upload Min/Max are computed the same way from Upload Speed (Mbps) and Upload Burst (kB/s) -- Example: - - UISP values: Download Speed = 100 Mbps, Download Burst = 12,500 kB/s - - Burst adds 12,500 × 8 / 1000 = 100 Mbps - - Download Min = 100 × commit_bandwidth_multiplier - - Download Max = (100 + 100) × bandwidth_overhead_factor -- Quick reference (burst kB/s → added Mbps): - - 6,250 kB/s → +50 Mbps - - 12,500 kB/s → +100 Mbps - - 25,000 kB/s → +200 Mbps -- Notes: - - Leave burst empty/null in UISP to disable burst. - - If suspended_strategy is set to slow, both Min and Max are set to 0.1 Mbps. - -### Configuration Example - -```ini -[uisp_integration] -# Core Settings -enable_uisp = true -token = "your-api-token-here" -url = "https://uisp.your_domain.com" -site = "Root_Site_Name" # Root site for topology perspective - -# Topology Strategy (see table above) -strategy = "full" # Recommended for most deployments - -# Suspension Handling (see table above) -suspended_strategy = "none" - -# Capacity Adjustments -# UISP's reported AP capacities can be optimistic -airmax_capacity = 0.65 # Use 65% of reported AirMax capacity -ltu_capacity = 0.95 # Use 95% of reported LTU capacity - -# Site Management -exclude_sites = [] # Sites to exclude, e.g., ["Test_Site", "Lab_Site"] -use_ptmp_as_parent = true # For sites branched off PtMP Access Points - -# Bandwidth Adjustments -bandwidth_overhead_factor = 1.15 # Give customers 15% above plan speed -commit_bandwidth_multiplier = 0.98 # Set minimum to 98% of maximum (CIR) - -# Advanced Options -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 -cd /opt/libreqos/src -sudo /opt/libreqos/src/bin/uisp_integration -``` - -On the first successful run, it will create a network.json and ShapedDevices.csv file. -If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```. - -ShapedDevices.csv will be overwritten every time the UISP integration is run. - -To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. -Edit the file to set the value of `always_overwrite_network_json` to `true`. -Then, run `sudo systemctl restart lqosd`. - -You have the option to run integrationUISP.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_uisp = true``` in `/etc/lqos.conf`. Once set, run `sudo systemctl restart lqos_scheduler`. - -### UISP Overrides - -You can also modify the the following files to more accurately reflect your network: -- integrationUISPbandwidths.csv -- integrationUISProutes.csv - -Each of the files above have templates available in the `/opt/libreqos/src` folder. If you don't find them there, you can navigate [here](https://github.com/LibreQoE/LibreQoS/tree/develop/src). To utilize the template, copy the file (removing the `.template` part of the filename) and set the appropriate information inside each file. -For example, if you want to change the set bandwidth for a site, you would do: -``` -sudo cp /opt/libreqos/src/integrationUISPbandwidths.template.csv /opt/libreqos/src/integrationUISPbandwidths.csv -``` -And edit the CSV using LibreOffice or your preferred CSV editor. - -#### UISP Route Overrides - -The default cost between nodes is typically 10. The integration creates a dot graph file `/opt/libreqos/src/graph.dot` which can be rendered using [Graphviz](https://dreampuf.github.io/GraphvizOnline/). This renders a map with the associated costs of all links. - -![image](https://github.com/user-attachments/assets/4edba4b5-c377-4659-8798-dfc40d50c859) - -Say you have Site 1, Site 2, and Site 3. -A backup path exists between Site 1 and Site 3, but is not the preferred path. -Your preference is Site 1 > Site 2 > Site 3, but the integration by default connects Site 1 > Site 3 directly. - -To fix this, add a cost above the default for the path between Site 1 and Site 3. -``` -Site 1, Site 3, 100 -Site 3, Site 1, 100 -``` -With this, data will flow Site 1 > Site 2 > Site 3. - -To make the change, perform a reload of the integration with ```sudo systemctl restart lqos_scheduler```. - -## WISPGate Integration - -First, set the relevant parameters for WISPGate in `/etc/lqos.conf`. -There should be a section as follows: - -``` -[wispgate_integration] -enable_wispgate = false -wispgate_api_token = "token" -wispgate_api_url = "https://your_wispgate_url.com" -``` - -If the section is missing, you can add it by copying the section above. -Set the appropriate values for wispgate_api_token and wispgate_api_url, then save the file. - -To test the WISPGate Integration, use - -```shell -python3 integrationWISPGate.py -``` - -On the first successful run, it will create a ShapedDevices.csv file and network.json. -ShapedDevices.csv will be overwritten every time the WISPGate integration is run. - -To ensure the network.json is always overwritten with the newest version pulled in by the integration, please edit `/etc/lqos.conf` with the command `sudo nano /etc/lqos.conf`. -Edit the file to set the value of `always_overwrite_network_json` to `true`. -Then, run `sudo systemctl restart lqosd`. - -You have the option to run integrationWISPGate.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_wispgate = true``` in `/etc/lqos.conf`. -Once set, run `sudo systemctl restart lqos_scheduler`. - -## Powercode Integration - -First, set the relevant parameters for Powercode (powercode_api_key, powercode_api_url, etc.) in `/etc/lqos.conf`. - -To test the Powercode Integration, use - -```shell -python3 integrationPowercode.py -``` - -On the first successful run, it will create a ShapedDevices.csv file. -You can modify the network.json file manually to reflect Site/AP bandwidth limits. -ShapedDevices.csv will be overwritten every time the Powercode integration is run. -You have the option to run integrationPowercode.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_powercode = true``` in `/etc/lqos.conf`. - -## Sonar Integration - -First, set the relevant parameters for Sonar (sonar_api_key, sonar_api_url, etc.) in `/etc/lqos.conf`. - -To test the Sonar Integration, use - -```shell -python3 integrationSonar.py -``` - -On the first successful run, it will create a ShapedDevices.csv file. -If a network.json file exists, it will not be overwritten, unless you set ```always_overwrite_network_json = true```. -You can modify the network.json file to more accurately reflect bandwidth limits. -ShapedDevices.csv will be overwritten every time the Sonar integration is run. -You have the option to run integrationSonar.py automatically on boot and every X minutes (set by the parameter `queue_refresh_interval_mins`), which is highly recommended. This can be enabled by setting ```enable_sonar = true``` in `/etc/lqos.conf`. - -## Third-Party Tools - -### Jesync UI Tool Dashboard -Jesync UI Tool Dashboard is a modern, web-based control panel designed to make managing LibreQoS and its integration files easier, faster, and more user-friendly. - -[https://github.com/jesienazareth/jesync_dashboard](https://github.com/jesienazareth/jesync_dashboard) - -### MikroTik PPPoE Integration -This script automates the synchronization of MikroTik PPP secrets (e.g., PPPoE users) and active hotspot users with a LibreQoS-compatible CSV file (ShapedDevices.csv). It continuously monitors the MikroTik router for changes to PPP secrets and active hotspot users, such as additions, updates, or deletions, and updates the CSV file accordingly. The script also calculates rate limits (download/upload speeds) based on the assigned PPP profile and ensures the CSV file is always up-to-date. - -The script is designed to run as a background service using systemd, ensuring it starts automatically on boot and restarts in case of failures. - -[https://github.com/Kintoyyy/MikroTik-LibreQos-Integration](https://github.com/Kintoyyy/MikroTik-LibreQos-Integration) +- [Quickstart](quickstart.md) +- [Operating Modes and Source of Truth](operating-modes.md) +- [Configure LibreQoS](configuration.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/node-manager-ui.md b/docs/v2.0/node-manager-ui.md index ff6d6edd..6e78ea89 100644 --- a/docs/v2.0/node-manager-ui.md +++ b/docs/v2.0/node-manager-ui.md @@ -1,6 +1,6 @@ -# LibreQoS Node Manager UI +# LibreQoS WebUI (Node Manager) -This page documents key Node Manager views and operational behavior in the local WebUI (`http://your_shaper_ip:9123`). +This page documents key WebUI (Node Manager) views and operational behavior in the local WebUI (`http://your_shaper_ip:9123`). ## Core Views @@ -29,13 +29,13 @@ This page documents key Node Manager views and operational behavior in the local - Supports paging and filtering in current builds. ### Urgent Issues -- Node Manager can display urgent operational issues generated by backend services. +- WebUI 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. +- WebUI 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"` diff --git a/docs/v2.0/operating-modes.md b/docs/v2.0/operating-modes.md new file mode 100644 index 00000000..87de993e --- /dev/null +++ b/docs/v2.0/operating-modes.md @@ -0,0 +1,35 @@ +# Operating Modes and Source of Truth + +LibreQoS supports two first-class operating modes. + +## Built-in Integrations (Recommended for Most Operators) + +In this mode, your CRM/NMS is the source of truth and LibreQoS integration jobs produce shaping inputs. + +Key behavior: +- `ShapedDevices.csv` is regenerated by integration sync cycles. +- `network.json` overwrite behavior depends on integration settings (for example `always_overwrite_network_json`). +- Direct manual edits may be overwritten on the next scheduler refresh. + +## Custom Source-of-Truth + +In this mode, your own scripts/systems generate `network.json` and `ShapedDevices.csv`. + +Key behavior: +- Your external workflow owns persistence. +- WebUI edits are valid for quick operational changes. +- Permanent changes should be made in your external source-of-truth workflow. + +## Mode Declaration Checklist (Before Go-Live) + +1. Pick one primary source of truth. +2. Confirm which system can write production shaping inputs. +3. Confirm scheduler refresh behavior and overwrite cadence. +4. Document your hotfix workflow (WebUI, external editor, or both). +5. Do not maintain competing edits in multiple systems for the same objects. + +## Related Pages + +- [Configure LibreQoS](configuration.md) +- [CRM/NMS Integrations](integrations.md) +- [Advanced Configuration Reference](configuration-advanced.md) diff --git a/docs/v2.0/performance-tuning.md b/docs/v2.0/performance-tuning.md index b801ee83..7d676209 100644 --- a/docs/v2.0/performance-tuning.md +++ b/docs/v2.0/performance-tuning.md @@ -23,7 +23,7 @@ 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. +- Validate WebUI CPU Tree/CPU Weights after major topology changes. ## Scheduler Refresh and Load @@ -33,7 +33,7 @@ When shaping large hierarchies: - 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 + - WebUI scheduler status ## StormGuard Rollout @@ -67,3 +67,10 @@ For routed deployments, tune OSPF neighbor timers on core and edge routers to re - hello interval - dead interval + +## Related Optimization and Resilience Pages + +- [Scale Planning and Topology Design](scale-topology.md) +- [StormGuard](stormguard.md) +- [High Availability and Failure Domains](high-availability.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/quickstart.md b/docs/v2.0/quickstart.md index 13f2eb81..c9217f6f 100644 --- a/docs/v2.0/quickstart.md +++ b/docs/v2.0/quickstart.md @@ -1,21 +1,29 @@ -# Install LibreQoS +# Quickstart: Choose Your Deployment Path -## Step 1 - Validate Network Design Assumptions and Hardware Selection +LibreQoS supports multiple real-world deployment paths. Start by selecting one path and keep a single source-of-truth model for shaping data. -- [Network Design Assumptions](design.md) -- [System Requirements](requirements.md) +## Before You Start -## Step 2 - Complete The Installation Prerequisites +- WebUI is the primary operational interface after install. +- Pick one source-of-truth model for `network.json` and `ShapedDevices.csv`. +- Avoid competing edits across multiple systems for the same objects. -- [Server Setup - Prerequisites](prereq.md) -- [Install Ubuntu Server 24.04](ubuntu-server.md) -- [Configure Shaping Bridge](bridge.md) +## Testbed / Lab -## Step 3 - Install LibreQoS v1.5 / Upgrade to LibreQoS v1.5 +Use this path when you want to validate LibreQoS behavior in a controlled environment before inline production deployment. -### Use .DEB Package (Recommended Method) +### Lab setup flow -``` +1. Build a lab topology (LibreQoS box + traffic generator endpoints + optional routers for OSPF/BGP path simulation). +2. Complete platform and install prerequisites: + - [Deployment Scenarios](design.md) + - [System Requirements](requirements.md) + - [Server Setup - Prerequisites](prereq.md) + - [Install Ubuntu Server 24.04](ubuntu-server.md) + - [Configure Shaping Bridge](bridge.md) +3. Install LibreQoS using `.deb` package (recommended): + +```bash cd ~ sudo apt-get update sudo apt-get upgrade @@ -23,10 +31,87 @@ wget https://download.libreqos.com/{deb_url_v1_5} sudo apt install ./{deb_url_v1_5} ``` -### Git Install (For Developers Only - Not Recommended) +4. Choose one test track: + - **Lab with manual files**: use sample/manual `network.json` and `ShapedDevices.csv`. + - **Lab with supported integration**: configure integration and validate pulled data. +5. Generate test traffic and validate in WebUI: + - Dashboard/Tree/Flow behavior + - Scheduler status + - Urgent issues +6. When behavior is as expected, move to an inline pilot path. -[Complex Installation](git-install.md) +### After this path -## Step 4 - Configure LibreQoS +- [Configure LibreQoS](configuration.md) +- [Operating Modes and Source of Truth](operating-modes.md) +- [CRM/NMS Integrations](integrations.md) +- [Troubleshooting](troubleshooting.md) -You are now ready to [Configure](configuration.md) LibreQoS! +## Supported Integration + +Use this path when your CRM/NMS is supported by built-in LibreQoS integrations. + +1. Complete install prerequisites and install LibreQoS (same links/steps as above). +2. Configure integration in WebUI. +3. Validate imported shaping data and topology in WebUI. +4. Place the LibreQoS box inline for pilot traffic. +5. Monitor scheduler health, shaping behavior, and urgent issues in WebUI. +6. Expand from pilot to broader deployment after stable observations. + +Note: +- In integration mode, `ShapedDevices.csv` is typically regenerated by sync jobs. +- `network.json` overwrite behavior depends on integration settings (for example `always_overwrite_network_json`). + +### After this path + +- [Operating Modes and Source of Truth](operating-modes.md) +- [CRM/NMS Integrations](integrations.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Troubleshooting](troubleshooting.md) + +## Custom Script Integration + +Use this path when your CRM/NMS is unsupported and you will generate `network.json` and `ShapedDevices.csv` with your own scripts. + +1. Complete install prerequisites and install LibreQoS (same links/steps as above). +2. Implement script/process to generate and refresh `network.json` and `ShapedDevices.csv`. +3. Treat script outputs as source-of-truth for long-term persistence. +4. Place the LibreQoS box inline for pilot traffic. +5. Use WebUI for operational checks and quick edits. +6. Move permanent logic/data changes back into your script pipeline. + +Note: +- WebUI edits are useful for quick operational changes. +- Long-term state should be maintained by your external source-of-truth workflow. + +### After this path + +- [Operating Modes and Source of Truth](operating-modes.md) +- [Advanced Configuration Reference](configuration-advanced.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Troubleshooting](troubleshooting.md) + +## Manual Files (<100 subscribers) + +Use this path when you intentionally maintain `network.json` and `ShapedDevices.csv` directly without CRM/NMS synchronization. + +Recommended only for networks under 100 subscribers. + +1. Complete install prerequisites and install LibreQoS (same links/steps as above). +2. Build and maintain `network.json` and `ShapedDevices.csv` directly. +3. Place the LibreQoS box inline for pilot traffic. +4. Use WebUI to validate shaping, scheduler status, and topology behavior. +5. Keep manual update discipline tight (data quality, consistency, update cadence). +6. If subscriber count or change volume grows, plan migration to supported integration or custom script integration. + +### After this path + +- [Advanced Configuration Reference](configuration-advanced.md) +- [Operating Modes and Source of Truth](operating-modes.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Troubleshooting](troubleshooting.md) + +## Developer Install (Not Recommended for Operators) + +Git-based install instructions are still available here: +- [Git Install (For Developers)](git-install.md) diff --git a/docs/v2.0/scale-topology.md b/docs/v2.0/scale-topology.md index 84e1d374..a46ae087 100644 --- a/docs/v2.0/scale-topology.md +++ b/docs/v2.0/scale-topology.md @@ -34,7 +34,7 @@ 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. +- WebUI CPU Tree shows skewed distribution not explained by demand. ## Virtual Nodes and Logical Grouping @@ -59,7 +59,7 @@ See [Troubleshooting](troubleshooting.md#urgent-issue-codes-and-first-actions) f 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: +4. Validate WebUI: - CPU Tree / CPU Weights distribution - Flow Map/ASN/Tree behavior - scheduler status and urgent issues @@ -69,5 +69,7 @@ See [Troubleshooting](troubleshooting.md#urgent-issue-codes-and-first-actions) f - [Integrations](integrations.md) - [Performance Tuning](performance-tuning.md) +- [StormGuard](stormguard.md) +- [High Availability and Failure Domains](high-availability.md) - [Configuration](configuration.md) - [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/stormguard.md b/docs/v2.0/stormguard.md index f0507bfe..bf86bfeb 100644 --- a/docs/v2.0/stormguard.md +++ b/docs/v2.0/stormguard.md @@ -6,7 +6,7 @@ StormGuard is LibreQoS' adaptive queue-adjustment subsystem for congestion and q - 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. +- Exposes status/debug data in the WebUI (Node Manager). ## Configuration @@ -37,7 +37,7 @@ If you are testing, start with `dry_run = true` so you can observe decisions bef ## UI and Debugging -- Node Manager provides StormGuard status and debug views. +- WebUI provides StormGuard status and debug views. - The StormGuard debug page shows: - current effective limits - evaluation metrics @@ -72,5 +72,8 @@ Also verify: ## Related Pages - [Configuration](configuration.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Performance Tuning](performance-tuning.md) +- [High Availability and Failure Domains](high-availability.md) - [Components](components.md) - [Troubleshooting](troubleshooting.md) diff --git a/docs/v2.0/troubleshooting.md b/docs/v2.0/troubleshooting.md index 74c35391..55f48e25 100644 --- a/docs/v2.0/troubleshooting.md +++ b/docs/v2.0/troubleshooting.md @@ -1,7 +1,28 @@ # Troubleshooting +## Start Here: Symptom Triage + +Use this table to jump to the first checks quickly. + +| Symptom | First check | WebUI location | Next section | +|---|---|---|---| +| Cannot access WebUI | `systemctl status lqosd` | N/A (UI unavailable) | No WebUI at x.x.x.x:9123 | +| Traffic is not shaping | verify `to_internet` / `to_network`, service state | WebUI Dashboard | LibreQoS Is Running, But Traffic Not Shaping | +| Scheduler appears unhealthy | check `lqosd` and `lqos_scheduler` logs | WebUI -> Scheduler Status | Scheduler status in WebUI looks unhealthy | +| Topology/flow views blank | confirm recent traffic and `lqosd` health | WebUI -> Flow Map / Tree / ASN Explorer | Flow Map / Tree Overview / ASN Explorer appears blank | +| Urgent issue code appears | open issue details and map code | WebUI -> Urgent Issues | Urgent issue codes and first actions | +| Mapped circuit cap events | validate license state and mapped counts | Insight UI + WebUI -> Urgent Issues | Mapped circuit limit reached | + ## Common Issues +### Where in WebUI + +- Service/health overview: `WebUI -> Dashboard` +- Scheduler readiness: `WebUI -> Scheduler Status` +- High-priority alerts: `WebUI -> Urgent Issues` +- Topology/traffic visualization: `WebUI -> Network Tree Overview` and `Flow Map` +- Shaped records review: `WebUI -> Shaped Devices Editor` + ### User password not working Delete the lqusers file: @@ -90,9 +111,9 @@ 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 +### Scheduler status in WebUI looks unhealthy -Recent builds expose scheduler readiness/state in the Node Manager UI. +Recent builds expose scheduler readiness/state in the WebUI (Node Manager). If scheduler status appears down/stale: 1. Verify both services: @@ -176,7 +197,7 @@ Recommended checks: ### Urgent issue codes and first actions -Node Manager urgent issues include machine-readable codes. Use them to triage quickly. +WebUI urgent issues include machine-readable codes. Use them to triage quickly. | Code | Meaning | First checks | Typical fix path | |---|---|---|---| @@ -184,7 +205,7 @@ Node Manager urgent issues include machine-readable codes. Use them to triage qu | `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). +1. Open urgent issue details in WebUI (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. @@ -220,3 +241,11 @@ Then, reboot, and confirm the systemd version with `systemctl --version` libreqos@libreqos:~$ systemctl --version systemd 257 (257.5) ``` + +## Related Pages + +- [Quickstart](quickstart.md) +- [Configure LibreQoS](configuration.md) +- [CRM/NMS Integrations](integrations.md) +- [Scale Planning and Topology Design](scale-topology.md) +- [Performance Tuning](performance-tuning.md) diff --git a/index.rst b/index.rst index bddcbde7..0dffe088 100644 --- a/index.rst +++ b/index.rst @@ -16,16 +16,18 @@ 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 :caption: Managing LibreQoS (v1.5 to v2.0): docs/v2.0/configuration + docs/v2.0/operating-modes + docs/v2.0/configuration-advanced docs/v2.0/integrations docs/v2.0/components docs/v2.0/node-manager-ui + docs/v2.0/scale-topology docs/v2.0/stormguard docs/v2.0/high-availability docs/v2.0/update