Operating Modes and Source of Truth

Page Purpose

Use this page to choose and enforce your source of truth policy (built-in integrations vs custom source of truth) before production changes.

Need definitions for terms on this page? See the Glossary.

        flowchart TD
    A[Choose Source of Truth] --> 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 jobs own file refresh]
    E --> H[External script pipeline owns persistence]
    F --> I[Direct file maintenance; best for small networks]

LibreQoS supports two first-class operating modes.

Built-in Integrations (Recommended for Most Operators)

In this mode, your CRM/NMS is the source of truth and LibreQoS integration jobs produce shaping inputs.

Key behavior:

ShapedDevices.csv is regenerated by integration sync cycles.
network.json overwrite behavior depends on integration settings (for example always_overwrite_network_json).
Direct manual edits may be overwritten on the next scheduler refresh.

Custom Source of Truth

In this mode, your own scripts/systems generate network.json and ShapedDevices.csv.

Key behavior:

Your external workflow owns persistence.
WebUI edits are valid for quick operational changes.
Permanent changes should be made in your external source of truth workflow.

Mode Declaration Checklist (Before Go-Live)

Pick one primary source of truth.
Confirm which system can write production shaping inputs.
Confirm scheduler refresh behavior and overwrite cadence.
Document your hotfix workflow (WebUI, external editor, or both).
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 own shaping inputs.
If you need strict custom topology behavior not represented by integration output, use custom source of truth mode and keep ownership explicit.

See:

If you are running built-in integrations, continue to CRM/NMS Integrations.