infix/doc/ethernet.md

Ethernet Interfaces

This document covers physical Ethernet interfaces and virtual Ethernet (VETH) pairs. For VLAN interfaces stacked on top of an Ethernet port or bridge, see VLAN Interfaces.

Physical Ethernet Interfaces

Ethernet Settings and Status

Physical Ethernet interfaces provide low-level settings for speed/duplex as well as packet status and statistics.

By default, Ethernet interfaces defaults to auto-negotiating speed/duplex modes, advertising all speed and duplex modes available. In the example below, the switch would by default auto-negotiate speed 1 Gbps on port eth1 and 100 Mbps on port eth4, as those are the highest speeds supported by H1 and H2 respectively.

A quick at-a-glance view of the physical link is available in the summary listing. When a port is up, a physical-layer row appears above the ethernet row, naming the IEEE PMD type (e.g. 1000baseT, 10GbaseLR) in the PROTOCOL column and the negotiated duplex in DATA. When the link is down the row is omitted and the interface name falls onto the ethernet row.

admin@example:/> show interface
INTERFACE       PROTOCOL      STATE       DATA             
eth1            1000baseT     UP          duplex: full
                ethernet                  00:53:00:06:11:01
eth2            1000baseT     UP          duplex: full
                ethernet                  00:53:00:06:11:02
eth3            ethernet      DOWN        00:53:00:06:11:03
eth4            100baseTX     UP          duplex: full
                ethernet                  00:53:00:06:11:04
...

The detail view spells everything out, including auto-negotiation state and the speed in Mbit/s.

admin@example:/> show interface eth1
name               : eth1
index              : 2
mtu                : 1500
operational status : up
link mode          : 1000baseT
auto-negotiation   : on
duplex             : full
speed              : 1000
physical address   : 00:53:00:06:11:01
ipv4 addresses     :
ipv6 addresses     :
in-octets          : 75581
out-octets         : 43130
...
admin@example:/> show interface eth4
name               : eth4
index              : 5
mtu                : 1500
operational status : up
link mode          : 100baseTX
auto-negotiation   : on
duplex             : full
speed              : 100
physical address   : 00:53:00:06:11:04
ipv4 addresses     :
ipv6 addresses     :
in-octets          : 75439
out-octets         : 550704
...
admin@example:/>

Restricting advertised link modes

Auto-negotiation is the right default for almost all links, but sometimes a port has to come up at a fixed speed, usually when talking to old hardware that won't auto-negotiate or does it badly. IEEE Std 802.3.2-2025 dropped the old "turn off auto-negotiation, then set a fixed speed and duplex" approach. Instead you restrict the set of PMD types the port may advertise: list a single PMD and the link pins to that mode against any peer that supports it.

Note

Earlier Infix releases needed enable false plus explicit speed and duplex leaves. IEEE Std 802.3.2-2025 retired the eth:speed leaf, so the speed now comes from the advertised-pmd-types entry instead. Existing startup-config.cfg files are migrated automatically on upgrade.

Each entry in auto-negotiation/advertised-pmd-types is an IEEE PMD-type identity (ieee802-ethernet-phy-type:pmd-type-*). The separate duplex leaf controls half vs full duplex.

The example below pins port eth3 to 100 Mbit/s half-duplex.

admin@example:/> configure
admin@example:/config/> edit interface eth3 ethernet
admin@example:/config/interface/eth3/ethernet/> set auto-negotiation advertised-pmd-types pmd-type-100BASE-TX
admin@example:/config/interface/eth3/ethernet/> set duplex half
admin@example:/config/interface/eth3/ethernet/> show
auto-negotiation {
  advertised-pmd-types [ ieee802-ethernet-phy-type:pmd-type-100BASE-TX ];
}
duplex half;
admin@example:/config/interface/eth3/ethernet/> leave
admin@example:/>

List several PMDs to advertise all of them; auto-negotiation then settles on the highest mode both ends support.

Important

When pinning a link mode, make sure both ends share at least one common (PMD, duplex) combination, otherwise the link will not come up.

Duplex and advertised modes

A PMD type like 10BASE-T or 100BASE-TX says nothing about duplex on its own, but the kernel tracks half and full duplex as separate link modes. Infix advertises both variants of every PMD you list, then narrows to one duplex when the duplex leaf is set:

advertised-pmd-types	duplex	Resulting advertised modes
[10BASE-T]	unset	10baseT/Half + 10baseT/Full
[10BASE-T]	full	10baseT/Full
[10BASE-T]	half	10baseT/Half
[10BASE-T, 100BASE-TX]	unset	all four half/full combinations
[10BASE-T, 100BASE-TX]	full	10baseT/Full + 100baseT/Full
unset	unset	every mode the PHY supports (default)

