v2.2

LibreQoS 2.2: What Changed Since 2.1

LibreQoS 2.2 guides operators from a fresh install through admin creation, interface selection, network preview, and service startup in the browser. Operators can build topology visually, shape subscribers created from RADIUS sessions, and compare queued demand with traffic that actually crossed the wire.

This changelog covers changes from LibreQoS 2.1, released March 31, 2026, through LibreQoS 2.2, released August 18, 2026. It also includes related improvements in LibreQoS Insight and the paid LibreQoS API.

TL;DR: The Biggest Upgrades

• Go from fresh install to running system with guided first-run setup. A temporary, protected setup page helps create the first admin, choose interfaces and operating mode, preview network changes, enable HTTPS, and hand control to the normal LibreQoS services.
• Build and manage topology visually. The new Topology Manager gives operators a clear workspace for reviewing sites, changing parent relationships, finding unmapped items, and publishing a safe network layout.
• See actual traffic, not only queued traffic. Key dashboards, circuit pages, tree views, Insight data, and API responses can now distinguish traffic offered to a queue from traffic that was actually transmitted. Operators can compare subscriber demand with delivered throughput.
• Create subscriber circuits from RADIUS sessions. LibreQoS can listen for RADIUS accounting events and dynamically add, update, and remove subscriber circuits for PPPoE and other session-based networks.
• Finish subscriber setup with a clear source-of-truth choice. After the core system starts, the new Complete Setup page guides operators to a built-in CRM/NMS integration, an in-house importer, or manual subscriber files.
• Run with stronger security by default. Web access now requires authentication, login attempts are rate limited, browser security rules are tighter, and sensitive session details receive better protection.
• Troubleshoot faster. StormGuard diagnostics, topology probes, clearer warnings, effective-rate explanations, and stronger reload reporting help operators find the cause of a problem without guessing.
• Import cleaner subscriber and topology data. UISP, VISP, Sonar, Splynx, Netzur, and MikroTik workflows now cover more account layouts and handle subscriber matching more reliably.
• Keep service steady during changes. Queue reloads, topology publishing, WebUI recovery, and background work received extensive reliability improvements designed to reduce interruptions and lockups.
• Plan upgrades with Insight evidence. New circuit and site reports flag plan-limit pressure, historical ASN views show traffic sources, geographic maps show site location, and multi-shaper accounts keep one connected view.
• Build better tools with the LibreQoS API. The API adds combined circuit views, richer CAKE statistics, Quality of Outcome data, actual transmitted throughput, and named local API keys.

LibreQoS 2.2

Topology Manager and Network Visibility

• The new Topology Manager brings network review, site and circuit inspection, and topology changes into one WebUI workspace.
• Dedicated attention views make unmapped items and incomplete integration data easy to find.
• Parent selection tools move sites and circuits without hand-editing large JSON files.
• Safe publishing prepares and validates a new layout before it replaces the active version.
• Validation catches duplicate circuits, conflicting identifiers, invalid parents, and other common mistakes.
• Logical and queue-visible nodes remain clear, so the WebUI can show the business layout and the structure used for traffic control.
• Topology probes test reachability and health from the same area used to manage the network, with clear reasons when a test cannot run.
• Improved UISP attachment handling so devices keep their intended native parents during import and refresh.
• Preserved UISP transit-device virtualization in full topology mode, improving the layout of networks with intermediate devices.
• Improved site export and removed duplicate UISP site identifiers.
• Stabilized flat-network placement so subscribers are assigned more consistently across reloads.
• Added stronger locking and validation around topology publication to prevent overlapping updates and stale output.
• Added automatic fallback warnings when runtime topology output cannot be used, helping operators understand which data source is active.
• Added a dedicated topology data-flow guide that explains which files are operator inputs, which data is generated, and what LibreQoS uses while shaping.

Queued Traffic and Actual Transmitted Traffic

• LibreQoS now tracks traffic offered to a queue separately from traffic actually transmitted through it.
• The main dashboard uses actual transmitted throughput where delivery rate is the useful measure.
• Circuit pages show what the subscriber actually received and sent, rather than only what entered the queue.
• Network tree totals and Insight reporting use transmitted traffic for live delivery views.
• Preserved queued traffic data for queue analysis. Operators and API users can compare demand with delivered traffic instead of losing either measurement.
• Improved throughput attribution so circuit totals, device totals, and active-flow details stay aligned.
• Added richer queue data for CAKE, including more of the statistics needed to understand delay, drops, marks, and queue behavior.
• Improved queue counter handling for large values and long-running systems.

RADIUS Accounting and Dynamic Subscribers

