Quickstart: ISP Deployment Path
Use this page to move from install to a safe pilot.
Most ISPs, should use a LibreQoS built-in integration.
Use this page in order:
Complete install and bridge setup.
Complete first-run WebUI access.
Pass the 10-minute health check.
Pick one source of truth owner.
Follow the recommended path for that owner.
Need definitions for key terms? See the Glossary.
1) Common Install Foundation
Complete this once before trying to shape live traffic:
Review architecture and sizing:
Prepare host and OS:
Configure how traffic will pass through the LibreQoS box:
This step is required before production use. If bridge/interface setup is wrong, later WebUI and shaping checks will be misleading.
Install LibreQoS (
.debrecommended):
cd /tmp
sudo apt-get update
sudo apt-get upgrade
wget https://download.libreqos.com/libreqos_2.1.202603311003-1_amd64.deb
sudo apt install ./libreqos_2.1.202603311003-1_amd64.deb
Using /tmp avoids local .deb permission issues where apt cannot access a package stored in a private home directory as user _apt.
Ubuntu 24.04 hotfix if the .deb install stops
On affected Ubuntu 24.04 hosts using systemd-networkd, the .deb install may stop and print a hotfix requirement message. This is expected.
If that happens, run:
cd /tmp/
sudo apt-get update
sudo HOTFIX_PACKAGE_VERSION=255.4-1ubuntu9999+libreqos1 /opt/libreqos/src/systemd_hotfix.sh install
sudo dpkg --configure -a
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 install:
cd /tmp
wget https://download.libreqos.com/libreqos_2.1.202603311003-1_amd64.deb
sudo apt install ./libreqos_2.1.202603311003-1_amd64.deb
Open WebUI at
http://your_shaper_ip:9123.
If no WebUI users exist yet, current builds redirect you to the first-run setup page automatically instead of presenting a normal login flow.
Complete first-run access:
Create the initial WebUI user if prompted.
Confirm you can sign in.
Confirm the Dashboard opens before doing any integration or topology work.
2) 10-Minute Health Check
Run:
sudo systemctl status lqosd lqos_scheduler
journalctl -u lqosd -u lqos_scheduler --since "10 minutes ago"
Confirm:
WebUI Dashboard loads.
Scheduler Status is healthy.
No urgent/fatal startup errors in logs.
You can sign in successfully after first-run setup.
If this fails, go to Troubleshooting before proceeding.
3) Pick One Source of Truth Owner
This is the most important early decision.
Source of truth means: the one place that should own persistent shaping data.
If you make persistent changes somewhere else, they may be overwritten later.
Choose one:
If this describes you |
Mode |
Owner of durable shaping data |
|---|---|---|
You use a supported LibreQoS CRM/NMS integration |
Built-In Integration Mode |
Integration jobs |
You generate |
Custom Source of Truth Mode |
Your scripts |
You intentionally maintain files by hand |
Manual Files Mode |
Manual edits |
Rule: keep one owner for persistent shaping inputs.
Most operators should stop here and choose Built-In Integration Mode.
Only choose the other two modes if you already know why.
4) Recommended Path: Built-In Integration Mode
This is the default path for most ISPs, including most small ISPs.
When to choose:
Your CRM/NMS is supported by built-in integrations.
Do this now:
Configure integration settings in WebUI.
Run the initial sync.
Confirm outputs were created or refreshed:
network.jsonShapedDevices.csv
Confirm Scheduler Status is healthy.
Confirm Network Tree reflects the expected hierarchy depth for your chosen integration strategy.
Confirm there are no urgent/fatal issues that block shaping.
Only then move to limited pilot traffic or inline use.
Do not do this:
Do not hand-edit integration-owned files as your normal workflow.
Do not split ownership between integration syncs and manual file edits unless you intentionally want that complexity.
Do not change overwrite behavior unless you understand how your integration should own
network.json.
Next:
5) Other Paths
Custom Source of Truth Mode
When to choose:
Your CRM/NMS is unsupported and you already generate
network.json+ShapedDevices.csvwith your own pipeline.
Do this now:
Implement script/process to generate and refresh shaping files.
Declare script outputs as your source of truth.
Place LibreQoS inline for pilot traffic.
Use WebUI for operational checks and short-term adjustments.
Keep permanent changes in your external script workflow.
Format reference:
See
network.jsonandShapedDevices.csvsections in Advanced Configuration Reference.
Next:
Manual Files Mode
When to choose:
You intentionally maintain
network.json+ShapedDevices.csvwithout CRM/NMS synchronization.Your network is small/simple enough that manual discipline is realistic.
You are doing a temporary pilot or working around an unsupported system.
Do this now:
Build
network.json.Build
ShapedDevices.csv.Restart or validate services.
Confirm the expected topology and devices appear in WebUI.
Validate shaping and scheduler status before adding more complexity.
Maintain strict manual change discipline.
This is not the normal recommendation for operators who already use a supported LibreQoS integration.
Next:
6) Common First-Run Mistakes
Unclear source of truth ownership between integration and manual edits.
Hand-editing files even though your integration is supposed to own them.
Changing topology depth before passing the health gate.
Skipping post-change service/log validation before pilot traffic.
Treating low-data or cold-start pages as proof that shaping is broken.
Changing too many things before you have one known-good baseline.
7) Done For Day 1 When
You can sign in to WebUI successfully.
Dashboard loads.
Scheduler Status is healthy.
No urgent/fatal startup errors are present.
The expected topology or devices appear.
One test subscriber/device behaves as expected.