User Tools

Site Tools


eve-os:interface-naming

This is an old revision of the document!


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 eth0 so 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 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.

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 kethX renaming 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.

eve-os/interface-naming.1787236836.txt.gz · Last modified: by mc