• A new RADIUS accounting service supports session-driven subscriber networks.
• Start, update, and stop events can create, refresh, and remove dynamic circuits.
• Subscribers can match by user name or MAC address.
• Stable circuit identifiers help reconnecting subscribers keep a consistent identity when the accounting data allows it.
• IP addresses follow active subscriber sessions, and expired sessions are removed automatically.
• Added protection so a permanent circuit from ShapedDevices.csv takes priority over a temporary dynamic circuit.
• Added a RADIUS configuration page in the WebUI.
• Added controls for shared secrets, listening addresses, fallback parents, subscriber speeds, and identity sources.
• Added status logging so operators can confirm that accounting is enabled and receiving usable events.
• Added a portable test harness and a full operator guide for MikroTik PPPoE and other RADIUS accounting deployments.
• Added dynamic subscribers to Node Manager, the network tree, queue management, and lqtop views.
• Kept dynamic subscribers separate from TreeGuard actions where automatic topology changes would be unsafe.

Dynamic Circuits Beyond RADIUS

• Added tools to promote unknown IP addresses into managed dynamic circuits.
• Added range rules for grouping or assigning previously unknown traffic.
• Added a WebUI editor for dynamic circuit settings.
• Added a clearer inventory view so operators can see which circuits are temporary and where they came from.
• Added automatic expiration for dynamic records that are no longer active.
• Improved save behavior and protected the configuration from recursion and stack-overflow failures.
• Added fallback loading from ShapedDevices.csv when an imported topology is missing or empty.

First-Run Setup, Interfaces, Bridges, and HTTPS

• Fresh installations now open a dedicated browser-based setup service.
• Protected, time-limited links keep initial configuration from becoming an open administration page.
• The setup flow creates the first administrator and will not apply the finished configuration until that account exists.
• Automatic interface discovery lists the network ports LibreQoS finds on the host.
• Operators choose between the recommended Linux bridge and a single-interface deployment with plain-language guidance.
• Preserved existing legacy XDP bridge settings during upgrades while steering new installations toward the current recommended mode.
• Added plain-language validation that prevents the same port from being selected as both the internet-facing and subscriber-facing side.
• A preview shows managed network changes before confirmation.
• Changes that may interrupt setup-page access include a confirmation and rollback path.
• An on-screen report lists the completed setup actions.
• The temporary setup server hands control to the normal LibreQoS services and provides the correct WebUI link, including HTTPS when enabled.
• Added first-run support for the required Ubuntu 24.04 system service hotfix, including clear status and installation guidance.
• Added optional HTTPS setup inside the first-run flow, with a local certificate or a public hostname.
• After first login, a separate Complete Setup page explains that a running WebUI does not yet prove subscriber shaping is ready.
• Complete Setup offers three clear subscriber-data paths: a built-in CRM/NMS integration, an in-house importer, or manually maintained files.
• Runtime status shows active integrations, network.json, and ShapedDevices.csv so operators can see what is still missing.
• Direct links lead to UISP, Splynx, VISP, Netzur, Powercode, Sonar, WispGate, shared integration settings, and manual editors.
• Added Setup Required status reporting until LibreQoS has enough valid subscriber and topology data to build queues.
• Added managed bridge workflows for operators who want LibreQoS to configure the bridge between access and transit interfaces.
• Added single-interface operating support for compatible designs.
• Added MTU controls for managed bridges and single-interface setups.
• Added safer interface inspection and configuration transactions. A failed change is less likely to leave the host in a partial state.
• Added clearer setup checks for interface roles, addressing, and service readiness.
• Set the CPU governor to performance by default when supported, helping avoid avoidable latency and throughput swings.
• Added an optional Caddy-based HTTPS setup with local-certificate and public-certificate choices.
• Added WebUI controls for enabling, reviewing, and disabling HTTPS.
• Added safe API listener rules when HTTPS is enabled, including loopback guidance for local proxy setups.
• Added service restart coordination after HTTPS changes so the WebUI and API return on their expected addresses.
• Moved Python dependencies into a root-owned virtual environment during supported installs, reducing conflicts with system Python packages.
• Improved Ubuntu 24.04 system service fixes and version detection.

WebUI Improvements

• Reorganized configuration into focused pages instead of one oversized screen.
• Added clearer sections for general settings, interfaces, queues, integrations, TreeGuard, tuning, HTTPS, dynamic circuits, and RADIUS.
• Improved WebSocket recovery so dashboards reconnect more cleanly after a service restart or network interruption.
• Improved loading, empty, and error states across several pages.
• Fixed edit buttons for devices with numeric identifiers.
• Fixed urgent-warning dialogs that could lock up after clearing an item.
• Reduced false urgent warnings while XDP mappings are still loading at startup.
• Added effective circuit rates to the tree and circuit views.
• Added an explanation of what currently limits each effective rate, such as the subscriber plan, a parent limit, or an active override.
• Added infrastructure Ethernet caps to help operators spot links that may be limiting a branch.
• Simplified the Tree page by removing an extra overview tab and keeping the important details together.
• Replaced the old 3D world-map component with a faster, browser-policy-friendly MapLibre view.
• Added optional operator cobranding with a custom logo.
• Improved privacy and redaction behavior for screenshots and shared troubleshooting sessions.
• Reduced noisy logs from expected WebSocket timeouts and routine browser requests.
• Improved responsiveness by bounding slow background requests and reducing lock contention in live flow data.

