Integraciones CRM/NMS

Esta página conserva material heredado de referencia detallada. La guía canónica y orientada a tareas está en las páginas por integración enlazadas desde Integraciones CRM/NMS.

• Integración con Splynx

  • Estrategias de Topología

  • Promover Nodos a Raíz (Optimización de Rendimiento)

  • Acceso API de Splynx

  • Sobrescrituras de Splynx

• Integración con Netzur

• Integración con VISP

• Integración con UISP

  • Estrategias de Topología

  • Estrategias de Manejo de Suspensiones

  • Burst

  • Ejemplo de Configuración

  • Sobrescrituras de UISP

• Integración con WISPGate

• Integración con Powercode

• 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.

Comportamiento importante cuando hay integraciones habilitadas:

• ShapedDevices.csv normalmente se regenera por los jobs de sincronización.

• network.json sigue siendo una entrada DIY/manual operada por el usuario.

• 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 usando Splynx Network Sites cuando estén disponibles
full	Mapeo completo de la jerarquía de monitoreo	Mayor	Conserva la jerarquía más rica de monitoreo de Splynx en vez de compactarla a Network Sites

Configure la estrategia en /etc/lqos.conf bajo la sección [splynx]:

[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 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:

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.

Las integraciones incluidas no sobrescriben network.json; conserve network.json como entrada DIY/manual operada por el usuario.

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

Use las sobrescrituras de la interfaz web de LibreQoS para cambiar la velocidad configurada de un Sitio o AP.

Abra el nodo correspondiente en la vista de árbol o de topología y guarde allí el ancho de banda deseado. LibreQoS conservará esa sobrescritura del operador en futuras actualizaciones de Splynx.

No cree ni dependa de archivos heredados integrationSplynxBandwidths*.csv en implementaciones nuevas. El flujo compatible es el sistema normal de sobrescrituras desde la interfaz web.

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:

[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 /etc/libreqos/mikrotik_ipv6.toml. LibreQoS relaciona IPv4 e IPv6 por dirección MAC usando datos de ARP, DHCPv4, DHCPv6 y vecinos IPv6 de MikroTik.

Credenciales de routers MikroTik para IPv6

Cuando use_mikrotik_ipv6 o ipv6_with_mikrotik esté habilitado, cree /etc/libreqos/mikrotik_ipv6.toml. Agregue un bloque [[router]] por cada router MikroTik que LibreQoS deba consultar:

version = 1

[[router]]
name = "core-1"
host = "100.64.0.1"
port = 8728
username = "libreqos"
password = "secreto"
use_ssl = false
plaintext_login = true

[[router]]
name = "core-2"
host = "100.64.0.2"
port = 8728
username = "libreqos"
password = "secreto"
use_ssl = false
plaintext_login = true

Agregue más bloques [[router]] para más routers. port, use_ssl y plaintext_login pueden omitirse cuando los valores por defecto son correctos: puerto 8728, SSL deshabilitado y login en texto plano habilitado.

Para una importación manual:

python3 integrationNetzur.py

La integración actualiza sus artefactos propios de topología y shaping. network.json sigue siendo una entrada DIY/manual operada por el usuario.

Integración con VISP

Primero, configure los parámetros relevantes de VISP en /etc/lqos.conf:

[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.

• El importador prioriza consultas bulk rápidas y completa de forma selectiva los suscriptores/servicios que no estén cubiertos por esa ruta.

• Cuando las relaciones IRM de dispositivo upstream están pobladas en VISP, el importador también construye topología de sitio/upstream para los suscriptores importados.

• La integración reescribe ShapedDevices.csv en cada ejecución.

• network.json sigue siendo una entrada DIY/manual operada por el usuario.

• Los tokens de VISP se cachean en <lqos_directory>/.visp_token_cache_*.json.

Importación manual:

python3 integrationVISP.py

Para ejecución automática con scheduler:

• [visp_integration] enable_visp = true

• reinicie scheduler:

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	Mejor cuando topología/overrides ya están validados y estables

Cómo Elegir la Estrategia Correcta:

• Comience con ap_only en despliegues nuevos y validación inicial

• Pase a ap_site cuando necesite control por sitio sin regulación de backhaul

• Pase a full cuando la calidad de topología y overrides esté validada y exista margen de CPU

• 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 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

[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 = "ap_only"  # Punto de inicio recomendado para nuevos despliegues UISP

# 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.8  # Usar 80% de la capacidad reportada de AirMax en instalaciones nuevas
airmax_flexible_frame_download_ratio = 0.8  # Reparto de respaldo para flexible framing de AirMax cuando UISP no expone dlRatio
ltu_capacity = 1.0      # Usar 100% de la capacidad reportada de LTU en instalaciones nuevas
infrastructure_transport_caps_enabled = true  # Limitar automáticamente la capacidad del radio al techo activo/conocido de los puertos Ethernet

# Gestión de Sitios
exclude_sites = []  # Sitios a excluir, ej: ["Sitio_Prueba", "Sitio_Lab"]

# 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
exception_cpes = []  # Excepciones de CPE en formato ["cpe:parent"]
squash_sites = []  # Opcional: sitios a compactar
do_not_squash_sites = []  # Opcional: nombres de sitios que deben permanecer sin compactar en runtime/exportació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.

• do_not_squash_sites: exclusiones explícitas por nombre de sitio para la compactación de runtime/exportación.

• ignore_calculated_capacity: usa capacidades configuradas en lugar de calculadas.

• insecure_ssl: deshabilita validación de certificados TLS para UISP.

• airmax_flexible_frame_download_ratio: cuando UISP reporta capacidad agregada de un AP AirMax con flexible framing y no entrega dlRatio, LibreQoS usa esta proporción de descarga como respaldo. 0.8 significa 80/20 descarga/subida.

Los sondeos de salud de adjuntos en Topology Manager usan las IPs de gestión reportadas por UISP para el par de adjuntos seleccionado. Las compilaciones actuales ya no filtran esas IPs de sondeo mediante allow_subnets de shaping; la lista permitida de direcciones de shaping sigue aplicándose a los datos generados de shaping de suscriptores/dispositivos, pero no a los destinos de sondeo de topología del plano de gestión.

Las versiones actuales limitan este manejo de flexible framing a equipos donde UISP reporta identification.type == "airMax" y identification.role == "ap". En esos AP AirMax, theoreticalTotalCapacity se usa solo como pista de flexible framing. La velocidad real de shaping sale de totalCapacity cuando UISP lo entrega, o de la capacidad direccional más fuerte cuando no lo hace, y la división sigue prefiriendo dlRatio cuando UISP lo reporta.

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. La compactación UISP de runtime/exportación siempre está habilitada después de Topology Manager. Use do_not_squash_sites solo cuando un camino concreto de sitio deba permanecer sin compactar.

Nota heredada:

• Los valores existentes de enable_squashing en /etc/lqos.conf se ignoran por compatibilidad hacia atrás.

Para probar la integración con UISP, ejecute:

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. Las integraciones incluidas no sobrescriben network.json; conserve network.json como entrada DIY/manual operada por el usuario.

ShapedDevices.csv será sobrescrito cada vez que se ejecute la integración de UISP.

Si UISP expone nombres visibles duplicados, las compilaciones actuales conservan los IDs estables de UISP y diferencian los nombres duplicados exportados de dispositivos/AP con un sufijo de ID corto, como Nanoswitch [7c57e383]. En colisiones de nombre entre sitio y AP, el sitio conserva el nombre simple y el lado AP recibe el sufijo para que una rama no oculte otra en el árbol heredado.

Las integraciones incluidas no sobrescriben network.json; conserve network.json como entrada DIY/manual operada por el usuario.

Tiene la opción de ejecutar uisp_integration 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

Puede usar las siguientes entradas de override para reflejar su red con mayor precisión:

• Rate Override para cambios de ancho de banda a nivel de nodo guardados como entradas operatorias AdjustSiteSpeed en lqos_overrides.json

• Topology Override para correcciones de selección de padre en UISP full, también guardadas en lqos_overrides.json

• integrationUISPbandwidths.csv solo como entrada heredada de compatibilidad

Las compilaciones actuales aplican Topology Override antes de generar network.json y ShapedDevices.csv. El soporte actual en WebUI es solo Pinned Parent, forzando un único padre inmediato detectado.

Las compilaciones UISP actuales también auto-migran un integrationUISPbandwidths.csv heredado hacia overrides operatorios AdjustSiteSpeed en la siguiente ejecución de la integración cuando todavía no existen overrides de tasa del operador. Si ya existen, el CSV se ignora. Las entradas JSON heredadas uisp.bandwidth_overrides se ignoran. La ruta autoritativa para overrides de ancho de banda es AdjustSiteSpeed en lqos_overrides.json. Las compilaciones UISP actuales ignoran las entradas heredadas uisp.route_overrides en lqos_overrides.json y los archivos heredados integrationUISProutes.csv. Si existe cualquiera de los dos, LibreQoS registra una advertencia y usa la topología detectada más los overrides de Topology Manager.

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í. Para utilizarlos, copie el archivo (eliminando la parte .template del nombre) y edítelo con la información correspondiente. Para cambios nuevos de ancho de banda, use los overrides operatorios en lqos_overrides.json. integrationUISPbandwidths.csv queda como una entrada heredada para migración única hacia AdjustSiteSpeed, no como el flujo preferido a largo plazo.

Para la intención de camino, use la selección de padre y la preferencia de attachments en Topology Manager. Ese es ahora el reemplazo soportado para los antiguos overrides de costo de ruta de UISP.

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:

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.

Las integraciones incluidas no sobrescriben network.json; conserve network.json como entrada DIY/manual operada por el usuario.

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:

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:

python3 integrationSonar.py

En la primera ejecución exitosa, se crearán los archivos network.json y ShapedDevices.csv. Las integraciones incluidas no sobrescriben network.json; conserve network.json como entrada DIY/manual operada por el usuario. 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

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