Differences

This shows you the differences between two versions of the page.

--- eve-os:interface-naming [2026/08/20 14:40] – mc
+++ eve-os:interface-naming [2026/08/20 15:03] (current) – [Migration Note] mc
@@ Line 7: / Line 7: @@
 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: Physical Adapter =====
+===== ethX: The Name You Actually Use =====
-  * The raw physical network port as EVE-OS first sees it.
+  * ''eth0'' is what everything in EVE and your apps expect to see: the IP address, VLAN subinterfaces, DHCP lease, all of it.
-  * Shows up in the Hardware Model / device model as an adapter.
+  * What's actually behind that name depends on the port. Read on.
-  * If it's not used by a Network Instance, it just stays as ''ethX''.
-===== kethX: Demoted Physical NIC =====
+===== kethX: The Physical NIC, Hidden Underneath =====
-This is the one that confuses people.
+This is the one that confuses people, because it shows up even with zero Switch NIs configured.
-  * Only appears when a physical NIC is assigned to a Switch Network Instance.
+  * 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.
-  * Switch NI is pure L2 bridging, meant to act like the physical NIC is directly wired to your VMs/containers.
+  * 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).
-  * The bridge needs to be named ''eth0'' so everything else in the system keeps referring to a stable, familiar name.
+  * 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.
-  * The physical NIC is already using that name, so the kernel can't have two things called ''eth0''.
+  * To pull this off without renaming anything visible, EVE renames the physical NIC to ''kethX'' and lets the bridge take over the ''eth0'' name.
-  * The physical NIC gets renamed to ''kethX'' (kernel eth) and demoted to being a port/slave on the new bridge.
-  * The bridge takes over the ''eth0'' name and becomes the interface everyone talks to.
-In short: ''eth0'' stops being the physical NIC's name and becomes the bridge's name. The physical NIC gets relabeled ''keth0'' and sits underneath as one port on that bridge.
+===== MAC Address Behavior (version dependent) =====
-===== bnX / bridgeX: The Bridge Itself =====
+  * **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.
-  * Created for Switch NI.
+===== bnX / bridgeX: Bridges for Network Instances =====
-  * Takes over the original interface name/identity.
-  * ''kethX'' (physical NIC) is a port on it.
-  * App VIFs (container/VM virtual NICs) are also ports on it.
-  * Physical NIC and app traffic share L2 like a real switch.
-===== Local NI: No kethX Needed =====
+  * 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 is NAT plus DHCP plus DNS, not pure passthrough.
+  * Local NI adds NAT, DHCP, and DNS on top. Switch NI is pure L2.
-  * It builds its own bridge but doesn't need to preserve the physical NIC's original name the same way.
-  * No ''kethX'' renaming here.
 ===== Reference Table =====
 ^ Interface ^ What it is ^ When you see it ^
-| ethX | Physical NIC, untouched | No NI, or Local NI upstream |
+| ethX | The bridge, holding the IP/VLANs/MAC everyone expects | Almost always, even with no Switch NI |
-| kethX | Physical NIC, demoted to bridge port | Switch NI only |
+| kethX | The real physical NIC, demoted underneath the bridge | Same as above, minus LTE/WiFi and VLAN/bond members |
-| bridge/bnX | The bridge that took over the original name | Switch NI |
+| 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 the bridge |
+| vifX | App/container virtual interface | Any NI, attached to its bridge |
-===== Migration Note =====
+===== Sources =====
-On tenant offboarding/re-onboarding, a stale ''kethX'' left over from a previous Switch NI config is a real failure mode. If the bridge/keth pairing didn't tear down cleanly, the rename can conflict with the next NI setup. Worth checking during migration troubleshooting.
+  * 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.