mirror of
https://github.com/LibreQoE/LibreQoS.git
synced 2026-10-25 22:30:05 -05:00
134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# Upgrading
|
|
|
|
```{warning}
|
|
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
|
|
|
|
```{important}
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](troubleshooting.md) 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```
|
|
5. Recompile: `./build_rust.sh`
|
|
6. `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:
|
|
|
|
```bash
|
|
cd /opt/libreqos/src
|
|
./systemd_hotfix.sh status
|
|
```
|
|
|
|
If the script reports that the hotfix should be offered, install it and reboot before continuing:
|
|
|
|
```bash
|
|
sudo ./systemd_hotfix.sh install
|
|
sudo reboot
|
|
```
|
|
|
|
Run the following commands to reload the LibreQoS services.
|
|
|
|
```shell
|
|
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](troubleshooting.md)
|
|
- [CRM/NMS Integrations](integrations.md)
|