IntenseWebs/LibreQoS
3
0 Fork 0
mirror of https://github.com/LibreQoE/LibreQoS.git synced 2026-10-25 22:30:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add optional Caddy HTTPS setup

Browse Source
This commit is contained in:
Herbert Wolverson committed 2026-04-16 11:06:06 -05:00
1 parent a2e68eff1a
commit 85624c7465
42 files changed
+1583 -67
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/v2.0/api.md
+4 -1
View File
@@ -13,7 +13,8 @@ This is separate from base shaping limits:
Use Swagger on your node as the complete reference and test surface for your installed build:
- `http://<node-ip>:9122/api-docs`
- Direct local API port: `http://<node-ip>:9122/api-docs`
- If optional HTTPS with Caddy is enabled for the WebUI: `https://<hostname-or-node-ip>/api/v1/api-docs`
Use this page as a capability map. Use Swagger for full endpoint inventory, request/response schemas, and live testing.
@@ -142,3 +143,5 @@ If integrations are enabled, integration refresh cycles may overwrite direct fil
- Do not expose the API directly to the public Internet.
- If remote access is needed, use a reverse proxy with TLS and authentication.
- Restrict inbound access with firewall allowlists.
If you want the WebUI and API docs on one HTTPS origin, see [Optional HTTPS With Caddy](https-caddy.md).
docs/v2.0/components.md
+4 -2
View File
@@ -10,7 +10,8 @@ flowchart LR
B --> E[Queue/shaping plan refresh]
E --> F[lqosd]
F --> G[XDP/TC shaping runtime]
F --> H[WebUI :9123]
F --> H[WebUI service :9123]
J[Optional Caddy HTTPS :443] --> H
B --> I[Scheduler Status / Urgent Issues]
F --> I
```
@@ -19,7 +20,8 @@ flowchart LR
- Manages actual XDP code.
- Coded in Rust.
- Runs the GUI available at http://a.b.c.d:9123
- Runs the GUI available at `http://a.b.c.d:9123` by default.
- If optional HTTPS is enabled, Caddy serves `https://hostname/` or `https://management-ip/` and proxies the WebUI to `127.0.0.1:9123`.
- Hosts WebUI pages such as:
- Site Map
- Flow Globe
docs/v2.0/configuration.md
+5 -1
View File
@@ -18,6 +18,8 @@ After installing the package:
4. Open `Complete Setup`
5. Choose how LibreQoS will receive subscriber and topology data
If you want operators to use HTTPS, open `Configuration -> SSL Setup` after sign-in, or enable the same option during first-run setup. See [Optional HTTPS With Caddy](https-caddy.md).
For most operators, `Complete Setup` is where the important early decision happens:
- Built-in integration for UISP, Splynx, VISP, Netzur, Powercode, Sonar, or WispGate
- Custom importer if your own process writes `network.json` and `ShapedDevices.csv`
@@ -27,13 +29,14 @@ If Scheduler Status still says `Setup Required`, LibreQoS is not ready to shape
## Configuration Via Web Interface
Most day-to-day LibreQoS configuration happens in WebUI (`http://your_shaper_ip:9123/config_general.html`).
Most day-to-day LibreQoS configuration happens in WebUI. By default that is `http://your_shaper_ip:9123/config_general.html`. If you enable optional HTTPS with Caddy, operators use `https://your-hostname/` or `https://your-management-ip/` instead.
Current builds use a consistent configuration layout across the General, RTT, Queues, TreeGuard, Network Mode, Integration Defaults, Network Layout, Insight, provider integration, IP Ranges, Flow Tracking, and Shaped Devices pages. Integration Defaults also includes the shared Ethernet port headroom policy used by integrations that can detect negotiated subscriber-facing port speeds.
### Where In WebUI
- General settings: `Configuration -> General`
- HTTPS setup: `Configuration -> SSL Setup`
- Integration settings: `Configuration -> Integrations`
- Network layout editor: `Configuration -> Network Layout`
- Shaped devices editor: `Configuration -> Shaped Devices`
@@ -101,6 +104,7 @@ For direct file editing (`/etc/lqos.conf`, `network.json`, `ShapedDevices.csv`),
## Related Pages
- [Quickstart](quickstart.md)
- [Optional HTTPS With Caddy](https-caddy.md)
- [Operating Modes and Source of Truth](operating-modes.md)
- [CRM/NMS Integrations](integrations.md)
- [LibreQoS WebUI (Node Manager)](node-manager-ui.md)
docs/v2.0/git-install.md
+2
View File
@@ -94,3 +94,5 @@ sudo systemctl start 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.
If you want operators to use HTTPS instead, sign in and open `Configuration -> SSL Setup`. See [Optional HTTPS With Caddy](https-caddy.md).
docs/v2.0/https-caddy.md
+51
View File
@@ -0,0 +1,51 @@
# Optional HTTPS With Caddy
LibreQoS can run the WebUI and API docs behind Caddy so operators can use HTTPS. This is optional. LibreQoS still works without it.
## When To Use It
Use `Configuration -> SSL Setup` when you want operators to open LibreQoS with HTTPS instead of plain HTTP on port `9123`.
You can also enable the same option during the first-run setup flow.
## Two Certificate Modes
LibreQoS supports two simple choices:
- Enter an external hostname such as `libreqos.example.com`: Caddy requests a public certificate from Let's Encrypt. Browsers should trust it automatically once DNS and inbound access are correct.
- Leave the hostname blank: Caddy secures LibreQoS by management IP address with Caddy's local certificate authority. Traffic is still encrypted, but operator computers must trust Caddy's local root certificate before browser warnings stop.
## What Changes After You Enable It
- Operators stop using `http://your_shaper_ip:9123` and instead use `https://your-hostname/` or `https://your-management-ip/`.
- LibreQoS moves the WebUI listener to `127.0.0.1:9123`.
- Caddy proxies the WebUI and API docs over HTTPS.
- Swagger moves to `/api/v1/api-docs` on the same HTTPS origin as the WebUI.
## If You Use The Local Certificate Mode
When you leave the hostname blank, the Caddy local root certificate is stored on the LibreQoS host at:
```text
/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt
```
Trust that certificate on each operator workstation that will open the HTTPS WebUI.
## Disable HTTPS
If you want to back out, open `Configuration -> SSL Setup` and choose `Disable SSL`.
LibreQoS then:
- removes the managed Caddy configuration
- restores the previous direct WebUI listener, or the normal default `:::9123` if no custom listener was set first
- returns operators to direct HTTP access on the management IP and port `9123`
## Related Pages
- [Quickstart](quickstart.md)
- [Configure LibreQoS](configuration.md)
- [LibreQoS WebUI (Node Manager)](node-manager-ui.md)
- [LibreQoS Node API](api.md)
- [Troubleshooting](troubleshooting.md)
docs/v2.0/node-manager-ui.md
+3 -1
View File
@@ -1,6 +1,6 @@
# LibreQoS WebUI (Node Manager)
This page documents key WebUI (Node Manager) views and operational behavior in the local WebUI (`http://your_shaper_ip:9123`).
This page documents key WebUI (Node Manager) views and operational behavior in the local WebUI. By default operators use `http://your_shaper_ip:9123`. If optional HTTPS with Caddy is enabled, operators use `https://your-hostname/` or `https://your-management-ip/` instead.
For the full logical-topology versus queue-topology file flow, see [Topology Data Flow](topology-data-flow.md).
@@ -173,6 +173,7 @@ Practical meaning:
- Saved passwords, API tokens, and keys stay hidden when you open an integration page.
- If a credential is already configured, the field stays blank until you type a replacement. Use `Clear` only when you want to remove the saved value.
- Leave the field blank to keep the current value. Enter a new value to replace it.
- `Configuration -> SSL Setup` can install Caddy, switch the WebUI behind HTTPS, and later disable that HTTPS setup if you want to return to direct HTTP on port `9123`.
### Urgent Issues
- WebUI can display urgent operational issues reported by LibreQoS services.
@@ -221,4 +222,5 @@ If only Site Map is blank or slow while other pages are healthy, also check mana
- [Components](components.md)
- [Configuration](configuration.md)
- [Optional HTTPS With Caddy](https-caddy.md)
- [Troubleshooting](troubleshooting.md)
docs/v2.0/quickstart.md
+3
View File
@@ -61,6 +61,8 @@ sudo apt install ./{deb_url_v1_5}
3. Create the initial WebUI admin user if prompted.
4. Sign in and confirm the Dashboard opens.
Optional: if operators need HTTPS, enable `Configuration -> SSL Setup` after sign-in, or enable the same option during first-run setup. See [Optional HTTPS With Caddy](https-caddy.md).
At this point, the WebUI being available does not yet prove that LibreQoS is ready to shape subscribers.
If Scheduler Status says `Setup Required`, that is expected until you choose a topology source and publish usable shaping data.
@@ -172,6 +174,7 @@ Expand only after you have one known-good baseline.
## 8) Related Pages
- [Configure LibreQoS](configuration.md)
- [Optional HTTPS With Caddy](https-caddy.md)
- [Operating Modes and Source of Truth](operating-modes.md)
- [CRM/NMS Integrations](integrations.md)
- [Advanced Configuration Reference](configuration-advanced.md)
docs/v2.0/troubleshooting.md
+12 -5
View File
@@ -8,7 +8,7 @@ Need definitions for licensing/scheduler terms? See the [Glossary](glossary.md).
| Symptom | First check | WebUI location | Next section |
|---|---|---|---|
| Cannot access WebUI | `systemctl status lqosd` | N/A (UI unavailable) | No WebUI at x.x.x.x:9123 |
| Cannot access WebUI | `systemctl status lqosd caddy` | N/A (UI unavailable) | No WebUI at x.x.x.x:9123 or HTTPS URL |
| Traffic is not shaping | verify `to_internet` / `to_network`, service state | WebUI Dashboard | LibreQoS Is Running, But Traffic Not Shaping |
| Scheduler appears unhealthy | check `lqosd` and `lqos_scheduler` logs | WebUI -> Scheduler Status | Scheduler status in WebUI looks unhealthy |
| Topology/flow views blank | confirm recent traffic and `lqosd` health | WebUI -> Flow Globe / Tree / ASN Analysis | Flow Globe / Tree Overview / ASN Analysis appears blank |
@@ -63,17 +63,24 @@ If the correct username/password still fails, first restart `lqosd` and try agai
sudo systemctl restart lqosd
```
Only remove `lqusers.toml` if you are intentionally resetting access or if the file is corrupt and cannot be repaired. After removing it, restart `lqosd` and open `BOX_IP:9123/login.html`; the WebUI should redirect you to first-run setup automatically.
Only remove `lqusers.toml` if you are intentionally resetting access or if the file is corrupt and cannot be repaired. After removing it, restart `lqosd` and open `BOX_IP:9123/login.html` if SSL is disabled; the WebUI should redirect you to first-run setup automatically.
### No WebUI at x.x.x.x:9123
### No WebUI at x.x.x.x:9123 or HTTPS URL
The WebUI is controlled by the `lqosd` service. In current builds, most WebUI access failures are caused by `lqosd` not being healthy.
The WebUI is controlled by `lqosd`. If optional HTTPS with Caddy is enabled, `caddy` also has to be healthy.
Start by checking:
```
sudo systemctl status lqosd
sudo systemctl status lqosd caddy
```
Then:
- If SSL is disabled, test `http://your-management-ip:9123/`
- If SSL is enabled with a hostname, test `https://your-hostname/`
- If SSL is enabled without a hostname, test `https://your-management-ip/`
- If browsers warn in local-certificate mode, trust `/var/lib/caddy/.local/share/caddy/pki/authorities/local/root.crt` on the operator workstation
Then follow the full workflow in **Service lqosd is not running or failed to start** below.
### LibreQoS Is Running, But Traffic Not Shaping