¶ LibreQoS
¶ Overview
LibreQoS is an open-source traffic shaping and QoS platform for ISPs. It applies fair-queueing (CAKE) and per-subscriber rate limits to deliver lower latency and a smoother quality of experience for end users.
The Splynx LibreQoS add-on connects your Splynx instance to a LibreQoS server (typically the cloud-hosted LibreQoS Insight portal) and pulls live bandwidth usage directly from LibreQoS. Once installed and configured, Splynx can display real-time download and upload speeds for any internet service shaped by LibreQoS — including IPoE customers and customers on non-MikroTik equipment, where Splynx previously could not read live usage.
¶ Installation
The add-on can be installed in two ways: through the Splynx Web UI or from the command line on the Splynx server.
To install the add-on from the Web UI, navigate to Config → Integrations → Add-ons, type libreqos in the search field, then click the Install icon in the Actions column next to splynx-libreqos:
Confirm the installation by clicking the Ok, confirm button in the dialog:
To install the add-on via CLI on the Splynx server, run:
apt-get update
apt-get install splynx-libreqos
After installation, the add-on appears in Config → Integrations → Modules list as splynx_libreqos_addon with the Enabled entry-point status:
¶ Configuration
Before configuring the add-on in Splynx, generate an API key in your LibreQoS Insight portal:
- Sign in to insight.libreqos.com.
- Open the Account tab and create a new Splynx API key.
- Copy the generated key — you will paste it into Splynx in the next step.
Then open Config → Integrations → Modules list, click splynx_libreqos_addon, and fill in the LibreQoS configuration block:
- LibreQoS URL - URL of your LibreQoS server. Defaults to
https://insight.libreqos.comfor the cloud-hosted Insight portal. Replace with your own host (for example,https://libreqos.local) if you run LibreQoS on-premise. - LibreQoS API key - API key generated in the Account tab of the LibreQoS Insight portal. Stored encrypted — once saved, the field shows the Warning! This field has a hidden encrypted value notice instead of the key itself.
- Enable live bandwidth usage - turns on the real-time bandwidth feed from LibreQoS in customer and service views. Leave it off while you are still testing the connection and switch it on once the URL and API key are confirmed working.
- Verify SSL certificate - enabled by default. Disable it only when you connect to a local LibreQoS server that uses a self-signed certificate; otherwise leave it on so Splynx rejects untrusted certificates.
Click Save. Splynx validates the URL and the API key against the LibreQoS server before storing them. If the connection fails, the form returns a clear error message — for example, LibreQoS API key is invalid, Cannot connect to LibreQoS server, or LibreQoS server error, try again later — so you can correct the value without leaving the configuration page.
¶ How the LibreQoS add-on works
After the add-on is installed and configured, Splynx adds two entry points that take an admin from a customer record straight to the matching LibreQoS Insight view:
-
A LibreQoS action on each internet service in the customer's Services tab. Clicking it requests a short-lived statistics URL from LibreQoS for that service's IP and opens the LibreQoS Insight page filtered to that service.
-
A LibreQoS tab on the customer profile. The tab loads the LibreQoS Insight statistics view for the customer directly inside Splynx, so you do not need to switch browser tabs to check traffic shaping, latency, or throughput for that subscriber.
Both shortcuts use the LibreQoS URL and LibreQoS API key from the add-on configuration to authenticate against LibreQoS on each request. If the request fails — for example, because the API key was revoked or the LibreQoS server is unreachable — Splynx shows the Showing statistics failed message in place of the statistics view. In that case, verify that the LibreQoS server is reachable from Splynx and that the API key in the configuration is still valid.
Splynx opens a secure WebSocket subscription to the LibreQoS server using the configured URL and API key. The connection is re-subscribed automatically every 30 seconds to keep the live data stream alive. Splynx then uses the live feed to enrich existing customer and service views:
- The Live usage widget in the customer profile and on the internet service shows real-time download and upload rates pulled from LibreQoS instead of (or in addition to) the router-based feed.
- Live usage becomes available for customers on any access technology — IPoE, PPPoE, DHCP, fiber, fixed wireless — as long as their traffic passes through a LibreQoS shaper.
- All data is read on demand when an admin opens the relevant page; no background polling is added, and the configuration check is cached per request to keep the page fast.
The customer portal honors the same feed: when Enable Live bandwidth usage is on, end customers see live bandwidth in their portal as well.
¶ Troubleshooting
If live bandwidth values do not appear on a customer or service page, the page surfaces the exact reason returned by LibreQoS. The most common messages are:
| Message | What it means | What to check |
|---|---|---|
| Cannot connect to LibreQoS server | Splynx cannot reach the configured LibreQoS URL | Network connectivity, DNS, firewall rules between Splynx and LibreQoS |
| LibreQoS API key is invalid | The key was rejected by the LibreQoS server | Regenerate the key in Account → Splynx API key on Insight and update it in Splynx |
| IP address not found in LibreQoS | The customer service IP is not shaped by LibreQoS | Confirm that the customer's IP/subnet is part of the LibreQoS ShapedDevices data |
| LibreQoS server error, try again later | LibreQoS returned a 5xx response | Check LibreQoS server health and try again |
| Unexpected response from LibreQoS | The response could not be parsed | Verify that LibreQoS URL points to a LibreQoS endpoint, not another service |