Configure LibreQoS

Page Purpose

Use this page for daily operations and WebUI configuration. Use Advanced Configuration Reference for direct file editing and CLI-heavy workflows.

Initial Configuration Via Setup Tool (From the .deb installer)

setup_tool

The setup tool configures initial bridge, interface, bandwidth, IP range, and WebUI user settings.

Notes:

  • The setup tool is keyboard-driven (Enter to select, Q to quit without saving).

Next Steps

After install, sign in to WebUI at http://your_shaper_ip:9123.

If no WebUI users exist yet, current builds redirect to first-run setup automatically.

For most operators:

  1. Choose your operating mode: Operating Modes and Source of Truth

  2. Configure integration settings in WebUI: CRM/NMS Integrations

  3. Validate scheduler and shaping behavior in WebUI: LibreQoS WebUI (Node Manager)

Configuration Via Web Interface

Most day-to-day LibreQoS configuration is handled in WebUI (http://your_shaper_ip:9123/config_general.html).

Current builds use shared configuration panels on the General, RTT, Queues, TreeGuard, Network Mode, Integration Defaults, Network Layout, Insight, provider-specific integration pages, IP Ranges, Flow Tracking, and Shaped Devices pages so node settings and operational tuning follow the same surface styling as the rest of Node Manager. The TreeGuard page starts with a live behavior summary rather than a permanent warning banner.

Where in WebUI

  • General settings: Configuration -> General

  • Integration settings: Configuration -> Integrations

  • Network layout editor: Configuration -> Network Layout

  • Shaped devices editor: Configuration -> Shaped Devices

  • Runtime operational validation: WebUI (Node Manager) pages (dashboard/tree/flow/scheduler)

When an integration is enabled and acting as the source of truth, the Network Layout and Shaped Devices editors remain viewable but become read-only in WebUI.

Topology note:

  • network.json node names must be globally unique across the whole tree. Duplicate node names now fail validation and are not accepted by the WebUI save path or LibreQoS.py.

  • When a node exposes a stable id, current builds prefer that ID for operator-owned site bandwidth overrides while keeping legacy name-only matching as a fallback.

Queue-mode note:

  • Current builds use queue_mode with shape and observe values. Older monitor_only wording is a compatibility alias rather than the primary operator-facing setting.

Operating Modes and Source of Truth

Read this first before production changes:

QoO (Quality of Outcome) profiles (qoo_profiles.json)

LibreQoS displays QoO as an estimate of internet quality based on latency and loss.

Where the file lives

<lqos_directory>/qoo_profiles.json

Selecting a profile

  • WebUI: Configuration -> General -> QoO Profile

  • Config file: set qoo_profile_id in /etc/lqos.conf

Example:

# /etc/lqos.conf
qoo_profile_id = "web_browsing"

Applying changes

  • Changes to qoo_profiles.json are picked up automatically.

  • If you change /etc/lqos.conf, restart lqosd.

Need CLI or File-Level Changes?

For direct file editing (/etc/lqos.conf, network.json, ShapedDevices.csv), overrides, and deeper topology/circuit reference material, use: