IntenseWebs/LibreQoS
3
0
Fork 0
mirror of https://github.com/LibreQoE/LibreQoS.git synced 2025-02-25 18:55:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #568 from LibreQoE/main

Browse Source 
Documentation updates
This commit is contained in:
Robert Chacón
2024-11-03 07:58:34 -08:00
committed by GitHub
parent 11c8a25c1c 903fc282c4
commit 1c594a701d
6 changed files with 127 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/v1.5/Quickstart/configuration.md
View File

@@ -1,15 +1,11 @@
# Configure LibreQoS
## Configure lqos.conf
## Main Configuration File
### /etc/lqos.conf
If you installed LibreQoS the complex (Git) installation, you can copy the lqosd daemon configuration file to `/etc`. This is not neccesarry if you installed using the .deb:
The LibreQoS configuration for each shaper box is stored in the file `/etc/lqos.conf`.
```shell
cd /opt/libreqos/src
sudo cp lqos.example /etc/lqos.conf
```
Now edit the file to match your setup with
Edit the file to match your setup with
```shell
sudo nano /etc/lqos.conf
@@ -33,7 +29,8 @@ After changing any part of `/etc/lqos.conf` it is highly recommended to always r
Learn more about [configuring integrations here](../TechnicalDocs/integrations.md).
## Network.json
## Network Hierarchy
### Network.json
Network.json allows ISP operators to define a Hierarchical Network Topology, or Flat Network Topology.
@@ -62,7 +59,7 @@ setting the following file content:
{}
```
## CSV to JSON format helper
#### CSV to JSON conversion helper
You can use
@@ -75,14 +72,29 @@ manualNetwork.csv can be copied from the template file, manualNetwork.template.c
Note: The parent node name must match that used for clients in ShapedDevices.csv
## ShapedDevices.csv
## Circuits
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 using either the WebUI or by directly editing the ShapedDevices.csv file through the CLI.
LibreQoS shapes individual devices by their IP addresses, which are grouped into "circuits".
### Manual Editing by WebUI
A circuit represents an ISP subscriber's internet service, which may have just one associated IP (the subscriber's router may be assigned a single /32 IPv4 for example) or it might have multiple IPs associated (maybe their router has a /29 assigned, or multiple /32s).
LibreQoS knows how to shape these devices, and what Node (AP, Site, etc) they are contained by, with the ShapedDevices.csv file.
### ShapedDevices.csv
The ShapedDevices.csv file correlates device IP addresses to Circuits (each internet subscriber's unique service).
Here is an example of an entry in the ShapedDevices.csv file:
| Circuit ID | Circuit Name | Device ID | Device Name | Parent Node | MAC | IPv4 | IPv6 | Download Min Mbps | Upload Min Mbps | Download Max Mbps | Upload Max Mbps | Comment |
|------------|--------------|-----------|-------------|-------------|-----|---------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------|
| 10001 | Person Name | 10001 | Device 1 | AP_A | | 100.64.0.2, 100.64.0.8/29 | fdd7:b724:0:100::/56 | 25 | 5 | 155 | 20 | |
If you are using one of our CRM integrations, this file will be automatically generated. If you are not using an integration, you can manually edit the file using either the WebUI or by directly editing the ShapedDevices.csv file through the CLI.
#### Manual Editing by WebUI
Navigate to the LibreQoS WebUI (http://a.b.c.d:9123) and select Configuration > Shaped Devices.
### Manual Editing by CLI
#### Manual Editing by CLI
- 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 (#). Every circuit needs a unique CircuitID - they cannot be reused. Here, circuit essentially means customer location. If a customer has multiple locations on different parts of your network, use a unique CircuitID for each of those locations.

2
docs/v1.5/Quickstart/quickstart-libreqos-1.5.md
View File

@@ -8,7 +8,7 @@
### Download .DEB Package (Recommended Method)
Donwload the latest .deb from https://libreqos.io/#download .
Donwload the latest .deb from [libreqos.io/#download](https://libreqos.io/#download).
Unzip the .zip file and transfer the .deb to your LibreQoS box, installing with:
```

42
docs/v1.5/Quickstart/services-and-run.md
View File

@@ -1,40 +1,40 @@
# LibreQoS daemons
# LibreQoS systemd service daemons
lqosd
- Manages actual XDP code. Build with Rust.
- Manages actual XDP code.
- Coded in Rust.
- 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 30 minutes: Update queues, pulling new configuration from CRM integration if enabled
- Minute interval is adjustable with the setting `queue_refresh_interval_mins` in `/etc/lqos.conf`.
- lqos_scheduler performs continuous refreshes of LibreQoS' shapers, including pulling from any enabled CRM Integrations (UISP, Splynx).
- Actions:
- On start: Run a full setup of queues
- Every X minutes: Update queues, pulling new configuration from CRM integration, if enabled.
- The default minute interval is 30, so the refresh occurs every 30 minutes by default.
- The minute interval is adjustable with the setting `queue_refresh_interval_mins` in `/etc/lqos.conf`.
## Run daemons with systemd
## Checking service status
Note: If you used the .deb installer, you can skip this section. The .deb installer automatically sets these up.
You can setup `lqosd`, and `lqos_scheduler` as systemd services.
```shell
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
```
sudo systemctl status lqosd lqos_scheduler
```
Finally, run
```shell
sudo systemctl daemon-reload
sudo systemctl enable lqosd lqos_scheduler
If the status of one of the two services shows 'failed', examine why using journalctl, which shows the full status of the service. For example, if lqosd failed, you would run:
```
sudo journalctl -u lqosd -b
```
Press the End key on the keyboard to take you to the bottom of the log to see the latest updates to that log.
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.
Lqosd will provide specific reasons it failed, such as an interface not being up, an interface lacking multi-queue, or other cocnerns.
## Debugging lqos_scheduler
In the background, lqos_scheduler runs scheduler.py, which in turn runs LibreQoS.py
In the background, lqos_scheduler runs the Python script scheduler.py, which in turn runs the Python script LibreQoS.py
- scheduler.py: performs continuous refreshes of LibreQoS' shapers, including pulling from any enabled CRM Integrations (UISP, Splynx).
- LibreQoS.py: creates and updates queues / shaping of devices
One-time runs of these individual components can be very helpful for debugging and to make sure everything is correctly configured.

49
docs/v1.5/TechnicalDocs/git-install.md
View File

@@ -1,4 +1,4 @@
# Git install
# Git Install (For Developers Only - Not Recommended)
## Clone the repo
@@ -27,18 +27,10 @@ Then you need to install some Python dependencies:
```shell
cd /opt/libreqos
pip install requirements.txt --break-system-packages
sudo pip install requirements.txt --break-system-packages
PIP_BREAK_SYSTEM_PACKAGES=1 pip install -r requirements.txt
sudo PIP_BREAK_SYSTEM_PACKAGES=1 pip install -r requirements.txt
```
## Python 3.10 quirk (will fix later)
```
cd /opt/libreqos/src/rust
cargo update
sudo cp /usr/lib/x86_64-linux-gnu/libpython3.11.so /usr/lib/x86_64-linux-gnu/libpython3.10.so.1.0
```
## Install the Rust development system
Run the following:
@@ -64,3 +56,38 @@ Now, to build rust crates, run:
cd rust
cargo build --all
```
## Lqos.conf
Copy the lqos.conf configuration file to `/etc`. This is not neccesarry if you installed using the .deb:
```shell
cd /opt/libreqos/src
sudo cp lqos.example /etc/lqos.conf
```
## Configuration
Proceed to configure settings [following this guide](../Quickstart/configuration.md).
## Daemon setup
## Run daemons with systemd
Note: If you used the .deb installer, you can skip this section. The .deb installer automatically sets these up.
You can setup `lqosd`, and `lqos_scheduler` as systemd services.
```shell
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
```shell
sudo systemctl daemon-reload
sudo systemctl enable lqosd 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.

53
docs/v1.5/TechnicalDocs/troubleshooting.md
View File

@@ -2,28 +2,55 @@
## Common Issues
### No WebUI at x.x.x.x:9123
The WebUI is controlled by the lqosd service. Usually, when the WebUI doesn't start, it is related to lqosd being in a failed state.
Check to see if the lqosd service is running:
```
sudo systemctl status lqosd
```
If the status is 'failed', examine why using journalctl, which shows the full status of the service:
```
sudo journalctl -u lqosd -b
```
Press the End key on the keyboard to take you to the bottom of the log to see the latest updates to that log.
Lqosd will provide specific reasons it failed, such as an interface not being up, an interface lacking multi-queue, or other cocnerns.
### LibreQoS Is Running, But Traffic Not Shaping
- In /etc/lqos.conf swap the interfaces
- Restart lqosd
```
cd /opt/libreqos/src
sudo python3 LibreQoS.py
```
In /etc/lqos.conf, ensure that `to_internet` and `to_network` are set correctly. If not, simply swap the interfaces between those and restart lqosd and the scheduler.
If that fixes it, and if you are using the scheduler service, run ```sudo systemctl restart lqos_scheduler```
```
sudo systemctl restart lqosd lqos_scheduler
```
Make sure your services are running properly
- `lqosd.service`
- `lqos_scheduler`
```
sudo systemctl status lqosd lqos_scheduler
```
The Web UI and lqos_scheduler are dependent on the `lqos.service` being in a healthy, running state.
The service lqos_scheduler is dependent on the lqosd service being in a healthy, running state.
For example to check the status of lqosd, run:
```sudo systemctl status lqosd```
### Service lqosd is not running or failed to start
Check to see the state of the lqosd service:
```
sudo systemctl status lqosd
```
If the status is 'failed', examine why using journalctl, which shows the full status of the service:
```
sudo journalctl -u lqosd -b
```
Press the End key on the keyboard to take you to the bottom of the log to see the latest updates to that log.
Lqosd will provide specific reasons it failed, such as an interface not being up, an interface lacking multi-queue, or other cocnerns.
### Advanced lqosd debug
### lqosd not running or failed to start
At the command-line, type ```sudo RUST_LOG=info /opt/libreqos/src/bin/lqosd``` which will provide specifics regarding why it failed to start.
### RTNETLINK answers: Invalid argument