Joachim Wiberg
4c17a79de6
Update CLI samples across the documentation to the new layered presentation: physical-medium row when linked (1000baseT/...), bare MACs, and key: value DATA tokens. Add a short prose block in ethernet.md and iface.md explaining the layering. Drop the historical 'show interfaces' (plural) form — removed from klish years ago — from all user-facing examples and the landing page. Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
9.2 KiB
Ethernet Interfaces
This document covers VLAN interfaces, physical Ethernet interfaces, and virtual Ethernet (VETH) pairs.
VLAN Interfaces
Creating a VLAN can be done in many ways. This section assumes VLAN interfaces created atop another Linux interface. E.g., the VLAN interfaces created on top of the Ethernet interface or bridge in the picture below.
A VLAN interface is basically a filtering abstraction. When you run
tcpdump on a VLAN interface you will only see the frames matching the
VLAN ID of the interface, compared to all the VLAN IDs if you run
tcpdump on the lower-layer interface.
admin@example:/> configure
admin@example:/config/> edit interface eth0.20
admin@example:/config/interface/eth0.20/> show
type vlan;
vlan {
tag-type c-vlan;
id 20;
lower-layer-if eth0;
}
admin@example:/config/interface/eth0.20/> leave
The example below assumes bridge br0 is already created, see VLAN Filtering Bridge.
admin@example:/> configure
admin@example:/config/> edit interface vlan10
admin@example:/config/interface/vlan10/> set vlan id 10
admin@example:/config/interface/vlan10/> set vlan lower-layer-if br0
admin@example:/config/interface/vlan10/> leave
As conventions, a VLAN interface for VID 20 on top of an Ethernet interface eth0 is named eth0.20, and a VLAN interface for VID 10 on top of a bridge interface br0 is named vlan10.
Note
If you name your VLAN interface
foo0.NorvlanN, whereNis a number, the CLI infers the interface type automatically.
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 of speed/duplex is the desired default for almost all use-cases, but sometimes a port must come up at a specific speed — typically when interoperating with legacy hardware that does not auto-negotiate, or that does so poorly. IEEE Std 802.3.2-2025 retired the older disable auto-negotiation, then set fixed speed/duplex idiom; the standards-correct way to express the same intent is to restrict the set of PMD types auto-negotiation may advertise. When only one PMD is advertised, the link pins to that mode against any cooperating peer.
Each entry in auto-negotiation/advertised-pmd-types is an IEEE
PMD-type identity (ieee802-ethernet-phy-type:pmd-type-*). Half- vs
full-duplex pinning is expressed by the orthogonal duplex leaf.
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:/>
Listing multiple PMD identities advertises that set; the peer's auto-negotiation picks the highest mutually-supported mode.
Important
When pinning to a specific link mode, ensure both sides of the link agree on at least one common (PMD, duplex) combination. If they don't, the link will not come up.
Note
Earlier Infix releases used
auto-negotiation/enable=falsewithspeedandduplexleaves to express the same thing. That syntax is retired together with the IEEE obsoletion ofeth:speed; existingstartup-config.cfgsnippets are automatically migrated to the new shape on upgrade.
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 statistics1 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
eth-in-frames : 434
eth-in-multicast-frames : 296
eth-in-broadcast-frames : 138
eth-in-error-fcs-frames : 0
eth-in-error-oversize-frames : 0
eth-out-frames : 310
eth-out-multicast-frames : 310
eth-out-broadcast-frames : 0
eth-out-good-octets : 76821
eth-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
vethmanually.
-
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. ↩︎