UISP Integration

First, set the relevant parameters for UISP in /etc/lqos.conf.

New Operator Quick Chooser

Use this section first to avoid common strategy confusion.

If you are new to UISP integration, start with strategy = "ap_only".
Move to ap_site when you need explicit site-level aggregation.
Use full when you need full hierarchy/backhaul representation and have CPU headroom.
Use flat only when hierarchy is not needed and maximum performance is the priority.

Router-Mode Expectations

UISP router mode is supported, but parent/route discovery quality depends on your UISP topology data quality.
LibreQoS focuses on shaping/queue hierarchy, not subscriber lifecycle enforcement.
Account suspension enforcement is usually handled by your edge/BNG/auth platform. Use suspended_strategy only for LibreQoS-side shaping behavior.

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	Best after topology/overrides are validated and stable

Performance Note: When using full strategy with large networks, consider using promote_to_root to distribute CPU load across multiple cores.

5-Minute Validation After UISP Config Changes

Run the integration once:

cd /opt/libreqos/src
sudo /opt/libreqos/src/bin/uisp_integration

Confirm outputs were generated/refreshed as expected:

ls -lh /opt/libreqos/src/network.json /opt/libreqos/src/ShapedDevices.csv

Confirm scheduler and shaper health:

sudo systemctl status lqosd lqos_scheduler
journalctl -u lqos_scheduler --since "30 minutes ago"

Validate result in WebUI:

Scheduler Status is healthy
Tree/Flow views reflect expected hierarchy depth for selected strategy

If hierarchy depth or parent mapping is not what you expect, revisit strategy, use_ptmp_as_parent, exclude_sites, and exception_cpes before changing other settings.

Promote to Root Nodes (Performance Optimization)

When using full topology strategy, traffic can bottleneck on a single root node/CPU core.

The promote_to_root feature can reduce this by promoting selected sites to root-level nodes so load is distributed.

Configuration:

Navigate to Configuration -> Integrations in WebUI.
In Promote to Root Nodes, enter one site per line.

Example:

Remote_Site_Alpha
Remote_Site_Beta
Datacenter_West

When to use:

Multi-site networks with high-capacity remote sites.
full strategy deployments showing single-core saturation.

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

[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 = "ap_only"  # Recommended starting point for new UISP 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 = true  # Recommended when using UISP integration in production
exception_cpes = []  # CPE exceptions in ["cpe:parent"] format
squash_sites = []  # Optional: sites to squash
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:

Keep insecure_ssl = false unless you have a known internal PKI/self-signed requirement.
Use exclude_sites and do_not_squash_sites first for safer topology changes.
Apply squash_sites/enable_squashing incrementally and validate queue placement after each change.

On the first successful run, the integration creates network.json and ShapedDevices.csv. If a network.json file exists, it is only overwritten when always_overwrite_network_json = true.

ShapedDevices.csv will be overwritten every time the UISP integration is run.

When UISP client sites share the same name, LibreQoS now tries to disambiguate the generated circuit/site display names with a human-friendly suffix such as the first street-address segment, falling back to service name and then a short ID only when needed. Stable circuit identity still comes from the UISP site/service ID, not the display name.

For integration-driven deployments, keep always_overwrite_network_json = true so topology stays aligned with UISP on each refresh cycle.

You have the option to run uisp_integration 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 following files to more accurately reflect your network:

integrationUISPbandwidths.csv
integrationUISProutes.csv

Tree-page Operator Override edits are separate from these legacy UISP files. Current builds write those operator-owned node rate changes to lqos_overrides.json and do not rewrite integrationUISPbandwidths.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. 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.

To avoid conflicting sources of truth, prefer one durable override path per node: either the legacy UISP CSV workflow or the operator override layer.

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. This renders a map with the associated costs of all links.

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.