Skip to content

cli: show interface, layered presentation on IEEE 802.3.2-2025 #1495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
troglobit wants to merge 6 commits into
base: main
Choose a base branch
from
Open

cli: show interface, layered presentation on IEEE 802.3.2-2025 #1495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bb9e927
cli: layered show interface, IEEE 802.3.2-2025 ethernet model
troglobit May 21, 2026
1589c23
doc: refresh show interface samples and rename plural form
troglobit May 18, 2026
d60017e
doc: add vlan.md, update ChangeLog for the branch
troglobit May 19, 2026
528692a
cli: tighten 'show interface' detail-view alignment
troglobit May 19, 2026
1e06cf7
show: relay cli-pretty's user-facing error messages
troglobit May 19, 2026
4c80fe6
cli: add 'show operational [path /X]' and path filter to config views
troglobit May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 27 additions & 4 deletions doc/ChangeLog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,21 +10,45 @@ All notable changes to the project are documented in this file.

- Upgrade Linux kernel to 6.18.32 (LTS)
- Upgrade FRR to 10.5.4
- Add support for [Acer Connect Vero W6m][AcerConnectVero], a COTS home router,
based upon the same hardware as [Banana Pi BPI-R3][BPI-R3], but
- Add support for [Acer Connect Vero W6m][AcerConnectVero], a low-cost COTS
home router, based on the same hardware as [Banana Pi BPI-R3][BPI-R3], but
with a Wi-Fi 6E (6 GHz band) chip.
- Add configurable channel-width in Wi-Fi configuration.
- Upgrade `ieee802-ethernet-interface` YANG model to revision 2025-09-10 (IEEE
Std 802.3.2-2025), adding the standard `phy-type` and `pmd-type` operational
leaves. Speed is now exposed via `ietf-interfaces:speed` (bps, RFC 8343);
the now obsolete `eth:speed` is no longer returned
- Rework `show interface` summary output as layered protocol rows. When a
port has link, a physical-medium row (e.g. `1000baseT`, `10GbaseLR`) appears
above the `ethernet` row. VLAN, GRE, VXLAN and WiFi interfaces likewise get
one row per protocol layer, with type-specific data on each (`vid:`,
`remote:`, `vni:`, `station ssid:`, etc.), issue #530
- Replace `auto-negotiation/enable=false` + fixed `speed`/`duplex` (retired in
IEEE Std 802.3.2-2025) with `auto-negotiation/advertised-pmd-types`, a list
of PMD-type identities (PMD ~ `ethtool` link mode). Listing a single PMD
pins the link to that mode; multiple entries restrict the auto-negotiation
set. Existing startup configurations are migrated automatically on upgrade
- New operational `supported-pmd-types` leaf-list on each Ethernet interface,
exposing the set of PMD types currently supported. Useful for SFP/SFP+
diagnosis: an LR-only optic narrows the list to a single entry, confirming
the transceiver without `ethtool -m`

### Fixes

- Fix #1493: container with a physical interface not properly removed
when switching to a configuration without containers
- Fix #1506: add documentation on how to configure VLAN interfaces,
including stacked (Q-in-Q) VLAN interfaces, in a dedicated `vlan.md`
- Fix long-standing typo `auto-negotation` in `yanger`, which caused
the operational `auto-negotiation/enable` leaf to always read as
`unknown` regardless of the actual port setting
- Handle unclean daemon exits better, e.g., `dbus-daemon` crashing and
leaving a stale pidfile behind, causing it to refuse to be restarted
- Fix occasional blank or garbled `[ OK ]` lines at startup
- Disallow multicast MAC addresses in custom MAC address configuration
- Fix broken Wi-Fi 6 GHz band configuration.

[BPI-R3]: https://docs.banana-pi.org/en/BPI-R3/BananaPi_BPI-R3
[AcerConnectVero]: ../board/aarch64/acer-connect-vero-w6m/

