You are reading the documentation for v1.3.0. The current release is v1.4.0.

QuantumBNG 1.3.0 — Release Notes

Release notes for the QuantumTouch BNG appliance and console, combined with the
Quantum BNG controller's own v1.3.0 notes. Controller-layer items are marked
[controller]; everything else is the QuantumTouch console, installer and
evaluation appliance.

Overview

Onboarding that scales, and the console surfaces to drive it.

The controller's serial punt→DHCP bottleneck is gone and the run-over-run
throughput decay that used to require a systemctl restart is fixed, so
back-to-back high-count runs hold their rate. Churn no longer over-drains live
sessions.

On top of that, bulk subscriber provisioning and out-of-contract DSCP
marking
gained console pages, RADIUS exchanges became a source on the audit
timeline, and the appliance gained a Grafana dashboard pack installable in
one click.

Two further capabilities are staged rather than delivered in this release.
Capacity licensing and local CDR / usage records both have their console
surfaces in place and their controller-side plumbing landing, but neither is
ready to operate in 1.3.0 — they complete in 1.4.0. They are described under
Staged for 1.4.0 below rather than among the new features, so nobody plans
around them this cycle.

Component versions

Component 1.2.0 shipped 1.3.0 ships
Quantum BNG controller v1.2.0 v1.3.0
quantum_core v1.4.0 v1.5.0
quantumtouch-bng (console plugin) 0.9.x 0.10.31
quantumtouch-core 0.10.x 0.10.16
CPESIM plugin v0.3.7 v0.4.16
VPP 25.10 25.10.0-23
Installer bundle 1.2.0-63 1.3.0-13

Ubuntu 24.04 (Noble), x86_64. The evaluation appliance ships GA kernel 6.8
deliberately — see Known issues.


New features

