Ethernet interfaces — naming, MAC, driver mapping

The physical Ethernet interfaces are the foundation of every VyOS router. The operator configures eth0, eth1, … but the Linux kernel and the hardware see different names. This lesson covers the mapping, the MAC address assignment, the driver detection, and the failure modes that surface when the mapping goes wrong.

How the kernel names map to VyOS names

flowchart LR
  subgraph Kernel[Linux kernel]
    K1[enp0s3<br/>PCI 0000:00:03.0]
    K2[enp1s0<br/>PCI 0000:01:00.0]
    K3[ens5<br/>Nitro system]
    K4[eth0<br/>legacy udev rule]
  end
  subgraph VyOS[VyOS shell]
    V1[eth0]
    V2[eth1]
    V3[eth2]
  end
  K1 --> V1
  K2 --> V2
  K3 --> V3
  K4 --> V1

The kernel uses predictable interface names (enp0s3, enp1s0, ens5) based on PCI bus position. VyOS maps these to eth0, eth1, … in enumeration order. The mapping is done by vyos-platform.hotplug at boot and after every NIC event.

Reading the mapping

vyos@vyos:~$ show interface ethernet
Codes: S - State, L - Link, u - Up, D - Down, A - AdminDown
Interface        IP Address                        S/L  Description
---------        ----------                        ---  -----------
eth0             192.0.2.1/24                      u/u  OUTSIDE
eth1             10.0.0.1/24                       u/u  INSIDE
eth2             -                                 u/D  TRANSIT

The S/L column shows administrative state (S) and link state (L). u/u means both up; u/D means admin-up but link-down; A/D means admin-down and link-down.

Mapping from the kernel

vyos@vyos:~$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether 52:54:00:12:34:57 brd ff:ff:ff:ff:ff:ff

The kernel’s ip link show shows the same names that VyOS uses on bare metal. On cloud images, the kernel uses ens5 etc. but VyOS remaps to eth0, eth1, …

MAC address assignment

vyos@vyos:~$ show interface ethernet eth0
eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 52:54:00:12:34:56 brd ff:ff:ff:ff:ff:ff
    inet 192.0.2.1/24 brd 192.0.2.255 scope global eth0
       valid_lft forever preferred_lft forever

The MAC address is assigned by the kernel from the NIC’s ROM. On virtual machines, the hypervisor assigns the MAC. On cloud images, the cloud platform assigns.

The operator can override:

set interfaces ethernet eth0 mac 'aa:bb:cc:dd:ee:ff'
commit
save

This is useful when the operator needs a specific MAC for a peer that filters on MAC.

Driver detection

vyos@vyos:~$ ethtool -i eth0
driver: virtio_net
version: 1.0.0
firmware-version:
bus-info: 0000:00:03.0
supports-statistics: yes
supports-test: yes
supports-eeprom-access: no
supports-register-dump: no
supports-priv-flags: no

driver: is the kernel module. On bare metal it might be igc, ixgbe, mlx5_core, etc. On VMs it is virtio_net or e1000 or vmxnet3. The driver determines which offloads (TSO, LRO, GRO, checksum) are available.

Speed and duplex

vyos@vyos:~$ ethtool eth0
Settings for eth0:
    Supported ports: [ TP ]
    Supported link modes:   10baseT/Half 10baseT/Full
                            100baseT/Half 100baseT/Full
                            1000baseT/Full
    Speed: 1000Mb/s
    Duplex: Full
    Auto-negotiation: on
    Port: Twisted Pair
    PHYAD: 0
    Transceiver: internal
    Link detected: yes

Speed: shows the negotiated link speed. A box that should be on 10 Gbps but shows 1000Mb/s has a cabling or autonegotiation problem.

How the result is validated

show interface ethernet
ip link show
ip addr show
ethtool eth0
ethtool -i eth0

The show interface ethernet is the VyOS view; the ip, ethtool commands are the Linux kernel view. Both should agree on link state and addresses.

How it fails

The production failure modes the engineer must recognise:

• Wrong kernel-to-VyOS mapping. A box with two NICs in reverse order on the PCI bus has eth0 and eth1 mapped backwards from the operator’s intent. Routing goes out the wrong interface.
• MAC duplication. Two VMs with the same MAC on the same bridge produce intermittent ARP failures. The hypervisor must assign unique MACs.
• Link down. A cable unplugged, a switch port disabled, a NIC driver crash. show interface ethernet shows D for link.
• Speed mismatch. One end autonegotiates to 1000/full; the other end is forced to 100/full. Packets flow with errors. Always let both ends autonegotiate.
• Driver crash. A faulty NIC driver crashes and the interface disappears. The kernel logs the crash; the operator reloads the driver or replaces the NIC.

Rollback

The recovery from a bad Ethernet configuration:

• set interfaces ethernet eth0 address dhcp reverted with delete interfaces ethernet eth0 address dhcp; set interfaces ethernet eth0 address 192.0.2.1/24; commit; save.
• A wrong-driver mapping recovered by rebooting with the correct driver binding.
• A link-down issue recovered by fixing the cable / switch port.

Production discipline

Cross-course references

The Linux course’s XIX-Linux-NetFoundations covers the kernel interface naming in detail. The Proxmox course’s XXIX-Proxmox-Networking covers the host-side bridge configuration. The OPNsense course’s VII-OPNsense-Interfaces covers the equivalent configuration on the firewall side.

Quiz