CRM/NMS Integrations

Page Purpose

Use this page to choose and configure a supported CRM/NMS integration. Use the per-integration pages for setup details.

Need definitions for common terms? See the Glossary.

Most operators use built-in integrations. If you have not selected a deployment path yet, start with Quickstart.

flowchart LR
    A[CRM/NMS] --> B[LibreQoS Integration Job]
    B --> H[topology_import.json]
    H --> E[lqos_scheduler]
    E --> F[Shaping Updates]
    E --> G[WebUI Status / Urgent Issues]

Choose Your Integration Path

Path	Best fit	Where permanent shaping changes belong
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`)

Where in WebUI

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 Globe

Built-In Integrations

Important Refresh Behavior

When integrations are enabled:

Integration sync refreshes the imported topology and shaping data LibreQoS uses.
Built-in integrations do not use network.json or ShapedDevices.csv as their normal output files.
Built-in integrations provide native infrastructure topology to Topology Manager; legacy compatibility trees remain derived/export-only data.
Python-backed integrations currently import infrastructure conservatively as fixed roots or fixed-parent branches. When bounded alternative-parent candidates are available, they are limited to the node's current local parent neighborhood, plus peer root parents of the same type when the current parent is itself a root, rather than the whole imported graph.
If you run a DIY or manual deployment, network.json and ShapedDevices.csv remain the files you maintain.
Direct edits to integration-managed data may be replaced on the next refresh cycle.

Mode capabilities are now explicit by integration:

UISP: flat, ap_only, ap_site, full
Splynx: flat, ap_only, ap_site, full
Sonar: flat, full
Manual edits may be overwritten on the next refresh cycle.

Legacy integrationUISPbandwidths.csv and integrationSplynxBandwidths.csv files are auto-migrated into operator AdjustSiteSpeed entries in lqos_overrides.json and renamed to .backup files.

DIY/manual deployments continue to use network.json and ShapedDevices.csv as their primary input files.

Topology Node ID Support

LibreQoS supports an optional generic "id" field on network.json nodes. This field is intended to carry stable node identifiers from the integration source where possible.

Current behavior:

when a node ID is available, LibreQoS uses it to match saved site bandwidth overrides more reliably
older name-only matching still works as a fallback for older data
topology names still need to remain globally unique in network.json

Integration	`network.json` node ID support	Notes
UISP	Yes	Real UISP sites/devices export generic `id` plus existing `uisp_site` / `uisp_device` metadata. Synthetic LibreQoS nodes use stable generated IDs.
Splynx	Yes	Network sites and AP/site topology nodes export generic `id`.
Sonar	Yes	Site and AP topology nodes export generic `id`.
Netzur	Partial	Exported only when the upstream zone data includes a stable zone ID.
VISP	No	Current importer shapes services/devices but does not build topology nodes in `network.json`.
Powercode	No	Current importer does not build topology nodes in `network.json`.
WISPGate	No	Current importer does not build topology nodes from stable upstream topology identifiers.

Common Client Rate Handling

For built-in integrations that import raw subscriber plan speeds, LibreQoS applies the same shared client-rate rule before writing ShapedDevices.csv:

effective client max rate = max(plan_rate * bandwidth_overhead_factor, plan_rate * client_bandwidth_multiplier)

Integrations that already ingest effective shaped rates keep those values as-is rather than applying the multiplier a second time.

4.9 KiB Raw Blame History