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— simple, unmodified.
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 = pure L2 bridging, meant to act like the physical NIC is directly wired to your VMs/containers.
- Problem: EVE-OS wants the bridge to be named
eth0(so everything else in the system keeps referring to a stable, familiar name). - But the physical NIC is already using that name — so the kernel can't have two things called
eth0. - Fix: the physical NIC gets renamed to
kethX(“kernel eth”) and demoted to being just a port/slave on the new bridge. - The bridge takes over the
eth0name and becomes the “real” interface everyone talks to.
Think of it like: eth0 used to be the front door. Now eth0 is a hallway (the bridge), and the old front door got relabeled keth0 and shoved into that hallway as one entrance among others.
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.
- Result: physical NIC and app traffic share L2 like a real switch.
Local NI — No kethX Needed
- Local NI = NAT + DHCP + DNS, not pure passthrough.
- It builds its own bridge but doesn't need to preserve the physical NIC's original name the same way.
- So you won't see the
kethXrenaming dance here.
Quick 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 |
Gotcha to Watch For
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.