Network Tracking

QuickBox Pro uses vnStat to record per-interface network traffic. vnStat is the data source behind the bandwidth charts on the System Dashboard, the network throughput tiles in the metric strip, and the historical bandwidth graphs you can scrub through over time. It ships pre-installed and starts collecting on first boot.

This page describes the auto-heal layer that keeps vnStat’s tracked interface set aligned with your server’s actual network topology — automatically, without manual reconfiguration.

Key features

What auto-heal does for you

When your server’s network topology changes — adding a bond, creating a bridge for VM traffic, joining a team, removing an old VLAN — vnStat’s tracked interface list updates on its own:

1. The new aggregate interface is registered with vnStat so the bandwidth chart picks up data on the next collection cycle.
2. Stale entries — interfaces that no longer exist or have been superseded by an aggregate — are removed so they stop showing up empty in the dashboard.
3. The vnStat daemon is restarted once at the end of the pass to load the updated tracking set. No partial state, no double restarts.

The end result: the dashboard’s network charts keep working after topology changes without you having to touch a config file or remember a CLI invocation.

What triggers a re-tracking pass

Auto-heal listens on three independent signal sources so it works on every distro QuickBox Pro supports, regardless of which network management stack the host uses.

All three converge on the same one-shot service. systemd handles deduplication, so a single topology change that fires more than one trigger still produces one reconcile pass.

Coalescing and debouncing

When NetworkManager flaps during boot or during a network restart, several events can land within a few seconds. To prevent repeated reconcile passes, the systemd path-watcher unit caps how often it fires — a short stream of back-to-back events results in a single reconcile pass, not twenty. You won’t see your journal filled with reconcile noise during NIC churn.

Manual rebuild

There are situations where you might want to force a reconcile pass on demand — after hand-editing vnstat.conf, after rebuilding network configuration outside QuickBox, or while troubleshooting why an expected interface isn’t showing in the bandwidth chart.

You have two options:

1. Dashboard — From the System Dashboard, find the Network Stats panel and click Rebuild interfaces.
2. CLI — Run qb manage vnstat --rebuild directly on the server.

Both paths invoke the same reconciler. Output is logged to the system journal regardless of which path you used.

CLI subcommands

Example invocations:

# Reconcile tracked interfaces now
qb manage vnstat --rebuild
 
# Inspect the plan without applying anything
qb manage vnstat --dry-run
 
# Show the current detection + registration state
qb manage vnstat --status

Diagnostics — what’s in the journal

The reconciler logs every pass to the system journal under the unit name qbx-vnstat-reconcile.service. To inspect:

# Most recent reconcile activity
journalctl -u qbx-vnstat-reconcile.service -n 50
 
# Follow live as topology changes happen
journalctl -u qbx-vnstat-reconcile.service -f
 
# Everything since last boot
journalctl -u qbx-vnstat-reconcile.service -b

A healthy pass shows the detected preferred interface, the planned add/remove list, the applied actions, and a “reconcile complete” line. If no changes were needed because the tracking set already matches the topology, the unit logs an “in sync” line and exits cleanly.

Best practices

FAQ

Related pages