Install LibreQoS 1.4

Updating from v1.3

Remove offloadOff.service

sudo systemctl disable offloadOff.service
sudo rm /usr/local/sbin/offloadOff.sh /etc/systemd/system/offloadOff.service

Remove cron tasks from v1.3

Run sudo crontab -e and remove any entries pertaining to LibreQoS from v1.3.

Simple install via .Deb package (Recommended)

Use the deb package from the latest v1.4 release.

Complex install (Not Recommended)

Clone the repo

The recommended install location is /opt/libreqos Go to the install location, and clone the repo:

cd /opt/
git clone https://github.com/LibreQoE/LibreQoS.git libreqos
sudo chown -R YOUR_USER /opt/libreqos

By specifying libreqos at the end, git will ensure the folder name is lowercase.

Install Dependencies from apt and pip

You need to have a few packages from apt installed:

sudo apt-get install -y python3-pip clang gcc gcc-multilib llvm libelf-dev git nano graphviz curl screen llvm pkg-config linux-tools-common linux-tools-`uname -r` libbpf-dev

Then you need to install some Python dependencies:

cd /opt/libreqos
python3 -m pip install -r requirements.txt
sudo python3 -m pip install -r requirements.txt

Install the Rust development system

Go to RustUp and follow the instructions. Basically, run the following:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

When Rust finishes installing, it will tell you to execute a command to place the Rust build tools into your path. You need to either execute this command or logout and back in again.

Once that’s done, please run:

cd /opt/libreqos/src/
./build_rust.sh

This will take a while the first time, but it puts everything in the right place.

Now, to build rust crates, run:

cd rust
cargo build --all

Configure LibreQoS

Configure lqos.conf

Copy the lqosd daemon configuration file to /etc:

cd /opt/libreqos/src
sudo cp lqos.example /etc/lqos.conf

Now edit the file to match your setup with

sudo nano /etc/lqos.conf

Change enp1s0f1 and enp1s0f2 to match your network interfaces. It doesn’t matter which one is which. Notice, it’s paring the interfaces, so when you first enter enps0f1 in the first line, the redirect_to parameter is enp1s0f2 (replacing with your actual interface names).

First Line: name = "enp1s0f1", redirect_to = "enp1s0f2"
Second Line: name = "enp1s0f2", redirect_to = "enp1s0f1"

Then, if using Bifrost/XDP set use_xdp_bridge = true under that same [bridge] section.

Configure ispConfig.py

Copy ispConfig.example.py to ispConfig.py and edit as needed

cd /opt/libreqos/src/
cp ispConfig.example.py ispConfig.py
nano ispConfig.py

Set upstreamBandwidthCapacityDownloadMbps and upstreamBandwidthCapacityUploadMbps to match the bandwidth in Mbps of your network’s upstream / WAN internet connection. The same can be done for generatedPNDownloadMbps and generatedPNUploadMbps.
Set interfaceA to the interface facing your core router (or bridged internal network if your network is bridged)
Set interfaceB to the interface facing your edge router
Set enableActualShellCommands = True to allow the program to actually run the commands.

Network.json

Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology.

For networks with no Parent Nodes (no strictly defined Access Points or Sites) edit the network.json to use a Flat Network Topology with nano network.json setting the following file content:

{}

If you plan to use the built-in UISP or Splynx integrations, you do not need to create a network.json file quite yet.

If you plan to use the built-in UISP integration, it will create this automatically on its first run (assuming network.json is not already present). You can then modify the network.json to more accurately reflect your topology.

If you will not be using an integration, you can manually define the network.json following the template file - network.example.json

