mirror of
https://github.com/LibreQoE/LibreQoS.git
synced 2026-10-25 06:17:39 -05:00
4.7 KiB
4.7 KiB
Quickstart: ISP Deployment Path
Use this page to move from install to a safe pilot with minimal ambiguity.
Need definitions for key terms? See the Glossary.
1) Common Install Foundation
Complete this once:
- Review architecture and sizing:
- Prepare host and OS:
- Configure bridge mode:
- Install LibreQoS (
.debrecommended):
cd ~
sudo apt-get update
sudo apt-get upgrade
wget https://download.libreqos.com/{deb_url_v1_5}
sudo apt install ./{deb_url_v1_5}
`ShapedDevices.csv` can contain unlimited entries. In v2.0, active shaping without a valid Insight subscription/license is limited to the first 1000 valid mapped circuits. See [Insight Licensing Behavior](insight.md#mapped-circuit-limits-and-license-state).
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
After the reboot, resume the install:
cd ~
sudo apt install ./{deb_url_v1_5}
- Open WebUI at
http://your_shaper_ip:9123.
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.
If this fails, go to Troubleshooting before proceeding.
3) Decision A: Deployment Stage
Choose one:
- Lab first: validate behavior in a controlled environment before inline traffic.
- Inline pilot now: proceed directly with limited production traffic.
If lab-first:
- Build a lab topology.
- Generate test traffic.
- Validate Dashboard, Tree, Flow, Scheduler Status, and Urgent Issues.
- Continue to Decision B.
4) Decision B: Source of Truth (Pick One Owner)
| If this describes you | Mode | Owner of durable shaping data |
|---|---|---|
| You use a supported CRM/NMS integration | Built-in integration mode | Integration jobs |
You generate network.json and ShapedDevices.csv with your own scripts |
Custom source of truth mode | Your scripts |
| You maintain files manually for a small/simple network | Manual files mode | Manual edits |
Rule: keep one owner for persistent shaping inputs.
5) Path Cards
Built-In Integration Mode
When to choose:
- Your CRM/NMS is supported by built-in integrations.
Do this now:
- Configure integration settings in WebUI.
- Run initial sync and validate imported shaping/topology data.
- Place LibreQoS inline for pilot traffic.
- Validate Scheduler Status, Urgent Issues, and topology/flow views.
- Expand pilot scope after stable operation.
Next:
Custom Source of Truth (Your Scripts)
When to choose:
- Your CRM/NMS is unsupported and you 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 (<100 Subscribers)
When to choose:
- You intentionally maintain
network.json+ShapedDevices.csvwithout CRM/NMS synchronization.
Do this now:
- Build and maintain shaping files directly.
- Place LibreQoS inline for pilot traffic.
- Validate shaping and scheduler status in WebUI.
- Maintain strict manual change discipline.
- Plan migration to supported integration or scripts if scale/change volume grows.
Next:
6) Common First-Run Mistakes
- Unclear source of truth ownership between integration and manual edits.
- Changing topology depth before passing the health gate.
- Skipping post-change service/log validation before pilot traffic.