Queue Management and Reload Reliability

• Changed full traffic-control reloads so traffic drains through the default path instead of suffering an avoidable cutout.
• Fixed a problem that could leave extra queues behind after repeated full reloads in memory-saving mode.
• Large memory-saving configurations now show a clear capacity warning when they can safely continue.
• Delayed Bakery queue startup until local license information is ready, preventing licensed circuits from being skipped during boot.
• Fixed a bus-handler deadlock that could stall circuit requests.
• Added limits around blocking work so one slow task is less likely to freeze other Node Manager operations.
• Added diagnostics for overloaded internal work queues, helping support identify which part of the service is falling behind.
• Improved queue-diff reset behavior after reconnects and reloads.
• Improved recovery when an interface attach or reload step fails.
• Changed the service watchdog to report problems without taking an overly aggressive recovery action.
• Reduced queue and topology reload churn when source data has not meaningfully changed.
• Improved recovery checks and startup warnings when subscriber IP mappings are not ready.

StormGuard and TreeGuard

• Added StormGuard status and diagnostics to the network tree.
• Added bounded diagnostic history so operators can see recent actions without creating unlimited data growth.
• Added clearer explanations for adjustment, hold, recovery, and disabled states.
• Improved early recovery when link conditions return to normal.
• Fixed rate restoration when StormGuard is disabled.
• Improved reset behavior so disabling the feature returns sites to their expected limits.
• Improved dynamic TreeGuard handling and cleanup of virtual overrides.
• Routed override changes through the main LibreQoS writer, reducing competing file updates.

Integration Improvements

• UISP: Improved full-topology imports, parent selection, route overrides, bandwidth overrides, suspension handling, and device virtualization.
• UISP: Added better handling for AP capacities, site management choices, legacy configuration, and incomplete topology data.
• VISP: Expanded subscriber coverage and added IRM topology import support.
• VISP: Improved ISP selection and optional online-session enrichment.
• Sonar: Added uninventoried MAC addresses as devices, helping operators account for active equipment that is not attached to a full inventory record.
• Sonar: Improved imported subscriber data and test coverage for common edge cases.
• Splynx: Improved topology strategies, root-node promotion, speed handling, and override behavior.
• Netzur and MikroTik: Added a TOML-based MikroTik IPv6 credential workflow and more reliable IPv6 enrichment.
• Improved shared integration handling for ignored subnets, uneven data, virtual nodes, and stable subscriber identity.
• Improved scheduler fault reporting so an integration problem is visible without ending future scheduled runs.

Flow, NetFlow, and Network Analysis

• Fixed NetFlow v9 IPv4 address byte order, so exported addresses are interpreted correctly.
• Fixed NetFlow uptime wraparound log storms on long-running exporters.
• Improved NetFlow 5 field handling and validation.
• Improved active-flow circuit metadata so flows are tied to the correct subscriber context.
• Reduced lock contention in the full flow list, improving responsiveness on busy systems.
• Improved flow timestamps and protected the Flow Explorer from invalid time values.
• Added safer handling for very large counters and conversions.
• Improved lqtop top-flow and top-host displays.

Security and Access Control

• Removed anonymous WebUI access. Operators must sign in before viewing network data.
• Added login rate limiting to slow repeated password attempts.
• Removed overly broad browser access permissions.
• Added a Content Security Policy to reduce the risk of injected browser content.
• Protected WebUI session tokens from accidental exposure.
• Fixed unsafe rendering paths for operator names, themes, and other browser-visible values.
• Added named local API keys that can be created, identified, and revoked individually.
• Protected API credentials when configuration pages save unrelated settings.
• Expanded API access eligibility for supported licenses with up to 1,000 mapped circuits.
• Updated vulnerable dependencies identified during the release security review.

Documentation and Operator Guidance

• Expanded the quick-start guide for current setup and service behavior.
• Added full English and Spanish RADIUS accounting guides.
• Added topology data-flow documentation for both integration-driven and manual networks.
• Added HTTPS setup and removal instructions.
• Expanded integration references for UISP, VISP, Sonar, Splynx, Netzur, WISPGate, and Powercode.
• Expanded troubleshooting for reloads, topology output, integrations, and service startup.
• Updated performance, operating-mode, API, TreeGuard, StormGuard, and Node Manager documentation.
• Added clearer guidance for installed paths, configuration sources, and runtime-generated files.

LibreQoS Insight Improvements

