LibreQoS/docs/v2.0/quickstart.md

Quickstart: Choose Your Deployment Path

Use this page to choose the correct deployment path quickly, then execute only the steps for that path.

Need definitions for key terms? See the Glossary.

flowchart TD
    A[Start Here: Quickstart] --> B{Choose Path}
    B --> C[Testbed / Lab]
    B --> D[Supported Integration]
    B --> E[Custom Script Integration]
    B --> F[Manual Files <100 subscribers]
    C --> G[Configure + Validate in WebUI]
    D --> G
    E --> G
    F --> G
    G --> H[Troubleshoot / Optimize / Scale]

Common Install Foundation

Complete this once before any path-specific steps.

1. Review deployment assumptions and capacity:
   • Deployment Scenarios
   • System Requirements
2. Prepare host and OS:
   • Server Setup - Prerequisites
   • Install Ubuntu Server 24.04
3. Configure bridge mode:
   • Configure Shaping Bridge
4. Install LibreQoS (.deb recommended):

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}

5. Open WebUI at http://your_shaper_ip:9123.

After Install: What Good Looks Like (10-Minute Check)

Before deeper configuration, verify baseline health:

1. Services are active:

sudo systemctl status lqosd lqos_scheduler

2. WebUI loads and updates (Dashboard + Scheduler Status).
3. No urgent/fatal errors in recent logs:

journalctl -u lqosd -u lqos_scheduler --since "10 minutes ago"

4. Your chosen source of truth is clear:

• integration mode: integration owns refresh of shaping inputs
• custom/manual mode: your files/scripts own persistence

If these checks fail, continue in Troubleshooting before pilot rollout.

Decide Source of Truth (Do This Once)

Before continuing, choose who owns ongoing shaping data updates:

If this describes you	Choose this mode	Next page
You use a supported CRM/NMS integration	Built-in integration mode	CRM/NMS Integrations
You generate network.json and ShapedDevices.csv from your own scripts	Custom source of truth mode	Operating Modes and Source of Truth
You maintain files directly (small/simple networks)	Manual files mode	Operating Modes and Source of Truth

Rule: keep one owner for persistent shaping inputs to avoid overwrite conflicts.

Testbed / Lab

When to choose

You want to validate behavior in a controlled environment before inline production.

Do this now

1. Build a lab topology (LibreQoS + traffic generator endpoints + optional OSPF/BGP path simulation).
2. Choose a lab track:
   • Lab with manual files: validate network.json + ShapedDevices.csv behavior.
   • Lab with supported integration: validate imported subscriber/topology data.
3. Generate traffic and validate in WebUI (Dashboard, Tree, Flow, Scheduler Status, Urgent Issues).
4. Confirm expected shaping behavior and stability.

Then go here

• Configure LibreQoS
• Troubleshooting

Supported Integration

When to choose

Your CRM/NMS is supported by built-in LibreQoS integrations.

Do this now

1. Configure integration settings in WebUI.
2. Run initial sync and validate imported shaping/topology data.
3. Place LibreQoS inline for pilot traffic.
4. Validate WebUI health signals (Scheduler Status, Urgent Issues, topology/flow views).
5. Expand pilot scope after stable operation.

Note:

• In integration mode, ShapedDevices.csv is typically regenerated by sync jobs.
• network.json overwrite behavior depends on integration settings (for example always_overwrite_network_json).

Then go here

• CRM/NMS Integrations
• Troubleshooting

Custom Script Integration

When to choose

Your CRM/NMS is unsupported and you will generate network.json + ShapedDevices.csv with your own pipeline.

Do this now

1. Implement script/process to generate and refresh shaping files.
2. Declare your script outputs as source of truth.
3. Place LibreQoS inline for pilot traffic.
4. Use WebUI for operational checks and quick adjustments.
5. Move permanent changes back into your script workflow.

Note:

• WebUI edits are useful for quick operations.
• Long-term state should be maintained by your external source of truth workflow.
• File format reference: see network.json and ShapedDevices.csv sections in Advanced Configuration Reference.

Then go here

• Operating Modes and Source of Truth
• Troubleshooting

Manual Files (<100 subscribers)

When to choose

You intentionally maintain network.json + ShapedDevices.csv directly without CRM/NMS synchronization.

Recommended only for networks under 100 subscribers.

Do this now

1. Build and maintain shaping files directly.
2. Place LibreQoS inline for pilot traffic.
3. Validate shaping and scheduler status in WebUI.
4. Maintain strict manual change discipline.
5. Plan migration to supported integration or custom scripts if scale/change volume grows.

Then go here

• Advanced Configuration Reference
• Troubleshooting

Common First-Run Mistakes

• Unclear source of truth ownership between integration and manual edits.
• Choosing deeper topology strategy before confirming baseline health.
• Skipping post-install service/log checks before pilot traffic.

Use:

• Operating Modes and Source of Truth
• Troubleshooting