A port moved to another VLAN keeps its MAC entries; stale rows read as live (#1255) #1256

Merged
jaylouisw merged 1 commit from fix/mac-table-vlan-flush into main 2026-11-09 19:20:08 +00:00
Owner

A port moved to another VLAN keeps its MAC entries; stale rows read as live

Fixes #1255.

SW1#show mac address-table
Vlan    Mac Address         Type        Ports
1       02:00:00:00:01:00   DYNAMIC     Fa0/1
1       02:00:00:00:02:00   DYNAMIC     Fa0/2 (administratively down)
20      02:00:00:00:09:00   DYNAMIC     Fa0/1 (vlan mismatch)

Before this change, moving Fa0/2 to VLAN 20 left its VLAN-1 entry in place indefinitely — a VLAN-1 entry
on a port that carries VLAN 20, which is not a forwarding decision any switch could make. Entries here are
learned and overwritten, never aged out, and a membership change did not touch them.

Checked first: it is not a leak

The dangerous version of this bug is a frame from VLAN 1 being forwarded into a port that is now VLAN 20.
Measured before touching anything: the switch drops with no egress ports in VLAN 1, and the only frame the
moved host receives is the switch's own LLDP. VLAN isolation holds. This is a table that lies, not a
flood that escapes — worth stating, because the fix would have been very different.

Now

  • Device.flushMacsOnPort(name) drops one port's entries across every VLAN and reports how many it dropped;
  • every membership command calls it — switchport access vlan, switchport mode,
    switchport trunk native vlan, switchport trunk allowed vlan, no switchport / reset — so a membership
    command added later inherits the same rule by calling the helper;
  • show mac address-table marks what the model still cannot know:
    • a port that cannot carry a frame gets the reason, from the same helper show arp uses, so the two
      tables cannot describe one port state two ways;
    • a port that does not carry the entry's VLAN gets (vlan mismatch);
    • a port that no longer exists gets (name: gone) instead of printing nothing;
  • shutting a port does not flush: real switches age entries out, and the mark is what says the row is
    stale — the same decision show arp made;
  • header and rows are built from one set of widths, so Ports sits under the header that names it.

Evidence

test/mac-table.test.js — 21 checks:

  • both hosts listed, four columns each, on the ports they were heard on;
  • a VLAN move leaves nothing claiming the old VLAN on the moved port, while the other port keeps its
    entry — and a flush on one port leaves another port's entries alone, including in another VLAN;
  • a shut port keeps its rows and marks them, without repeating "shut down" after "administratively down";
  • (vlan mismatch) for an entry in a VLAN its port does not carry, and (gone) for a removed port;
  • a trunk's own VLANs are never marked (the marking must not cry wolf on healthy trunks);
  • flushMacsOnPort reports what it dropped, and is idempotent.

Reverting engine/cli.js fails 5 of the 21; reverting engine/device.js fails 2.

docs/CLI.md gains a "Reading show mac address-table" section.

Suite: 141 suites, 6,042 assertions, 0 failed.

A port moved to another VLAN keeps its MAC entries; stale rows read as live Fixes #1255. ``` SW1#show mac address-table Vlan Mac Address Type Ports 1 02:00:00:00:01:00 DYNAMIC Fa0/1 1 02:00:00:00:02:00 DYNAMIC Fa0/2 (administratively down) 20 02:00:00:00:09:00 DYNAMIC Fa0/1 (vlan mismatch) ``` Before this change, moving `Fa0/2` to VLAN 20 left its VLAN-1 entry in place indefinitely — a VLAN-1 entry on a port that carries VLAN 20, which is not a forwarding decision any switch could make. Entries here are learned and overwritten, never aged out, and a membership change did not touch them. ## Checked first: it is not a leak The dangerous version of this bug is a frame from VLAN 1 being forwarded into a port that is now VLAN 20. Measured before touching anything: the switch drops with `no egress ports in VLAN 1`, and the only frame the moved host receives is the switch's own LLDP. **VLAN isolation holds.** This is a table that lies, not a flood that escapes — worth stating, because the fix would have been very different. ## Now * `Device.flushMacsOnPort(name)` drops one port's entries across every VLAN and reports how many it dropped; * every membership command calls it — `switchport access vlan`, `switchport mode`, `switchport trunk native vlan`, `switchport trunk allowed vlan`, `no switchport` / reset — so a membership command added later inherits the same rule by calling the helper; * `show mac address-table` marks what the model still cannot know: * a port that cannot carry a frame gets the reason, from the **same helper `show arp` uses**, so the two tables cannot describe one port state two ways; * a port that does not carry the entry's VLAN gets `(vlan mismatch)`; * a port that no longer exists gets `(name: gone)` instead of printing nothing; * shutting a port does **not** flush: real switches age entries out, and the mark is what says the row is stale — the same decision `show arp` made; * header and rows are built from one set of widths, so `Ports` sits under the header that names it. ## Evidence `test/mac-table.test.js` — 21 checks: * both hosts listed, four columns each, on the ports they were heard on; * a VLAN move leaves **nothing** claiming the old VLAN on the moved port, while the other port keeps its entry — and a flush on one port leaves another port's entries alone, including in another VLAN; * a shut port keeps its rows and marks them, without repeating "shut down" after "administratively down"; * `(vlan mismatch)` for an entry in a VLAN its port does not carry, and `(gone)` for a removed port; * a trunk's own VLANs are **never** marked (the marking must not cry wolf on healthy trunks); * `flushMacsOnPort` reports what it dropped, and is idempotent. Reverting `engine/cli.js` fails 5 of the 21; reverting `engine/device.js` fails 2. `docs/CLI.md` gains a "Reading `show mac address-table`" section. Suite: 141 suites, 6,042 assertions, 0 failed.
A port moved to another VLAN keeps its MAC entries; stale rows read as live (#1255)
All checks were successful
CI / Classify the change (pull_request) Successful in 12s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Test (Node 20) (pull_request) Successful in 1m48s
CI / Test (Node 18) (pull_request) Successful in 1m53s
CI / Server smoke test (pull_request) Successful in 34s
CI / Docker build (pull_request) Successful in 43s
CI / Test (Node 22) (pull_request) Successful in 1m44s
b343a04ae0
Moving a port from VLAN 1 to VLAN 20 left every MAC learned there still listed as VLAN 1:

  Vlan    Mac Address         Type        Ports
  1       02:00:00:00:02:00   DYNAMIC     Fa0/2      <- Fa0/2 is access VLAN 20 now

A VLAN-1 entry on a port that carries VLAN 20 is not a forwarding decision any switch could make, and
nothing here removes it: entries are learned and overwritten, never aged, and a membership change did not
touch them. Chasing the dangerous version of this first (does the stale entry leak a frame across VLANs?)
measured no leak - the switch drops with "no egress ports in VLAN 1" - so this is a table that lies rather
than a flood that escapes.

Real switches flush a port's dynamic entries when its membership changes. Now:

* `Device.flushMacsOnPort(name)` drops one port's entries across every VLAN and reports how many;
* every membership command calls it: `switchport access vlan`, `switchport mode`,
  `switchport trunk native vlan`, `switchport trunk allowed vlan`, and `no switchport` / reset;
* `show mac address-table` marks what the model still cannot know: a port that cannot carry a frame gets the
  reason (same sentence `show arp` uses, from one shared helper), a port that does not carry the entry's
  VLAN gets `(vlan mismatch)`, and a port that no longer exists gets `(name: gone)`;
* shutting a port does NOT flush - real switches age entries out and the mark is what says the row is stale;
* the header and rows are built from one set of widths, so `Ports` sits where the header says it does.

test/mac-table.test.js (21 checks): both hosts listed with four columns each on the right port; a VLAN move
leaves nothing claiming the old VLAN on the moved port while the other port keeps its entry; a flush on one
port leaves another port's entries alone (including in another VLAN); a shut port keeps its rows and marks
them; `(vlan mismatch)` and `(gone)`; a trunk's own VLANs are never marked; and `flushMacsOnPort` reports
what it dropped. Reverting engine/cli.js fails 5, reverting engine/device.js fails 2.

docs/CLI.md gains "Reading `show mac address-table`".

Suite: 141 suites, 6,042 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 19:20:04 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1256
No description provided.