Diagnosing FreeBSD Ethernet Link Flapping at the Driver Level

An Ethernet interface that repeatedly goes up and down — link flapping — has a small number of actual root causes, and FreeBSD exposes enough driver and link-state information to distinguish between them without guessing. The mistake is treating every flap as the same problem and reaching for the same fix (usually “replace the cable”) regardless of what the interface itself is actually reporting.

Confirming it’s actually flapping, and how often

Before anything else, get a precise record of when link state changes happen, not just a vague sense that “the network drops sometimes.” ifconfig’s own status, combined with devd/syslog link-state logging, gives exact timestamps:

grep -i "link state changed" /var/log/messages

FreeBSD’s network stack logs a link state changed to UP/DOWN message via devd for most drivers whenever the physical link state actually changes, and having exact timestamps for every flap is the foundation for everything else — a flap every few seconds under load looks different from one flap every few hours, and points at different causes.

Checking driver-level error counters

netstat -i and, more granularly, sysctl dev.<driver>.<unit>.stats (where supported by the specific driver) expose hardware-level error counters — CRC errors, alignment errors, collisions — that distinguish a physical-layer problem from something else entirely:

netstat -i
sysctl dev.igb.0.mac_stats

(substitute the actual driver name — igb, em, ix, re, etc. — for whichever NIC is involved; not every driver exposes the same sysctl tree, but most modern Intel and Chelsio drivers expose fairly detailed MAC-level statistics). A steadily climbing CRC error or alignment error count strongly implicates the physical layer: a bad cable, a failing transceiver/SFP module, or electrical interference — these errors specifically indicate frames arriving corrupted at the electrical level, which is not something a driver bug or switch misconfiguration typically produces.

Physical layer: cable, transceiver, and auto-negotiation

If error counters point at the physical layer, the standard elimination sequence applies, but with FreeBSD-specific commands for confirming what’s actually negotiated:

ifconfig <interface> media

lists the media types the driver supports and what’s currently negotiated. A link that’s negotiated at a lower speed or different duplex setting than both ends actually support (e.g., negotiated at 10baseT/UTP half-duplex on hardware capable of gigabit) is a strong signal of an auto-negotiation mismatch — commonly caused by one end being hard-set to a specific speed/duplex while the other is left on auto-negotiate, which frequently negotiates incorrectly rather than falling back gracefully. Forcing both ends to the same explicit setting (both hard-set, or both auto) resolves this category cleanly:

ifconfig <interface> media 1000baseT mediaopt full-duplex

If media negotiation looks correct but flapping continues, physically reseating the cable and, if using SFP/SFP+ modules, the transceiver itself, is worth doing before assuming a software problem — a partially-seated transceiver is a common, physically-obvious-in-hindsight cause that produces intermittent rather than constant failure, which is exactly what makes it easy to misdiagnose as something more complex.

Switch-side causes

If the physical layer checks out (clean cable run, correctly seated transceiver, matched negotiation settings) but flapping continues, the next most common cause is switch-side: spanning tree reconvergence events, a switch port flapping due to its own hardware issue, or a switch configured with aggressive link-flap detection that’s shutting the port down defensively in response to something else entirely (a broadcast storm, a duplicate MAC address on the segment). Checking the switch’s own port logs for the same timestamps identified from FreeBSD’s devd logging is the direct way to correlate — if the switch logs a spanning-tree topology change or its own link-down event at the exact same second FreeBSD logs link state changed to DOWN, the cause is upstream of the FreeBSD host entirely, and no amount of driver-level tuning on the FreeBSD side will fix it.

Driver or firmware-level causes

If both the physical layer and switch-side logs are clean, but flapping is genuinely originating at the FreeBSD host, a driver or firmware issue becomes the more likely remaining explanation — particularly with newer or less mature NIC firmware, or a driver version mismatch relative to the actual hardware revision. Check dmesg and pciconf -lv for the exact NIC model and firmware version reported, and compare against the FreeBSD hardware notes / release errata for the specific driver in use; some NIC firmware revisions have documented issues with specific link states (particularly around energy-efficient Ethernet / EEE negotiation, which has caused real, documented flapping issues on some hardware combinations) that are resolved by either a firmware update from the vendor or, in some cases, explicitly disabling EEE at the driver level:

ifconfig <interface> -eee

This single flag has resolved genuine, hardware-confirmed flapping issues on certain NIC/switch combinations where EEE’s low-power link-idle negotiation was being interpreted differently by each side, causing periodic renegotiation that presented exactly as link flapping.

Building the actual diagnosis, not skipping to a fix

The reliable path through this is sequential, not parallel guessing: confirm the flap pattern and timing first, check hardware error counters second (this alone often conclusively points at or rules out the physical layer), check switch-side logs for correlated events third, and only conclude “driver/firmware issue” once the first three have genuinely been ruled out rather than just seeming inconclusive. Jumping straight to a firmware update or a driver-tuning sysctl without first confirming the cable and switch are clean is the most common way this kind of troubleshooting goes in circles — fixing (or failing to fix) a symptom without ever having confirmed which layer actually owns the problem.