Run the audit suite end-to-end

l2trace ships seven independent audit commands. Each one surfaces a different family of L2/L3 misconfigurations from existing observation data. Running them in a single pass over a freshly-collected fabric is the highest-information operator workflow the tool supports — most of the bugs they catch are silent until someone looks.

When you need this

• “We just brought this fabric under l2trace. What’s already broken that we should know about?”
• “We had a weird incident last night. I want a pre-flight check across every signal we collect.”
• “Quarterly fabric review. I want a single page of findings, not seven separate runs.”

Prerequisites

• l2trace reconciler has been running long enough for collectors to populate the bitemporal log. About two SNMP poll cycles (default 120s) is the floor; longer for richer flap-detector evidence.
• At least one of: gNMI subscription, SNMP polling, or SSH/napalm configured on each device of interest. Three sources is better than one — the cross-source detectors light up only when ≥2 sources see the same device.

The sweep, in order

The order matters: cheap detectors first, layered detectors after. A topology problem flagged by audit-adjacencies often explains why a later detector behaves oddly, so it pays to triage upward.

1. Bidirectional LLDP — audit-adjacencies

The cheapest, most common detector. One side reports the peer, the other doesn’t.

l2trace audit-adjacencies

Empty output = every open LLDP row has a confirmed reverse. Anything in the table is one of:

Symbol	Meaning
✗ no reverse	Peer doesn’t see us at all — one-way cable, port down on the peer, or LLDP-TX disabled
△ source asym	Bidirectional via some source, but the named source only sees one direction (telemetry asymmetry, not cabling)

See Audit LLDP adjacencies for the full triage playbook.

2. Cross-source CAM mismatch — disagreements view

Two collectors seeing the same (mac, device, vlan) on different ports. This one runs from the TUI or via SQL — there’s no dedicated CLI yet:

psql -d l2trace -c "SELECT * FROM mac_observation_disagreement"

Or in the TUI: OPS screen, Disagreements pane. Common cause: stale SNMP poll racing live gNMI; once the SNMP poll catches up the row clears itself.

See Spot cross-source disagreements.

3. MAC flap — audit-flaps

MACs oscillating between ports faster than the switch’s aging timer.

l2trace audit-flaps                 # defaults: 300s window, 3+ ports
l2trace audit-flaps --window 60 --min-moves 2   # tighter for forensics

Real causes: switching loop, misconfigured server bond, active-active VRRP gone split-brain. A flagged row is the host MAC, the device hosting it, the number of distinct ports observed, and the time window of the activity.

4. Cross-VLAN MAC — audit-multi-vlan

Same MAC currently observed in 2+ VLANs.

l2trace audit-multi-vlan

The device_count column is the triage hint:

• 1 device, N vlans is usually a dot1q sub-interface on a server NIC — legitimate, just record it as known.
• N devices, N vlans is almost always a misconfiguration — 802.1Q double-tagging, an accidental L2 segment merge, or a trunk-port allowed-VLAN list with a typo.

5. STP × CAM cross-layer — audit-stp-cam

Ports marked STP-blocking that still have open CAM entries. Violates 802.1D §8.6 — blocked ports don’t learn MACs.

l2trace audit-stp-cam

Most common cause: stale CAM the compactor hasn’t aged out yet. Wait one aging-threshold worth, re-run, and it usually clears. Persistent flags after that point indicate a vendor FDB-learning bug (some IOS-XE versions don’t gate learning on STP state) — file a vendor case.

6. STP root disagreement — audit-stp-roots

VLANs where devices report different root_ids. Structurally impossible on a connected segment (802.1D root election converges).

l2trace audit-stp-roots

Causes when non-empty: segment partition (each half elected its own root), BPDUs filtered by an ACL or QoS misconfig, mixed PVST/RSTP/MSTP modes across vendor peers.

7. ARP IP-collision — audit-arp-collision

The first cross-table check: IPs claimed by 2+ different MACs in the same VRF.

l2trace audit-arp-collision

Real causes: DHCP IP-conflict (two hosts got the same lease), static-route typo, L2 partition with duplicate hosts on each half, or active ARP-spoofing (man-in-the-middle).

Again, device_count triages: 1 router + 2 macs is usually a single-router multi-source race; ≥2 routers is almost always a real conflict.

8. Port state × CAM — audit-port-state-cam

Cross-layer PHY/data check: ports marked admin='down' or oper IN ('down', 'lower-layer-down') with open CAM entries.

l2trace audit-port-state-cam

Down ports drop frames at the PHY layer — no frames means no MAC learning, so an open CAM on a down port is impossible in steady state. Cause is typically a stale CAM the compactor hasn’t aged, or a port-state collector lagging the CAM collector.

What “clean” looks like

Every command above prints a green “no rows found” line when the audit finds nothing. A clean sweep is:

$ for cmd in adjacencies flaps multi-vlan stp-cam stp-roots arp-collision port-state-cam; do
    echo "--- $cmd ---"
    l2trace audit-$cmd
  done
--- adjacencies ---
no asymmetric adjacencies found
--- flaps ---
no MAC flaps in the last 300s
--- multi-vlan ---
no multi-VLAN MACs
--- stp-cam ---
no STP-CAM inconsistencies
--- stp-roots ---
no STP root-bridge disagreements
--- arp-collision ---
no ARP IP-collisions
--- port-state-cam ---
no port-state/CAM inconsistencies

Save the output. The diff between today’s clean sweep and tomorrow’s flag-heavy one is faster to read than a forensics dump.

What to do with findings

Each detector’s row carries enough information to act:

• Adjacency / LLDP issues → check the physical link, the peer’s LLDP config, and whether one source is silently missing.
• CAM-table issues (flap, multi-vlan, cam-vs-stp, cam-vs-port-state) → triage with the MAC history view to see the full timeline of port assignments. Frequently a flap is just the compactor’s threshold being too generous for your churn rate.
• STP issues → suspect BPDU filtering first, then mixed-mode vendor configs. STP root disagreements correlate strongly with L2 partitions; check trunk health on the path between disagreeing devices.
• ARP issues → DHCP audit first, ARP spoofing second. Look at recent DHCP lease activity for the colliding IP; if no overlap, investigate.

See also

• Bug detection across the observation surface — the methodology, the cross-detector invariants, the F19 coverage harness.
• CLI reference — full flag lists for every audit command.
• MAC history — the per-MAC timeline view that pairs naturally with any CAM-table audit finding.