6.8 KiB
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/{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.
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:
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 install:
cd /tmp
wget https://download.libreqos.com/{deb_url_v1_5}
sudo apt install ./{deb_url_v1_5}
- 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 network.json and ShapedDevices.csv with your own automation |
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.