Deploy LibreQoS on your own hardware
Install the supported Debian package, complete setup in the WebUI, and validate with a limited pilot before rolling into production. Inline Linux Bridge is the default path, and the installer handles the bridge setup automatically for most operators.
Network design
Where LibreQoS fits
Inline between your edge and core. A separate bypass keeps a backup route available.
Normal operation
Traffic flows through LibreQoS.
Inline path unavailable
Routing switches to the bypass.
Path restored
Traffic returns to LibreQoS.
With NAT / CG-NAT, place LibreQoS on the subscriber side so it can see pre-NAT addresses.
Deployment plan
Plan your deployment
Start small, validate real traffic, then roll into production.
Evaluate
Use spare hardware to explore the UI and confirm the workflow fits your network.
Pilot
Validate a limited set of subscribers or devices before expanding.
Production
Confirm hardware fit, bypass capacity, and failover before broad rollout.
Hardware
Choose your hardware
Choose a platform, check the prerequisites, and compare reference builds for your network.
Bare metal or VM?
Bare metal is the default for production. A VM works well where virtualization is already standard and throughput stays under 10 Gbps.
Bare Metal
Best default for production throughput, lowest overhead, and clearer performance expectations.
VM
A supported option when virtualization is already standard. Best under 10 Gbps unless you use passthrough NICs.
Before you buy or roll out
Platform fit
- Ubuntu Server 24.04
- High single-thread CPU performance matters more than generic core count alone
- Enough RAM for expected subscriber scale
- 50 GB or more of disk
- Disable hyper-threading / SMT
- Disable SR-IOV where required
Network fit
- Use a separate management interface
- Use a supported shaping NIC family
- Do not use bonded shaping interfaces
- VM deployments need multiqueue aligned to vCPU
- Above 10 Gbps on VM usually requires passthrough
- Single Interface remains an advanced option only
Deployment profiles
Small
Up to about 1,000 subscribers and up to roughly 1 Gbps. Good fit for pilots, smaller production networks, and lighter managed WiFi environments.
2+ strong cores, 8 GB RAMMedium
Roughly 1,000 to 5,000 subscribers and around 1 to 10 Gbps. A common fit for established WISPs, smaller fiber operators, and many production VM deployments.
6-16 cores, 32-64 GB RAMLarge
Roughly 5,000 to 20,000 subscribers and around 10 to 50 Gbps. Requires stronger CPU selection, more RAM, and supported higher-speed NICs.
16-64 cores, 64-128 GB RAMHigh-Throughput
50 Gbps and above, or deep hierarchy at scale. Prioritize high single-thread score, queue-to-core balance, and validated XDP-capable NIC support.
50 Gbps+ or deep hierarchyReference builds
These are practical starting points from the current LibreQoS hardware recommendations. Use them as starting points for a pilot or production build, then validate fit against your topology and throughput goals.
Official hardware requirements
| 1G to 10G Small Form Factor | Minisforum MS-01 with i9-12900H, 32 GB RAM, and built-in NICs. A strong compact option for pilots, smaller production deployments, and operators who want serious performance without a rack server. |
|---|---|
| 10G Rackmount | Supermicro SYS-511R-M with E-2488, 32 GB RAM, and dual 10G SFP+. A solid production starting point when you want rackmount hardware and clearer 10G expectations. |
| 10G Rackmount | Dell PowerEdge R260 with E-2456, 32 GB RAM, and Intel X710-T2L dual 10G RJ45. A practical fit where 10G copper is preferable or Dell standardization matters operationally. |
| 25G Production | Supermicro AS-1115S-FWTRT with 8534P, 64 GB RAM, and Mellanox dual SFP28. A stronger fit for operators moving beyond 10G and needing more production headroom. |
| 50G Production | Supermicro AS-1015SV-WTNRT with 8534P, 128 GB RAM, and Mellanox 100G connectivity. A higher-throughput option for larger deployments and more demanding hierarchy depth. |
| 100G Production | Supermicro AS-2015CS-TNR with 9745, 256 GB RAM, and MCX653106A-HDAT. Built for very high-throughput environments where queue-to-core balance and NIC validation matter. |
Sizing Estimator
Check hardware fit
Need a closer estimate? Expand the calculator to check CPU, NIC, RAM, and topology fit.
Open hardware sizing estimator
Type to search the CPU catalog, then click a matching model below.
Optional target inputs
Fit
good
No explicit target entered. This card shows conservative upper bounds from the docs.
Aggregate throughput
up to ~10 Gbps
Per AP / OLT / top-level node
up to ~6 Gbps
Per subscriber plan
up to ~6 Gbps
Max circuits supported
up to ~4,800
Warnings
- Intel modules can be vendor-locked. Verify optics compatibility.
Install Flow
Install and complete setup
For most operators, the installer creates the Linux Bridge automatically, so deployment starts from the CLI and continues in the WebUI.
Install LibreQoS
Run these commands on a supported Ubuntu Server 24.04 host. Setup continues in the WebUI.
cd /tmp && wget https://download.libreqos.com/libreqos_2.2.202609081854-1_amd64.deb && sudo apt-get install -y ./libreqos_2.2.202609081854-1_amd64.debInstall Ubuntu Server 24.04
Prepare the host, keep management separate, and verify the machine matches the profile and NIC guidance.
Install the Debian package
Copy the package commands to install LibreQoS without manually building the Linux Bridge.
Open the WebUI on :9123
Open the WebUI and confirm the system is healthy.
Run Complete Setup
Connect LibreQoS to the data source you use for shaping and topology.
Validate with a pilot
Do not treat a loading dashboard as proof. Confirm scheduler health and one known-good subscriber or device.
Validation
Validate your pilot
Production readiness depends on scheduler health, topology health, and a validated pilot, not just package installation.
Health check
- Dashboard loads
- Scheduler is no longer Setup Required
- Expected topology or subscriber/device list appears
- lqosd and lqos_scheduler are healthy
Pilot readiness
- One pilot subscriber or device behaves as expected
- Expected hierarchy depth appears
- No urgent startup errors remain
- Only then expand toward production cutover
Operational checklist
- Use deterministic OSPF or BGP preference between primary and bypass paths
- Validate backup-path capacity for realistic degraded-state demand
- Test failover and failback during maintenance windows, not just in theory
- Do not skip the limited pilot just because installation was fast
Start your deployment
Once hardware fit and rollout expectations are clear, install the package and continue setup in the WebUI.