+-----------------------------------------------------------------------+
| Entire Network                                                        |
+-----------------------+-----------------------+-----------------------+
| Parent Node A         | Parent Node B         | Parent Node C         |
+-----------------------+-------+-------+-------+-----------------------+
| Parent Node D | Sub 3 | Sub 4 | Sub 5 | Sub 6 | Sub 7 | Parent Node F |
+-------+-------+-------+-------+-------+-------+-------+-------+-------+
| Sub 1 | Sub 2 |       |                       |       | Sub 8 | Sub 9 |
+-------+-------+-------+-----------------------+-------+-------+-------+

Manual Setup

You can use

python3 csvToNetworkJSON.py

to convert manualNetwork.csv to a network.json file. manualNetwork.csv can be copied from the template file, manualNetwork.template.csv

Note: The parent node name must match that used for clients in ShapedDevices.csv

ShapedDevices.csv

If you are using an integration, this file will be automatically generated. If you are not using an integration, you can manually edit the file.

Manual Editing

Modify the ShapedDevices.csv file using your preferred spreadsheet editor (LibreOffice Calc, Excel, etc), following the template file - ShapedDevices.example.csv
Circuit ID is required. Must be a string of some sort (int is fine, gets parsed as string). Must NOT include any number symbols (#).
An IPv4 address or IPv6 address is required for each entry.
The Access Point or Site name should be set in the Parent Node field. Parent Node can be left blank for flat networks.
The ShapedDevices.csv file allows you to set minimum guaranteed, and maximum allowed bandwidth per subscriber.
The minimum allowed plan rates for Circuits are 2Mbit. Bandwidth min and max should both be above that threshold.
Recommendation: set the min bandwidth to something like 25/10 and max to 1.15X advertised plan rate by using bandwidthOverheadFactor = 1.15
- This way, when an AP hits its ceiling, users have any remaining AP capacity fairly distributed between them.
- Ensure a reasonable minimum bandwidth minimum for every subscriber, allowing them to utilize up to the maximum provided when AP utilization is below 100%.

Note regarding SLAs: For customers with SLA contracts that guarantee them a minimum bandwidth, set their plan rate as the minimum bandwidth. That way when an AP approaches its ceiling, SLA customers will always get that amount.

LibreQoS daemons

lqosd

Manages actual XDP code. Build with Rust.

lqos_node_manager

Runs the GUI available at http://a.b.c.d:9123

lqos_scheduler

lqos_scheduler handles statistics and performs continuous refreshes of LibreQoS’ shapers, including pulling from any enabled CRM Integrations (UISP, Splynx).
On start: Run a full setup of queues
Every 10 seconds: Graph bandwidth and latency stats
Every 30 minutes: Update queues, pulling new configuration from CRM integration if enabled

Run daemons with systemd

You can setup lqosd, lqos_node_manager, and lqos_scheduler as systemd services.

sudo cp /opt/libreqos/src/bin/lqos_node_manager.service.example /etc/systemd/system/lqos_node_manager.service
sudo cp /opt/libreqos/src/bin/lqosd.service.example /etc/systemd/system/lqosd.service
sudo cp /opt/libreqos/src/bin/lqos_scheduler.service.example /etc/systemd/system/lqos_scheduler.service

Finally, run

sudo systemctl daemon-reload
sudo systemctl enable lqosd lqos_node_manager lqos_scheduler

You can now point a web browser at http://a.b.c.d:9123 (replace a.b.c.d with the management IP address of your shaping server) and enjoy a real-time view of your network.

Debugging lqos_scheduler

In the background, lqos_scheduler runs scheduler.py, which in turn runs LibreQoS.py

One-time runs of these individual components can be very helpful for debugging and to make sure everything is correctly configured.

First, stop lqos_scheduler

sudo systemctl stop lqos_scheduler

For one-time runs of LibreQoS.py, use

sudo ./LibreQoS.py

To use the debug mode with more verbose output, use:

sudo ./LibreQoS.py --debug

To confirm that lqos_scheduler (scheduler.py) is able to work correctly, run:

sudo python3 scheduler.py

Once you have any errors eliminated, restart lqos_scheduler with

sudo systemctl start lqos_scheduler