LibreQoS Software Components

Systemd Services

        flowchart LR
    A[CRM/NMS Integrations] --> B[lqos_scheduler]
    C[network.json + ShapedDevices.csv] --> B
    D[lqos_overrides.json] --> B
    B --> E[Queue/shaping plan refresh]
    E --> F[lqosd]
    F --> G[XDP/TC shaping runtime]
    F --> H[WebUI :9123]
    B --> I[Scheduler Status / Urgent Issues]
    F --> I

lqosd

Manages actual XDP code.
Coded in Rust.
Runs the GUI available at http://a.b.c.d:9123
Hosts WebUI pages such as:
- Site Map
- Flow Globe
- Network Tree Overview
- ASN Analysis
- CPU Tree / CPU Weights
- Configuration editors for integrations (UISP, Splynx, Netzur, VISP, etc.)

lqos_scheduler

lqos_scheduler performs continuous refreshes of LibreQoS’ shapers, including pulling from any enabled CRM Integrations (UISP, Splynx, Netzur).
Actions:
- On start: Run a full setup of queues
  - Current builds wait briefly for lqosd to finish binding the local bus before the first scheduler run.
- Every X minutes: Update queues, pulling new configuration from CRM integration, if enabled.
  - The default minute interval is 30, so the refresh occurs every 30 minutes by default.
  - The minute interval is adjustable with the setting queue_refresh_interval_mins in /etc/lqos.conf.

Checking service status

sudo systemctl status lqosd lqos_scheduler

If the status of one of the two services shows ‘failed’, examine why using journalctl, which shows the full status of the service. For example, if lqosd failed, you would run:

sudo journalctl -u lqosd -b

Press the End key on the keyboard to take you to the bottom of the log to see the latest updates to that log.

Lqosd will provide specific reasons it failed, such as an interface not being up, an interface lacking multi-queue, or other concerns.

Debugging lqos_scheduler

In the background, lqos_scheduler runs the Python script scheduler.py, which in turn runs the Python script LibreQoS.py

scheduler.py: performs continuous refreshes of LibreQoS’ shapers, including pulling from any enabled CRM Integrations (UISP, Splynx, Netzur).
LibreQoS.py: creates and updates queues / shaping of devices

One-time runs of these individual components can be very helpful for debugging and to make sure everything is correctly configured.

First, stop lqos_scheduler

sudo systemctl stop lqos_scheduler

For one-time runs of LibreQoS.py, use

sudo ./LibreQoS.py

To use the debug mode with more verbose output, use:

sudo ./LibreQoS.py --debug

To confirm that lqos_scheduler (scheduler.py) is able to work correctly, run:

sudo python3 scheduler.py

If an integration fails during a scheduler run, current builds keep the scheduler alive, surface a shortened output preview in scheduler status/error reporting, and save the full captured output to a timestamped /tmp/lqos_scheduler_<integration>_*.log file.

Once you have any errors eliminated, restart lqos_scheduler with

sudo systemctl start lqos_scheduler

Troubleshooting Service Components

Please see Troubleshooting.

WebUI privacy mode

WebUI (Node Manager) includes a client-side redaction mode for demos/screenshots:

Toggle using the mask icon in the top navigation.
Redaction preference is saved in browser local storage.
This masks/redacts visible data in the browser UI; it does not modify source data files.

For public screenshots, enable redaction before capture.

Urgent issue channel

WebUI (Node Manager) includes an urgent issue channel for high-priority events (for example, mapped-circuit limit enforcement and related operational warnings).

Urgent issues appear in the top navigation indicator.
They can be reviewed and acknowledged from the urgent issues modal.
Use this as an at-a-glance operational signal; confirm details in journalctl -u lqosd.

Scheduler status indicator

WebUI (Node Manager) includes scheduler status visibility for operator awareness.

Use scheduler status as a quick health signal for recurring refresh jobs.
If scheduler is not healthy, validate lqosd and lqos_scheduler service state first.
Confirm details with:
- journalctl -u lqos_scheduler --since "30 minutes ago"
- journalctl -u lqosd --since "30 minutes ago"