Onboarding scale and throughput [controller] (#11, #27)

  • Punt→DHCP processing is no longer strictly serial. Punts are fast-consumed,
    deduplicated by subscriber identity and applied in batched session adds, so
    completion no longer collapses as the concurrent-request rate rises.
  • Onboarding throughput no longer degrades cumulatively under heavy load, and
    no longer needs a restart to recover.

Measured. Against a 900/s requested in-rush, the box completes the cold
phase at ~600 subscribers/s (run 670: 605.65/s cold, 491.8/s warm; runs
663/665/669/670 average ~610/s cold), with limited_by: none — neither the
BNG nor the load generator saturated at that rate. Earlier in the cycle the
same suite could only request 220/s; the generator-side work in CPESIM 0.4.16
is what made a rate this high askable, and the box answered it.

Bulk local-AAA provisioning [controller + console] (#26)

Gated-mode admission previously required one PUT per subscriber line, which
serialised through the controller and collapsed provisioning throughput at
scale. A bulk endpoint loads many lines in one atomic call.

The console's bulk subscriber import was rewritten onto that atomic endpoint,
with batched subscriber and session reads and an all-or-nothing result
state
— a partial import no longer leaves the operator guessing which rows
landed. The per-row console path cost three controller round-trips per
subscriber (a record GET, a full session-list GET, and the record PUT), which
is what held CSV import to ~2/s before this change.

Captive-portal URL via DHCP Option 114 [controller] (#25)

The DHCP OFFER/ACK path emits Option 114 (RFC 7710 / 8910) carrying the
captive-portal metadata URL, so iOS 12+, Android 10+, macOS 10.13+ and
Windows 10 2004+ natively detect the captive network and open the sign-in flow.
No DNS-interception fallback required.

Out-of-contract DSCP marking [controller + console] (#19)

The per-subscriber trTCM policer DSCP-marks yellow (out-of-contract) traffic as
AF11 on both upstream and downstream paths, so downstream devices can
differentiate in- from out-of-contract packets. Previously yellow was counted
but forwarded byte-identical to green; green/red behaviour is unchanged (red
still dropped). The console gained a DSCP marking policy section on the
Dataplane page
to set it, and the dashboard's QoS panel captions the
active marking state.

RADIUS diagnostics on the audit timeline

radius-exchanges joins qt-events as a source on the audit timeline:
decoded, linted RADIUS exchanges shown beside everything else that happened on
the box, so a failing subscriber authentication can be read without leaving the
console or running tcpdump by hand.

Off by default, and opt-in. When enabled, the box elects a single capture
owner so four gunicorn workers cannot start four dumpcap children over one
ring buffer, and every path where a capture was requested but could not be
started publishes that fact rather than showing an empty feed. With capture
off, the timeline's "no tap" clause is a true statement rather than an absence
of evidence.

RADIUS shared secrets are read for verification and never emitted — the
timeline distinguishes thirteen secret states without printing one.

Prometheus read proxy

A same-origin read proxy for Prometheus with a default-deny allowlist,
registered on /api/bng and forwarding allowlisted reads unwrapped. This is
what lets a Grafana instance query the box without handing it broad access, and
it pairs with the scoped metrics-only API key preset below.

Grafana dashboard pack

A curated BNG dashboard pack, installable in one click from About → Toybox,
with a multi-select download. Platform Health reads the host rather than a
metric that never populated, and host sections sort above the fold.

Supporting work: a Prometheus read proxy with a default-deny allowlist, and
a Grafana/metrics-only API key preset with a 365-day default expiry and a
visible path_scope, so a dashboard key is visibly scoped to what it can read.

Observability

IPMI chassis sensors are exported to Prometheus, and Prometheus alerting rules
ship wired into rule_files.


Staged for 1.4.0

Both of these have shipped code in 1.3.0 and neither is ready to use. They are
here because the controller-side work landed this cycle and we would rather stage
the console against it now than build it all in one jump later — but treat them
as groundwork, not capability.

Capacity-tier session licensing

[controller] The controller gained capacity licensing in v1.3.0. The free
tier is capped at 1,000 concurrent sessions; a signed capacity licence raises the
cap to a per-customer limit and applies immediately on activation. Licensing
gates capacity only, never function — a missing, expired or tampered licence
reverts to the free-tier cap rather than blocking operation. GET /bng/health
sessions.max reflects the active cap. Activation requires a TPM 2.0 device;
the free tier requires neither a licence nor a TPM.

Activation is done on the box with quantum-license-fingerprint,
quantum-license-install and quantum-license-status.

[console] A Licensing page exists and shows the capacity in force. It cannot
yet operate activation — see Known issues. The evaluation appliance ships a
vTPM (state stripped at export, so each import seeds its own identity) so the
flow can be exercised there once the console side completes.

Nothing here changes what a 1.3.0 box does. Without a licence — which is
every box today — the free tier applies exactly as before.

Local CDR / usage records

[controller] Durable per-subscriber usage records, the local-AAA analogue of
RADIUS accounting, persisted on the box for operators who bill by usage.

[console] A Usage Records page lists them with CSV download and an
Acknowledge & prune action that permanently removes what it consumes —
download before acknowledging.

Marked a preview: records are held, downloadable and prunable, but RADIUS
accounting is not enabled in this release, so they are not produced from live
subscriber traffic. Full accounting arrives in 1.4.0.

Evaluation appliance

The build account is gone. Previous appliances — including the published
v1.2.0-63 — shipped the Vagrant build account: user vagrant with the
well-known default password, passwordless sudo, and sshd accepting password
authentication on a forwarded port. That is remote root on any reachable
appliance, guessable without ever downloading the image. The account, its
sudoers grants and the build host keys are now removed before export, SSH
password authentication is off, and each appliance regenerates its own host
keys on first boot.

Console access is preserved: a random root password is generated per build
and recorded in /root/QUICKSTART.md beside the web credentials. It is a
console credential — it will not work over SSH.

Other appliance changes:

  • The Vagrant shared folder is no longer exported. It pointed at the build
    machine's directory, so VirtualBox reported invalid storage on import and the
    OVA leaked the builder's filesystem layout.
  • The documented 8 GiB minimum is now actually reachable. Preflight
    floor-divided MemTotal, which excludes firmware reservation, so a genuine
    8 GiB box read as 7 GiB and was refused — on real hardware, not just in a VM.
    It rounds to the nearest GiB now.
  • Hugepages are sized to the box. The installer reserved a flat 8 GiB
    regardless of RAM, which on an 8 GiB box is the entire machine. The budget is
    tiered (8192 MiB at ≥12 GiB, 2048 MiB at ≥6 GiB, 1024 MiB below), so boxes at
    or above 12 GiB — the perf rig and every production target — are unchanged.
  • The intermittent first-boot hang is fixed. Roughly 1 first boot in 6-10
    after import never reached the web console, stalling in
    systemd-tmpfiles-setup-dev-early with a (no limit) job timer. It was
    present in v1.2.0-63 at the same rate, so it is not new in this release, and
    a power cycle always recovered it — but a first impression should not need
    one. The cause is a stalled expedited RCU grace period:
    synchronize_rcu_expedited() signals every CPU and waits for each to
    acknowledge, and under VirtualBox one vCPU intermittently never does, so
    every caller blocks indefinitely. The appliance now boots with
    rcupdate.rcu_normal=1, which uses ordinary grace periods and removes that
    dependency. Measured with a repeated fresh-import harness at 8 GiB: 75
    consecutive clean boots
    (30 at 4 vCPU, 30 on the shortcut test image, 15 at
    the shipped 3 vCPU), against 2 failures in 15 on the previous build. Every
    boot came up in 7-8 seconds.
  • The appliance ships 3 vCPU / 8 GiB — the fewest that satisfies the
    CPU-pinning rules (core 0 Linux housekeeping, core 1 VPP main, core 2 VPP
    worker). The single worker runs at ~15% of vector capacity while sustaining
    ~1 Gbps through the appliance's veth pair for the first time.
  • The appliance's virtual disk advertises 64 GiB but occupies ~4.3 GiB.
    It is dynamically allocated: VirtualBox writes blocks on demand and does not
    pre-check the host against the advertised size, so you do not need 64 GiB
    free to import or run it
    . Verified by importing and booting this appliance
    on a 9.8 GiB volume — it used 4.3 GiB and left 5.5 GiB free. Budget roughly
    7 GiB in total: 2.1 GiB for the download plus ~4.3 GiB for the imported VM.
    The guest's root filesystem is 31 GiB, so the file can grow toward that under
    heavy use; on a tight volume leave headroom, since a full host pauses the VM
    with a disk-full error. (Earlier notes said 20 GiB, which was never what
    shipped.)
  • CPESIM v0.4.16: struct-packed DHCP relay frames (36× on the rig, 17.2×
    measured on the appliance, byte-identical to the previous output), each frame
    parsed once instead of twice, a tick_hz throttle that had been declared and
    never referenced while costing 76% of the onboard loop, and QoS scoring that
    no longer counts subscribers which produced no measurement.

Bug fixes

Controller

  • Churn no longer over-drains live sessions (#24). Session reconciliation
    matches on subscriber identity rather than MAC only, so a subscriber that
    reconnects during churn keeps its live session. (A v1.2.0 known issue, now
    resolved.)
  • Idle sessions are no longer reaped prematurely. Idle detection
    establishes a counter baseline on a session's first interim before accruing
    idle time, so a session survives its full configured idle_timeout.
  • Reset fully clears the dataplane session table, so no stale entry
    survives to collide with a re-added framed IP (previously
    BngSessionAdd refused retval=-81).

Console and installer

  • The status banner counted recovered events as active. A freshly imported
    appliance read "Fault — 1 active event (1 critical)" for a boot-time
    watchdog blip that had already self-recovered, because the events feed keeps
    recovered entries until acknowledged and the banner counted the whole feed.
  • The setup wizard's Data Plane step reported success for work it had not
    done.
    It recorded the interface choice and returned OK; it now queries the
    controller and says plainly when nothing is wired and what the consequence is.
  • The wizard's Apply destroyed installer GRUB state. Two owners write two
    different GRUB variables; Apply blanked the installer's.
  • API keys: Revoke now actually revokes a bearer key, revocations made
    before the disabled fix are enforced, a rotate can no longer mint a secret
    nobody sees, key writes no longer discard the document, and the Grafana
    preset is minted into the realm it has to authenticate in.
  • Controller proxy: percent-encoded path segments are forwarded intact
    rather than being decoded and re-sent.

Known issues

  • Controller session view sheds ~10% of sessions under churn
    (bng#36). Clients stay
    bound and traffic keeps flowing; the controller's view loses sessions and
    recovers them only on re-DORA. Under test this shows as a lease-churn
    continuity failure. Open at time of release; a fix is targeted for the next
    cycle.

  • The Licensing page cannot read licence status or the machine fingerprint.
    The console addressed the controller's licence routes without their /v1
    prefix, so the calls returned 404. This is staging work for 1.4.0 rather than a
    capability anyone should be using in 1.3.0 (see Staged for 1.4.0), and the
    free tier — every box today — is unaffected. Activation, if you need it now, is
    fully supported from the command line with quantum-license-fingerprint,
    quantum-license-install and quantum-license-status. Fixed in 1.4.0.

  • The controller's production RADIUS client is not yet shipped. Standalone
    deployments use local AAA and need no RADIUS server. RADIUS diagnostics
    (capture, decode, lint, timeline) do ship in this release and work against
    any RADIUS traffic the box sees — what is outstanding is the controller-side
    client for auth, accounting and CoA. The conformance work below is the
    specification and proof harness that release will be measured against.

  • sessions.max / sessions.at_cap require the plugin and vpp_bridge
    built with this release. Against an older dataplane those fields are omitted
    and /bng/health degrades gracefully.

  • CPESIM plugin upgrades require a BNG release. The plugin version is
    pinned in the product, so a newer CPESIM is not picked up by an existing
    appliance. Lifecycle management — update checking, in-place upgrade and
    rollback for the BNG and its plugins — is targeted for 1.4.0.

  • The evaluation appliance ships GA kernel 6.8, not HWE. The HWE
    metapackage pulls a kernel that hangs in early boot under VirtualBox at
    ≥6 vCPUs. GA 6.8 supports every feature the BNG needs, and with
    rcupdate.rcu_normal=1 (see Evaluation appliance above) it boots cleanly
    at the 3 and 4 vCPU counts this release was validated at.

Breaking changes

None. The freemium licensing fallback is strictly more permissive than a hard
gate, and the remaining changes are corrective.

The appliance's removal of the vagrant account is a deliberate behaviour
change for anyone who was using it to reach the box: use the console root
password in /root/QUICKSTART.md, or add your own key to
/root/.ssh/authorized_keys from the console.

Resolved issues

Closed under the controller's v1.3.0 milestone:

  • 11 — DHCP onboarding doesn't scale; completion collapses at high counts

  • 19 — trTCM YELLOW band not DSCP-marked (AF11)

  • 23 — local-AAA usage/billing export (local CDR)

  • 24 — controller over-drains subscriber sessions under churn

  • 25 — RFC 7710/8910 DHCP Option 114 (captive-portal URL) emission

  • 26 — bulk local-AAA provisioning API

  • 27 — onboarding throughput decays under load, recovers only on restart

Installation

Root permissions required.

tar xvzf quantumtouch-installer-1.3.0-13.tar.gz
cd quantumtouch-installer-1.3.0-13
sudo ./install.sh

The installer runs a preflight first and refuses to install on an unsuitable
box; QT_SKIP_PREFLIGHT=1 forces past it. Requirements: Ubuntu 24.04,
8 GiB RAM minimum (16 GiB recommended), 5 GiB free on /opt, Python 3.12+,
and no docker-ce (it conflicts with the docker.io the controller needs).

Evaluation appliance: import quantumtouch-bng-eval-v1.3.0-13.ova into
VirtualBox 7.0+ and start it, then open https://localhost:8443/. Credentials
are in /root/QUICKSTART.md on the appliance. Rotate the web password
immediately.