A LAG no longer hashes traffic onto a member whose link is down (#1263) #1264

Merged
jaylouisw merged 1 commit from fix/lag-member-link-state into main 2026-11-09 20:02:38 +00:00
Owner

A LAG no longer hashes traffic onto a member whose link is down

Fixes #1263.

Group  Protocol   Ports
1      active     Fa0/2(P) Fa0/3(D)
  Fa0/3     not bundled (down: link down)
  bundle 1 is running on 1 of 2 members: Fa0/2

The bug

Two switches joined by a two-member port-channel. Both cables in: pings cross. One cable out: every ping
fails.

both links up      true,true,true,true
one member down    false,false,false,false,false,false
lag picks after:   ["Fa0/3","Fa0/3","Fa0/3","Fa0/3","Fa0/3","Fa0/3"]     <- the dead member, every time

selectMember() filtered on enabled and nothing else, and the forwarding path's candidate list filtered
spanning tree and VLAN membership and nothing else — so the hash kept landing on the unplugged member while
Fa0/2, up and idle, carried nothing. And show etherchannel summary called both members (P), i.e. "this
port is carrying traffic", for a port whose link was down.

A bundle exists to survive losing a member. Here, losing one cost whatever hashed to it, and the only clue
was a drop count on a port that still looked bundled.

Now

  • selectMember(members, frame, policy, { canCarry }) takes an operational predicate — a predicate
    rather than a flag, so engine/lag.js stays free of topology while every caller still has to answer the
    same question;
  • the simulator answers it with Device.ifaceStatus(iface, topo) — the one rule show interfaces,
    show arp and the canvas already use — so a pulled cable, a down link, a shut far port, an
    administratively-down port and an STP-blocked port are excluded the same way, in the same words;
  • eligibleMembers() is exported so the CLI and the data plane cannot hold two opinions about a bundle;
  • the hash is taken over eligible members only, so the bundle keeps working. With nothing wrong the pick is
    byte-for-byte what it was
    , so flows do not re-balance on an unrelated change;
  • when no member can carry, one is still picked so the frame is attempted and dropped with a reason — the
    loss stays countable (#1258) rather than vanishing into a bundle that looks healthy;
  • show etherchannel summary marks (P) only for members that can carry, (D) otherwise, prints why in the
    same sentence show interfaces uses, and reports the bundle's live member count or that it is down;
  • the lag timeline event records live, degraded and noLiveMember, so a viewer does not have to diff
    two arrays to see why a member was skipped.

Evidence

test/lag-member-down.test.js — 30 checks:

  • a healthy bundle is unchanged (both members (P), nothing called out) — the fix must not re-balance
    working flows;
  • with one cable down, every ping is still answered and no frame is hashed onto the dead member;
  • a locally shut member reads (administratively down); a shut far port reads peer shut down — the same
    fault seen from the other end says a different thing, correctly;
  • with both members down the bundle reports itself down and the drops are counted with a reason;
  • the rule itself: pick independent of config order, null when nothing can carry, enabled still honoured,
    eligibleMembers dedupes and sorts;
  • the lag event records members, live, degraded, noLiveMember.

Reverting engine/simulator.js fails 5; engine/cli.js fails 9; engine/lag.js fails the suite outright.

docs/CLI.md gains "Reading show etherchannel summary" and the command in the table.

Suite: 145 suites, 6,194 assertions, 0 failed.

A LAG no longer hashes traffic onto a member whose link is down Fixes #1263. ``` Group Protocol Ports 1 active Fa0/2(P) Fa0/3(D) Fa0/3 not bundled (down: link down) bundle 1 is running on 1 of 2 members: Fa0/2 ``` ## The bug Two switches joined by a two-member port-channel. Both cables in: pings cross. **One cable out: every ping fails.** ``` both links up true,true,true,true one member down false,false,false,false,false,false lag picks after: ["Fa0/3","Fa0/3","Fa0/3","Fa0/3","Fa0/3","Fa0/3"] <- the dead member, every time ``` `selectMember()` filtered on `enabled` and nothing else, and the forwarding path's candidate list filtered spanning tree and VLAN membership and nothing else — so the hash kept landing on the unplugged member while `Fa0/2`, up and idle, carried nothing. And `show etherchannel summary` called both members `(P)`, i.e. "this port is carrying traffic", for a port whose link was down. A bundle exists to survive losing a member. Here, losing one cost whatever hashed to it, and the only clue was a drop count on a port that still looked bundled. ## Now * `selectMember(members, frame, policy, { canCarry })` takes an **operational predicate** — a predicate rather than a flag, so `engine/lag.js` stays free of topology while every caller still has to answer the same question; * the simulator answers it with **`Device.ifaceStatus(iface, topo)`** — the one rule `show interfaces`, `show arp` and the canvas already use — so a pulled cable, a down link, a shut far port, an administratively-down port and an STP-blocked port are excluded the same way, in the same words; * `eligibleMembers()` is exported so the CLI and the data plane cannot hold two opinions about a bundle; * the hash is taken over eligible members only, so the bundle keeps working. **With nothing wrong the pick is byte-for-byte what it was**, so flows do not re-balance on an unrelated change; * when **no** member can carry, one is still picked so the frame is attempted and dropped with a reason — the loss stays countable (#1258) rather than vanishing into a bundle that looks healthy; * `show etherchannel summary` marks `(P)` only for members that can carry, `(D)` otherwise, prints why in the same sentence `show interfaces` uses, and reports the bundle's live member count or that it is down; * the `lag` timeline event records `live`, `degraded` and `noLiveMember`, so a viewer does not have to diff two arrays to see why a member was skipped. ## Evidence `test/lag-member-down.test.js` — 30 checks: * a **healthy bundle is unchanged** (both members `(P)`, nothing called out) — the fix must not re-balance working flows; * with one cable down, **every ping is still answered** and no frame is hashed onto the dead member; * a locally shut member reads `(administratively down)`; a shut *far* port reads `peer shut down` — the same fault seen from the other end says a different thing, correctly; * with both members down the bundle reports itself down and the drops are counted with a reason; * the rule itself: pick independent of config order, `null` when nothing can carry, `enabled` still honoured, `eligibleMembers` dedupes and sorts; * the `lag` event records `members`, `live`, `degraded`, `noLiveMember`. Reverting `engine/simulator.js` fails 5; `engine/cli.js` fails 9; `engine/lag.js` fails the suite outright. `docs/CLI.md` gains "Reading `show etherchannel summary`" and the command in the table. Suite: 145 suites, 6,194 assertions, 0 failed.
A LAG no longer hashes traffic onto a member whose link is down (#1263)
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 14s
CI / Test (Node 20) (pull_request) Successful in 1m56s
CI / Test (Node 18) (pull_request) Successful in 2m0s
CI / Server smoke test (pull_request) Successful in 33s
CI / Docker build (pull_request) Successful in 41s
CI / Test (Node 22) (pull_request) Successful in 1m43s
d86f805dd3
Two switches joined by a two-member port-channel: with both cables in, pings cross; take one cable out and
every ping fails, because the hash kept landing on the unplugged member while the surviving member sat idle.

  both links up      true,true,true,true
  one member down    false,false,false,false,false,false   picks: Fa0/3 every time

`selectMember()` filtered on `enabled` and nothing else, and the forwarding path's candidate list filtered
spanning tree and VLAN membership and nothing else. `show etherchannel summary` reported both members (P)
throughout - "this port is carrying traffic" - for a port whose link was down.

Now:
* `selectMember(members, frame, policy, { canCarry })` takes an operational predicate. It is a predicate
  rather than a flag so engine/lag.js stays free of topology while every caller still has to answer the same
  question;
* the simulator answers it with `Device.ifaceStatus(iface, topo)` - the one rule `show interfaces`,
  `show arp` and the canvas already use - so a pulled cable, a down link, a shut far port, an
  administratively down port and an STP-blocked port are all excluded the same way;
* `eligibleMembers()` is exported so the CLI and the data plane cannot hold two opinions about a bundle;
* the hash is taken over eligible members only, so the bundle keeps working; with nothing wrong the pick is
  byte-for-byte what it was, so flows do not re-balance on an unrelated change;
* when no member can carry, one is still picked so the frame is attempted and dropped with a reason - the
  loss stays countable (#1258) instead of vanishing into a bundle that looks healthy;
* `show etherchannel summary` marks (P) only for members that can carry, (D) otherwise, prints why in the
  same sentence show interfaces uses (`not bundled (down: link down)`, `(administratively down)`,
  `(STP blocking)`), and reports `bundle 1 is running on 1 of 2 members: Fa0/2` or
  `bundle 1 is down: no member can carry a frame`;
* the lag timeline event records `live`, `degraded` and `noLiveMember`, so a viewer does not have to diff
  two arrays to see why a member was skipped.

test/lag-member-down.test.js (30 checks): a healthy bundle is unchanged and both members read (P); with one
cable down every ping is still answered and no frame is hashed onto the dead member; a shut member and a shut
far port are named differently; with no live member the bundle is reported down and the drops are counted
with a reason; the pick does not depend on config order, returns null when nothing can carry, honours
`enabled`, and `eligibleMembers` dedupes and sorts; and the lag event records what could carry. Reverting
engine/simulator.js fails 5, engine/cli.js fails 9, engine/lag.js fails the suite outright.

Suite: 145 suites, 6,194 assertions, 0 failed.
jaylouisw scheduled this pull request to auto merge when all checks succeed 2026-11-09 20:02:35 +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!1264
No description provided.