Insight can now rank circuit and site upgrade candidates, export the results, map network sites, analyze historical ASN traffic, and combine data from multiple shapers.

Upgrade Planning and Executive Reports

• Added circuit upgrade analysis that compares observed demand with each subscriber's plan speed.
• Added site upgrade analysis so operators can find branches with several subscribers approaching their limits.
• Added upgrade-eligible circuit reports based on observed capacity, not only configured values.
• Added category totals so teams can quickly separate urgent candidates, watch-list items, and circuits with no current concern.
• Upgrade reports can be downloaded as CSV files for sales, support, and network planning teams.
• Added complete report streaming in small batches. Large accounts can load full results without waiting for one oversized response.
• Improved report limits and compatibility with older LibreQoS upgrade-analysis data.

Maps, History, and Multi-Shaper Accounts

• Replaced the node map with a geographic site map that uses topology coordinates.
• Added optional latitude and longitude support for network-tree nodes.
• Added historical ASN analysis so operators can see which networks and services drove traffic over time.
• Improved ASN loading and added lazy evidence retrieval for faster initial pages.
• WebUI charts now share time markers, so the same event lines up across traffic, latency, and retransmit views.
• Improved circuit timelines across accounts with more than one shaper.
• Combined circuit devices across all connected shapers.
• Routed live circuit views to the shaper that is currently serving the circuit.
• Preserved topology views when several shapers report parts of the same account.
• Improved overlapping-shaper display on the node map.
• Improved chart scaling for stacked throughput and child traffic.

Libby Assistant

• Expanded Libby's operator tools for investigating shapers, sites, circuits, clients, devices, and ASNs.
• Improved documentation search by combining exact keyword matches with meaning-based search.
• Added stronger evidence rules so answers are tied more closely to available network data.
• Added limits around tool use and response size so investigations stay focused and predictable.
• Routed remote Libby sessions through the shaper gateway for more reliable access.
• Preserved compatibility with the existing LibreQoS client protocol.

Account, Billing, and Licensing Experience

• Improved signup address and country handling.
• Added fresh regional pricing during signup.
• Improved browser checkout completion and recovery from delayed billing events.
• Added a copyable license key to the account page.
• Improved login for email addresses connected to more than one account by asking for the needed license key only when necessary.
• Added offline license bundles for systems that cannot regularly contact Insight.
• Added support for the Forever Free API license option.
• Improved billing reconciliation, cancellation handling, operator notifications, and recovery from delayed or repeated payment events.

Insight Reliability

• Improved topology ingest stability and device-address reconciliation.
• Added ingest health information to the admin dashboard.
• Kept the last known good geographic data available when a refresh fails.
• Reduced slow database work on common circuit, site, and executive pages.
• Fixed a locking problem that could stall shaper updates.
• Improved static-file fallback behavior during service deployment.
• Added stronger handling for stale billing and webhook database connections.

Paid LibreQoS API Improvements

The paid API gained richer circuit and queue information while keeping existing field names compatible.

New Data and Endpoints

• Added combined circuit endpoints that bring live and summary information together for simpler client applications.
• Added Quality of Outcome endpoints for understanding subscriber experience, not only traffic volume.
• Added extended CAKE queue statistics for deeper queue-health analysis.
• Added actual transmitted throughput to circuit responses.
• Kept the existing bytes_per_second field for queued traffic and added actual_bytes_per_second for delivered traffic. Existing clients can continue working while new clients gain the clearer measurement.
• Added actual throughput to circuit lookup, IP lookup, all-circuits, active-user, and missing-user responses that use the shared circuit format.

Authentication and Access

• Added named local API keys. Operators can issue a separate key for each application or integration instead of sharing one unnamed secret.
• Added support for verifying, listing, and revoking those local keys through the LibreQoS configuration system.
• Updated the API access policy to match LibreQoS 2.2 licensing for supported systems with up to 1,000 mapped circuits.
• Improved API authentication and tightened the default Caddy listener setup.

Data Quality and Stability

• Added validation for invalid site-speed samples.
• Added safe handling for invalid or infinite round-trip-time samples.
• Updated the bundled LibreQoS version and generated API description to match the 2.2 data model.

Upgrade Notes

• Review the current quick-start and update guides before upgrading, especially if LibreQoS manages your bridge or HTTPS configuration.
• Back up /etc/lqos.conf, network.json, ShapedDevices.csv, integration settings, and overrides before changing versions.
• If you use an integration, review the Topology Manager after the first successful import and before publishing manual parent changes.
• If you enable RADIUS accounting, test start, update, stop, and reconnect behavior in a lab before placing it in the subscriber path.
• If you consume the paid API, existing queued-throughput fields remain available. Adopt the new actual-throughput field when your application needs delivered traffic.
• After upgrading, confirm that circuits are loaded, queues are active, the WebUI reconnects, and traffic totals match the intended interfaces.