[v26.04.0][] - 2026-04-30
Expand Down Expand Up @@ -72,7 +96,6 @@ All notable changes to the project are documented in this file.
- Fix [BPI-R3][] PCIe devices failing to initialize on boot due to a missing
clock definition in the device tree

[BPI-R3]: https://wiki.banana-pi.org/Banana_Pi_BPI-R3
[BPI-R4]: https://docs.banana-pi.org/en/BPI-R4/BananaPi_BPI-R4
[ESPRESSObin]: https://espressobin.net/
[SAMA7G54]: https://www.microchip.com/en-us/development-tool/ev21h18a
Expand Down Expand Up @@ -176,7 +199,7 @@ All notable changes to the project are documented in this file.

- Fix CLI `copy` command problem to copy to scp/sftp destinations

[BPI-R3-MINI]: https://wiki.banana-pi.org/Banana_Pi_BPI-R3_Mini
[BPI-R3-MINI]: https://docs.banana-pi.org/en/BPI-R3_Mini/BananaPi_BPI-R3_Mini
[SAMA7G54-EK]: https://www.microchip.com/en-us/development-tool/ev21h18a

[v26.01.0][] - 2026-02-03
Expand Down
4 changes: 2 additions & 2 deletions doc/bridging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,8 +73,8 @@ admin@example:/config/interface/br0/> <b>set bridge vlans vlan 20 tagged br0</b>
</code></pre>

To route or to manage via a VLAN, a VLAN interface needs to be created
on top of the bridge, see section [VLAN Interfaces](ethernet.md#vlan-interfaces)
for more on this topic.
on top of the bridge, see section [VLAN Interfaces](vlan.md) for more
on this topic.

> [!NOTE]
> In some use-cases only a single management VLAN on the bridge is used.
Expand Down
2 changes: 1 addition & 1 deletion doc/cli/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ interfaces {
}
}
admin@host-12-34-56:/config/interface/eth0/> leave
admin@host-12-34-56:/> show interfaces
admin@host-12-34-56:/> show interface
INTERFACE PROTOCOL STATE DATA
lo loopback UNKNOWN 00:00:00:00:00:00
ipv4 127.0.0.1/8 (static)
Expand Down
8 changes: 4 additions & 4 deletions doc/dhcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,11 +109,11 @@ When configuring, e.g., `dns-server`, or `router` options with the value
`auto`, the system uses the IP address from the interface matching the
subnet. For example:

<pre class="cli"><code>admin@example:/> <b>show interfaces</b>
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
eth0 ethernet UP 02:00:00:00:00:00
<pre class="cli"><code>admin@example:/> <b>show interface</b>
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
eth0 ethernet UP 02:00:00:00:00:00
ipv4 192.168.1.1/24 (static)
eth1 ethernet UP 02:00:00:00:00:01
eth1 ethernet UP 02:00:00:00:00:01
ipv4 192.168.2.1/24 (static)

admin@example:/config/dhcp-server/subnet/192.168.1.0/24/> <b>edit option dns-server</b>
Expand Down
250 changes: 130 additions & 120 deletions doc/ethernet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,8 @@
# 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.

![VLAN interface on top of Ethernet or Bridge interfaces](img/interface-vlan-variants.svg)

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.

<pre class="cli"><code>admin@example:/> <b>configure</b>
admin@example:/config/> <b>edit interface eth0.20</b>
admin@example:/config/interface/eth0.20/> <b>show</b>
type vlan;
vlan {
tag-type c-vlan;
id 20;
lower-layer-if eth0;
}
admin@example:/config/interface/eth0.20/> <b>leave</b>
</code></pre>