So duplex filters the PMDs you listed. PMDs with no half-duplex variant (everything above 1 Gbps) only ever advertise full.

Disabling auto-negotiation

The method above keeps auto-negotiation on and only limits what it advertises, so the peer still negotiates as usual. That doesn't help with gear that won't negotiate at all, like some old switches or a back-to-back copper link. For those, set auto-negotiation/enable false together with a single advertised-pmd-types entry to force a fixed speed and duplex with negotiation off:

admin@example:/config/interface/eth3/ethernet/> set auto-negotiation enable false
admin@example:/config/interface/eth3/ethernet/> set auto-negotiation advertised-pmd-types pmd-type-100BASE-TX
admin@example:/config/interface/eth3/ethernet/> set duplex full

With enable false you must list exactly one PMD: it sets the speed, and the duplex leaf sets half or full. Leave duplex out and Infix uses whatever the PMD supports, normally full.

Auto-MDIX usually rides along with auto-negotiation, so turning negotiation off can leave both ends picking the same MDI/MDI-X pinout. The link then comes up electrically but carries no traffic. When that happens, force opposite pinouts with the mdi-x leaf — set one end true (MDI-X) and the other false (MDI):

admin@example:/config/interface/eth3/ethernet/> set mdi-x false

Leaving mdi-x unset keeps Auto-MDIX in charge, which is correct whenever auto-negotiation is on.

Note

Whether enable false reaches the external PHY depends on the driver. Direct-attach NICs handle it directly. Switch user ports go through the switch driver, and some accept the request at the MAC but leave the PHY auto-negotiating: the kernel reports the configured speed while the wire runs at whatever was negotiated, and traffic stalls. If that happens, read the PHY's BMCR register (e.g. with mdio from mdiotools) to see what the PHY is actually doing.

The detail view exposes a supported block (operational state, backed by the supported-pmd-types leaf-list) listing the PMD types the kernel currently believes the interface can operate at. For SFP/SFP+ cages this set reflects the inserted module: plug in a 10G LR optic and supported will narrow to 10GbaseLR only. Combined with the operational link mode row above it, this makes it trivial to confirm what an unknown transceiver actually is — no ethtool -m round-trip needed.

admin@example:/> show interface eth13
name               : eth13
type               : ethernet
operational status : up
link mode          : 10GbaseLR
auto-negotiation   : off
supported          : 10GbaseLR
duplex             : full
speed              : 10000
...

Ethernet statistics

Ethernet packet statistics¹ can be listed as shown below.

admin@example:/> show interface eth1
name               : eth1
index              : 2
mtu                : 1500
operational status : up
link mode          : 1000baseT
auto-negotiation   : on
duplex             : full
speed              : 1000
physical address   : 00:53:00:06:11:0a
ipv4 addresses     :
ipv6 addresses     :
in-octets          : 75581
out-octets         : 43130
───────────────────
Ethernet Statistics
in-frames                : 434
in-multicast-frames      : 296
in-broadcast-frames      : 138
in-error-fcs-frames      : 0
in-error-oversize-frames : 0
out-frames               : 310
out-multicast-frames     : 310
out-broadcast-frames     : 0
out-good-octets          : 76821
in-good-octets           : 60598
admin@example:/>

VETH Pairs

A Virtual Ethernet (VETH) pair is basically a virtual Ethernet cable. A cable can be "plugged in" to a bridge and the other end can be given to a container, or plugged into another bridge.

The latter example is useful if you have multiple bridges in the system with different properties (VLAN filtering, IEEE group forwarding, etc.), but still want some way of communicating between these domains.

admin@example:/> configure
admin@example:/config/> edit interface veth0a
admin@example:/config/interface/veth0a/> set veth peer veth0b
admin@example:/config/interface/veth0a/> end
admin@example:/config/> diff
interfaces {
+  interface veth0a {
+    type veth;
+    veth {
+      peer veth0b;
+    }
+  }
+  interface veth0b {
+    type veth;
+    veth {
+      peer veth0a;
+    }
+  }
}
admin@example:/config/>

Tip

This is another example of the automatic inference of the interface type from the name. Any name can be used, but then you have to set the interface type to veth manually.

---

1. Ethernet counters are described in ieee802-ethernet-interface.yang and infix-ethernet-interface.yang. There is a dedicated document on Ethernet Counters that provide additional details on the statistics support. ↩︎