LibreQoS/docs/v2.0/update.md

Upgrading

If you use the XDP bridge, traffic will briefly stop passing through the bridge when lqosd restarts (XDP bridge is only operating while lqosd runs).

If you installed the .deb

Starting in v2.0, mapped-circuit ingest depends on valid Insight license state. Without a valid Insight subscription/license, LibreQoS reads only the first 1000 valid mapped circuits into active shaping state. This includes expired or otherwise invalid local grant/license state. See [Insight Licensing Behavior](insight.md#mapped-circuit-limits-and-license-state) and [Troubleshooting](troubleshooting.md).

Run:

cd /tmp
sudo apt-get update
sudo apt-get upgrade
wget https://download.libreqos.com/{deb_url_v1_5}
sudo apt install ./{deb_url_v1_5}

Using /tmp avoids local .deb permission issues where apt cannot access a package stored in a private home directory as user _apt.

If apt install completes normally, restart services:

sudo systemctl restart lqosd lqos_scheduler

Ubuntu 24.04 hotfix if the upgrade stops

On affected Ubuntu 24.04 hosts using systemd-networkd, apt install may stop with a hotfix requirement message. This is expected.

If that happens, run:

sudo /opt/libreqos/src/systemd_hotfix.sh install
sudo reboot

The hotfix installer bootstraps the LibreQoS APT repo at https://repo.libreqos.com, installs the patched Noble systemd package set, and pins those packages for future updates.

After the reboot, resume the upgrade and restart services:

cd /tmp
wget https://download.libreqos.com/{deb_url_v1_5}
sudo apt install ./{deb_url_v1_5}
sudo systemctl restart lqosd lqos_scheduler

Post-upgrade reboot

Now reboot the LibreQoS box with:

sudo reboot

This will flush the old eBPF maps and load the latest LibreQoS version.

Then continue with the normal post-upgrade validation below.

Post-Upgrade Validation (Required)

Run these checks after upgrade/reboot:

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

Then verify:

1. WebUI Dashboard and Scheduler Status are healthy.
2. Integration users: a fresh sync produces expected ShapedDevices.csv/network.json behavior.
3. Topology depth matches your chosen integration strategy.

If checks fail, go directly to Troubleshooting before further config changes.

If you installed with Git

1. Change to your LibreQoS directory (e.g. cd /opt/libreqos)
2. Update from Git: git pull
3. git switch develop
4. Recompile: ./build_rust.sh
5. sudo rust/remove_pinned_maps.sh

Ubuntu 24.04 hotfix for Git installs

Before restarting LibreQoS services on Ubuntu 24.04, check whether the Noble systemd-networkd hotfix should be offered:

cd /opt/libreqos/src
./systemd_hotfix.sh status

If the script reports that the hotfix should be offered, install it and reboot before continuing:

sudo ./systemd_hotfix.sh install
sudo reboot

Run the following commands to reload the LibreQoS services.

sudo systemctl restart lqosd lqos_scheduler

Notes on pinned BPF maps

rust/remove_pinned_maps.sh removes pinned maps used by the eBPF/XDP pipeline so newer map schemas can load cleanly after upgrades.

Recent versions include additional map cleanup (including ip_mapping_epoch). If this cleanup is skipped after a schema-changing upgrade, you may see stale behavior or mapping inconsistencies.

If you use Git installs, keep this order:

1. build/update binaries
2. stop/restart services as needed
3. run sudo rust/remove_pinned_maps.sh
4. restart lqosd and lqos_scheduler

Stop-and-Triage Symptoms

Pause rollout and triage immediately if you see:

• lqosd or lqos_scheduler not healthy after restart
• unexpected hierarchy collapse/expansion after integration sync
• persistent scheduler unhealthy state in WebUI

Primary references:

• Troubleshooting
• CRM/NMS Integrations