mirror of
https://github.com/LibreQoE/LibreQoS.git
synced 2026-11-02 08:10:02 -06:00
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
# Operating Modes and Source of Truth
|
|
|
|
## Page Purpose
|
|
|
|
Use this page to decide where permanent shaping changes should live before you go to production.
|
|
|
|
Need definitions for terms on this page? See the [Glossary](glossary.md).
|
|
|
|
For the full file/ownership/runtime diagram, see [Topology Data Flow](topology-data-flow.md).
|
|
For static virtualization and queue-visibility behavior, see [Advanced Configuration Reference](configuration-advanced.md).
|
|
|
|
```{mermaid}
|
|
flowchart TD
|
|
A[Choose Where Changes Live] --> B{Using built-in CRM/NMS integration?}
|
|
B -->|Yes| C[Built-in Integrations Mode]
|
|
B -->|No| D{Generating files from your own scripts/systems?}
|
|
D -->|Yes| E[Custom Source of Truth Mode]
|
|
D -->|No| F[Manual Files Mode]
|
|
C --> G[Integration sync keeps shaping data current]
|
|
E --> H[Your scripts refresh the shaping files]
|
|
F --> I[You maintain the files directly]
|
|
```
|
|
|
|
LibreQoS supports three common operating modes.
|
|
|
|
## Built-in Integrations (Recommended for Most Operators)
|
|
|
|
In this mode, your CRM/NMS is where permanent subscriber and topology changes belong, and LibreQoS keeps itself in sync from that system.
|
|
|
|
Key behavior:
|
|
- Integration sync refreshes the topology and shaping data LibreQoS uses.
|
|
- Built-in integrations do not use `network.json` as their normal working file.
|
|
- Direct file edits may be overwritten on the next scheduler refresh.
|
|
- `flat` mode intentionally simplifies the tree when you want lower overhead.
|
|
- Built-in integrations can keep a fuller logical topology for Topology Manager while publishing a separate queue-visible runtime tree for `network.effective.json`, `shaping_inputs.json`, `tree.html`, and HTB.
|
|
- Large integration roots and aggregation-only sites can be auto-virtualized automatically, so the queue-visible tree does not waste HTB depth or impose artificial aggregate bottlenecks while the nodes still remain visible for monitoring.
|
|
|
|
## Custom Source of Truth
|
|
|
|
In this mode, your own scripts or systems generate `network.json` and `ShapedDevices.csv`.
|
|
|
|
Key behavior:
|
|
- Your external workflow is where permanent changes belong.
|
|
- WebUI edits are fine for quick operational changes.
|
|
- Keep your long-term changes in your own scripts or automation.
|
|
- Use `topology.compile_mode = "full"` when the `Parent Node` values in `ShapedDevices.csv` should shape under the named hierarchy in `network.json`.
|
|
- Use `flat` only when generated CPU bucket queues such as `Generated_PN_1` are the intended queue layout.
|
|
|
|
## Manual Files Mode
|
|
|
|
In this mode, you maintain `network.json` and `ShapedDevices.csv` yourself.
|
|
|
|
Key behavior:
|
|
- Best fit for small networks, short pilots, or temporary workarounds.
|
|
- WebUI helps you validate what LibreQoS is using.
|
|
- Manual discipline matters because there is no upstream system keeping those files in sync for you.
|
|
- Use `topology.compile_mode = "full"` when top-level or AP/Site parent shaping should follow `network.json`.
|
|
- If `shaping_inputs.json` shows `resolution_source: "flat_bucket"`, LibreQoS is in flat mode and circuits will show generated parent queues instead of the names from `network.json`.
|
|
|
|
## Mode Declaration Checklist (Before Go-Live)
|
|
|
|
1. Pick one primary place for permanent shaping changes.
|
|
2. Confirm which system writes production shaping data.
|
|
3. Confirm scheduler refresh behavior and overwrite cadence.
|
|
4. Document your hotfix workflow (WebUI, external editor, or both).
|
|
5. Do not maintain competing edits in multiple systems for the same objects.
|
|
|
|
## Topology and Mode Expectations
|
|
|
|
- Single-interface (on-a-stick) and VLAN-heavy designs are valid, but require explicit queue/interface planning and careful validation after changes.
|
|
- Integration mode is best when you want CRM/NMS-driven topology and subscriber lifecycle data to control shaping.
|
|
- If you need topology behavior that your integration cannot represent, use custom source of truth mode and keep the responsibility clear.
|
|
|
|
See:
|
|
- [Advanced Configuration Reference](configuration-advanced.md)
|
|
- [Troubleshooting](troubleshooting.md)
|
|
|
|
If you are running built-in integrations, continue to [CRM/NMS Integrations](integrations.md).
|
|
|
|
## Related Pages
|
|
|
|
- [Configure LibreQoS](configuration.md)
|
|
- [CRM/NMS Integrations](integrations.md)
|
|
- [Topology Data Flow](topology-data-flow.md)
|
|
- [Advanced Configuration Reference](configuration-advanced.md)
|