The example below assumes bridge br0 is already created, see [VLAN
Filtering Bridge](bridging.md#vlan-filtering-bridge).

<pre class="cli"><code>admin@example:/> <b>configure</b>
admin@example:/config/> <b>edit interface vlan10</b>
admin@example:/config/interface/vlan10/> <b>set vlan id 10</b>
admin@example:/config/interface/vlan10/> <b>set vlan lower-layer-if br0</b>
admin@example:/config/interface/vlan10/> <b>leave</b>
</code></pre>

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.N` or `vlanN`, where `N` is a
> number, the CLI infers the interface type automatically.
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](vlan.md).


## Physical Ethernet Interfaces
Expand All @@ -56,111 +12,165 @@ top of a bridge interface *br0* is named *vlan10*.
Physical Ethernet interfaces provide low-level settings for speed/duplex as
well as packet status and [statistics](#ethernet-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 Gbit/s on port eth1 and 100 Mbit/s on port eth4, as those are the
highest speeds supported by H1 and H2 respectively.
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.

![4-port Gbit/s switch connected to Gbit and Fast Ethernet Hosts](img/ethernet-autoneg.svg)

The speed and duplex status for the links can be listed as shown
below, assuming the link operational status is 'up'.
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.

<pre class="cli"><code>admin@example:/> <b>show interface</b>
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
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
...
</code></pre>

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

<pre class="cli"><code>admin@example:/> <b>show interface eth1</b>
name : eth1
index : 2
mtu : 1500
operational status : up
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
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:/> <b>show interface eth4</b>
name : eth4
index : 5
mtu : 1500
operational status : up
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
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:/>
</code></pre>

### Configuring fixed speed and duplex
### Restricting advertised link modes

Auto-negotiation of speed/duplex mode is desired in almost all
use-cases, but it is possible to disable auto-negotiation and specify
a fixed speed and duplex mode.
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.

> [!IMPORTANT]
> When setting a fixed speed and duplex mode, ensure both sides of the
> link have matching configuration. If speed does not match, the link
> will not come up. If duplex mode does not match, the result is
> reported collisions and/or bad throughput.
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 configures port eth3 to fixed speed 100 Mbit/s
half-duplex mode.
The example below pins port `eth3` to 100 Mbit/s half-duplex.

<pre class="cli"><code>admin@example:/> <b>configure</b>
admin@example:/config/> <b>edit interface eth3 ethernet</b>
admin@example:/config/interface/eth3/ethernet/> <b>set speed 0.1</b>
admin@example:/config/interface/eth3/ethernet/> <b>set auto-negotiation advertised-pmd-types pmd-type-100BASE-TX</b>
admin@example:/config/interface/eth3/ethernet/> <b>set duplex half</b>
admin@example:/config/interface/eth3/ethernet/> <b>set auto-negotiation enable false</b>
admin@example:/config/interface/eth3/ethernet/> <b>show</b>
auto-negotiation {
enable false;
advertised-pmd-types [ ieee802-ethernet-phy-type:pmd-type-100BASE-TX ];
}
duplex half;
speed 0.1;
admin@example:/config/interface/eth3/ethernet/> <b>leave</b>
admin@example:/>
</code></pre>

Speed metric is in Gbit/s. Auto-negotiation needs to be disabled in
order for fixed speed/duplex to apply. Only speeds `0.1`(100 Mbit/s)
and `0.01` (10 Mbit/s) can be specified. 1 Gbit/s and higher speeds
require auto-negotiation to be enabled.
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=false` with
> `speed` and `duplex` leaves to express the same thing. That syntax
> is retired together with the IEEE obsoletion of `eth:speed`; existing
> `startup-config.cfg` snippets 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.

<pre class="cli"><code>admin@example:/> <b>show interface eth13</b>
name : eth13
type : ethernet
operational status : up
link mode : 10GbaseLR
auto-negotiation : off
supported : 10GbaseLR
duplex : full
speed : 10000
...
</code></pre>

### Ethernet statistics

Ethernet packet statistics[^1] can be listed as shown below.

<pre class="cli"><code>admin@example:/> <b>show interface eth1</b>
name : eth1
index : 2
mtu : 1500
operational status : up
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
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
───────────────────
<b>Ethernet Statistics</b>
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:/>
</code></pre>

Expand Down
Loading