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: Physical Adapter
- The raw physical network port as EVE-OS first sees it.
- Shows up in the Hardware Model / device model as an adapter.
- If it's not used by a Network Instance, it just stays as
ethX.
kethX: Demoted Physical NIC
This is the one that confuses people.
- Only appears when a physical NIC is assigned to a Switch Network Instance.
- Switch NI is pure L2 bridging, meant to act like the physical NIC is directly wired to your VMs/containers.
- The bridge needs to be named
eth0so everything else in the system keeps referring to a stable, familiar name. - The physical NIC is already using that name, so the kernel can't have two things called
eth0. - 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
eth0name 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.
bnX / bridgeX: The Bridge Itself
- Created for Switch NI.
- 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
- Local NI is NAT plus DHCP plus DNS, not pure passthrough.
- It builds its own bridge but doesn't need to preserve the physical NIC's original name the same way.
- No
kethXrenaming here.
Reference Table
| Interface | What it is | When you see it |
|---|---|---|
| ethX | Physical NIC, untouched | No NI, or Local NI upstream |
| kethX | Physical NIC, demoted to bridge port | Switch NI only |
| bridge/bnX | The bridge that took over the original name | Switch NI |
| vifX | App/container virtual interface | Any NI, attached to the bridge |
Migration Note
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.
