StormGuard

StormGuard is LibreQoS' adaptive queue-adjustment subsystem for congestion and quality events.

Important Scope Warning StormGuard is intended for specific use cases, such as controlling congestion on variable-bandwidth WAN links (for example maritime networks), or a small number of access points with highly variable capacity. It is not intended to manage dozens or hundreds of nodes at the same time.

What StormGuard Does

Monitors real-time signals (throughput, RTT/loss-related metrics, and saturation context).
Applies bounded adjustments to configured node limits to protect quality under stress.
Exposes status/debug data in the WebUI (Node Manager).

StormGuard adaptive site-speed changes are stored in the StormGuard override layer. They are not written back into network.json.

Configuration

StormGuard is configured in /etc/lqos.conf under [stormguard].

Common keys:

enabled: turns StormGuard on/off.
dry_run: calculate decisions without applying live queue changes.
targets: list of top-level node names to manage.
minimum_download_percentage: minimum floor ratio for download limits.
minimum_upload_percentage: minimum floor ratio for upload limits.
log_file: optional CSV output path for decision/change telemetry.

Example:

[stormguard]
enabled = true
dry_run = true
log_file = "/var/log/stormguard.csv"
targets = ["SITE_A", "SITE_B"]
minimum_download_percentage = 0.5
minimum_upload_percentage = 0.5

If you are testing, start with dry_run = true so you can observe decisions before allowing live limit changes.

UI and Debugging

WebUI provides a dedicated StormGuard dashboard tab plus status and debug views.
The StormGuard dashboard tab is intended to answer "what is StormGuard doing right now?" with:
- summary cards for watched, cooling-down, and recently changed sites
- a site list that works for single-site and multi-site watched sets
- a selected-site detail panel explaining current limits, last actions, and why StormGuard is holding or changing rates
- a recent activity feed for quick operator triage
The StormGuard debug page shows:
- current effective limits
- evaluation metrics
- rule/decision context

Use this during rollout validation.

Safe Rollout Pattern

Enable StormGuard with dry_run = true.
Observe behavior for multiple peak periods.
Validate there are no undesirable limit oscillations.
Switch dry_run = false.
Continue monitoring after each major topology/integration change.

Troubleshooting

If StormGuard behavior seems incorrect:

sudo systemctl status lqosd lqos_scheduler
journalctl -u lqosd --since "30 minutes ago"

Also verify:

target node names still match your current network.json hierarchy
integration updates have not renamed key nodes/APs
your minimum percentage floors are reasonable for expected traffic profiles
network.json still reflects your planned/source-of-truth site rates if you are investigating an unexpected StormGuard reduction
log_file path (if configured) is writable by the service user

3.3 KiB Raw Blame History