TreeGuard (Upcoming v2.0 Feature)

TreeGuard is an upcoming LibreQoS v2.0 feature for intelligent node management.

Important status:

TreeGuard is upcoming.
TreeGuard is not enabled by default.
Current defaults remain unchanged unless an operator explicitly enables TreeGuard.

What TreeGuard Does

TreeGuard has two control domains:

Link/node virtualization management (for selected nodes).
Per-circuit SQM switching between cake and fq_codel.

For circuits, TreeGuard can make per-direction decisions (download and upload independently).

Default Behavior Without TreeGuard

When TreeGuard is not enabled, LibreQoS behavior stays with configured/default SQM policy (commonly cake diffserv4, with operator overrides where configured).

TreeGuard does not affect traffic unless enabled.

Circuit SQM Switching Model (When Enabled)

TreeGuard evaluates utilization, RTT freshness, CPU guardrails, and optional QoO guardrails.

High-level behavior:

For sustained low-load conditions, TreeGuard may switch a direction from cake to fq_codel.
If utilization rises, RTT/QoO guardrails are unsafe, or revert conditions are met, TreeGuard switches back to cake.
Decisions can be independent per direction when independent_directions = true.

This gives a dynamic profile where loaded directions favor cake diffserv4, while low-load directions can use fq_codel when conditions are safe.

Configuration (`/etc/lqos.conf`)

TreeGuard config lives under [treeguard] and sub-sections:

[treeguard]: enable/disable, dry-run, tick cadence.
[treeguard.cpu]: CPU-aware vs traffic/RTT mode and thresholds.
[treeguard.links]: node virtualization enrollment and guardrails.
[treeguard.circuits]: circuit enrollment and SQM switching guardrails.
[treeguard.qoo]: optional QoO protection threshold.

From PR #946 defaults:

[treeguard]
enabled = false
dry_run = true
tick_seconds = 1

[treeguard.circuits]
enabled = true
switching_enabled = true
independent_directions = true
idle_util_pct = 2.0
idle_min_minutes = 15
rtt_missing_seconds = 120
upgrade_util_pct = 5.0
min_switch_dwell_minutes = 30
max_switches_per_hour = 4
persist_sqm_overrides = true

Safe Rollout Pattern

Keep enabled = false until you have reviewed policy and enrollment lists.
Start with enabled = true and dry_run = true.
Use a small allowlist of nodes/circuits first.
Validate behavior over multiple peak/off-peak windows.
Only then set dry_run = false.

Overrides and Operational Notes

When enabled and not dry-run, TreeGuard may persist decisions to:

lqos_overrides.treeguard.json

TreeGuard is designed to avoid fighting operator-owned overrides. If operator overrides exist for enrolled entities, TreeGuard skips those entities and reports warnings.

3.1 KiB Raw Blame History