This is an old revision of the document!
Table of Contents
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
eth0is 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
kethXand lets the bridge take over theeth0name. - The bridge also takes over the original MAC address, so DHCP still hands out the same IP after an EVE update.
kethXgets a different MAC (with the local bit set) so there's no collision.
In short: eth0 is the bridge. kethX is the real physical NIC sitting underneath it, demoted to a bridge port.
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 |
Migration Note
On tenant offboarding/re-onboarding, a stale kethX left over from a previous config is a real failure mode. If the bridge/keth pairing didn't tear down cleanly, the rename can conflict with the next setup. Worth checking during migration troubleshooting.
Source
Confirmed against the lf-edge EVE design doc “K3S flat network in EVE” (wiki.lfedge.org), which describes the bridge-per-port and keth renaming mechanism directly.