6. Common tasks & troubleshooting

"The demo says running but I have 0 connected subscribers"

This is the classic wedge — usually stale kernel state from an earlier aborted run that the defensive cleanup didn't catch. Recover from the UI:

On the Simulator page, click Reset simulator (top-right of the CPESIM header).
Wait ~10–15 seconds for the reset to complete — bng-demo stops, all demo* veths are cleaned up, the cpesim-subs netns is deleted, VPP + controller + bng-demo are restarted, and the engine confirms it's responding.
Click Start again — subscribers should onboard normally within 20–45 seconds.

No shell access required. If Reset fails for some reason (e.g. VPP is unreachable), the button surfaces the error text right underneath.

"Throughput reads 0 on the CPESIM page but the BNG dashboard shows traffic"

If you're on CPESIM ≤ v0.3.8 you'll see this — the older CPESIM read throughput from an internal counter that undercounted during subscriber churn. Upgrade to v0.3.9 (bundled with QuantumBNG v1.2.0-21+).

Fixed in QuantumBNG v1.2.0-17. The old Toybox poller used fetchWithAuth, which treats any 401 (including transient ones during a busy install) as a session failure and redirects. Upgrading fixes it.

"Install downloaded an older CPESIM version than I expected"

The About-page Install button uses the version pinned in the currently-installed wrapper (CPESIM_VERSION in cpesim_module.py). To install a newer plugin than the wrapper pins, either upgrade the wrapper OR pass an explicit URL:

sudo /opt/bng-deploy/venv/bin/python -c "
from quantumtouch_bng.helpers.cpesim_module import CpesimModule
CpesimModule().install({'url': 'https://github.com/Bluedot-Insight/cpesim/releases/download/vX.Y.Z/cpesim_vX.Y.Z.tar.gz'})
"

"I don't see the Simulator page in the nav"

Two possibilities: the plugin isn't installed (check About → Toybox), or the browser has a stale capability cache. Hard-refresh (Cmd+Shift+R / Ctrl+F5) and it should appear.

"The `trickle re-dora: [Errno 9] Bad file descriptor` error is showing on last_error"

Cosmetic and only appears on CPESIM ≤ v0.3.7. It's a benign shutdown-race warning (the trickle thread races the transport socket close during Stop). Suppressed in v0.3.8+.

"I need to see what CPESIM is actually doing at the wire level"

# What's in the sub-side netns?
sudo ip netns exec cpesim-subs ip addr show demo0

# TCP sockets each sub has open
sudo ip netns exec cpesim-subs ss -tan

# VPP counters (what the BNG dashboard sees)
sudo vppctl show interface host-demo0p host-demo-upp

# Live journal
sudo journalctl -u bng-demo -f

"I need to remove CPESIM entirely"

From the UI: About → Toybox → Remove on the CPESIM card. Under the hood this calls /demo/stop to release sessions and tear down the data path, then systemctl disable --now bng-demo and removes /opt/bng-demo. The nav's Simulator entry disappears within a few seconds.