====== EVE OS Interfaces ======

A quick plain-English guide to the interface names you'll see on an EVE-OS device.

===== The Basics =====

When EVE-OS boots, every physical NIC on the box gets discovered and given a name based on PCI location (like ''eth0'', ''eth1'', etc). These are your physical ports, the actual copper/fiber jacks on the hardware.

===== ethX: The Name You Actually Use =====

  * ''eth0'' is what everything in EVE and your apps expect to see: the IP address, VLAN subinterfaces, DHCP lease, all of it.
  * What's actually behind that name depends on the port. Read on.

===== kethX: The Physical NIC, Hidden Underneath =====

This is the one that confuses people, because it shows up even with zero Switch NIs configured.

  * EVE puts a Linux bridge in front of nearly every Ethernet port it manages. Not just ports used by a Switch NI, basically all of them.
  * The exceptions: LTE and WiFi ports (can't do Ethernet bridging), and ports that are members of a VLAN or bond adapter (those skip the kethX treatment).
  * Why bridge everything up front: so a bridge is already sitting there ready to accept app VIFs later, even on the management port itself, without needing a reboot or reconfig.
  * To pull this off without renaming anything visible, EVE renames the physical NIC to ''kethX'' and lets the bridge take over the ''eth0'' name.

===== MAC Address Behavior (version dependent) =====

  * **EVE 17.0 and newer (PR #6167, merged Jul 2026):** ''ethX'' and ''kethX'' share the exact same MAC address. Testing showed this causes no problems; the Linux bridge FDB tolerates a duplicate local address by design, and NIM only assigns IP (including IPv6 link-local) to the ''ethX'' bridge, never to ''kethX'', so there's no collision.
  * **Older EVE (pre-17.0, still true on 16.0/14.5/13.4-stable):** ''kethX'' got a different MAC than ''ethX'' by flipping the locally-administered bit. This was a conservative design choice, not a technical requirement, and it's what could make a box look like it has two MACs on one port, which some security software flagged.
  * Check your EVE version before assuming which behavior you're looking at.

===== bnX / bridgeX: Bridges for Network Instances =====

  * These are the bridges you create explicitly through Switch NI or Local NI configuration.
  * Different from the invisible per-port bridge described above. NI bridges are user-visible and app VIFs attach to them directly.
  * Local NI adds NAT, DHCP, and DNS on top. Switch NI is pure L2.

===== Reference Table =====

^ Interface ^ What it is ^ When you see it ^
| ethX | The bridge, holding the IP/VLANs/MAC everyone expects | Almost always, even with no Switch NI |
| kethX | The real physical NIC, demoted underneath the bridge | Same as above, minus LTE/WiFi and VLAN/bond members |
| bnX / bridgeX | A Network Instance bridge (Switch NI or Local NI) | Only when that NI is configured |
| vifX | App/container virtual interface | Any NI, attached to its bridge |


===== Sources =====

  * lf-edge EVE design doc "K3S flat network in EVE" (wiki.lfedge.org), original bridge-per-port and keth renaming design.
  * [[https://github.com/lf-edge/eve/pull/6167|lf-edge/eve PR #6167]], "dpcreconciler: drop alternativeMAC", merged Jul 17 2026, backported to 17.0. Confirms current MAC-sharing behavior and drops the old locally-administered-bit distinction.