diff --git a/doc/ChangeLog.md b/doc/ChangeLog.md index 04a49b49..4b9fd689 100644 --- a/doc/ChangeLog.md +++ b/doc/ChangeLog.md @@ -10,21 +10,51 @@ All notable changes to the project are documented in this file. - Upgrade Linux kernel to 6.18.33 (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 +- New `auto-negotiation/advertised-pmd-types` leaf-list replaces the + retired `enable=false + speed + duplex` idiom for pinned link modes + (IEEE Std 802.3.2-2025 obsoleted `eth:speed`), issue #805. Existing + startup configurations are migrated automatically on upgrade; see + [ethernet.md](ethernet.md#restricting-advertised-link-modes) for the + new model, the duplex × PMD mapping, and the `enable=false` escape + hatch for non-autoneg peers +- New `ethernet/mdi-x` boolean leaf to force the copper MDI/MDI-X pinout + (true = MDI-X, false = MDI, absent = Auto-MDIX). Needed on some PHYs + where Auto-MDIX stops working once auto-negotiation is disabled; see + [ethernet.md](ethernet.md#restricting-advertised-link-modes) +- 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 @@ -72,7 +102,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 @@ -176,7 +205,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 diff --git a/doc/bridging.md b/doc/bridging.md index 187cb980..3ba38052 100644 --- a/doc/bridging.md +++ b/doc/bridging.md @@ -73,8 +73,8 @@ admin@example:/config/interface/br0/> set bridge vlans vlan 20 tagged br0 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. diff --git a/doc/ethernet.md b/doc/ethernet.md index 8abe5b8f..c95c913f 100644 --- a/doc/ethernet.md +++ b/doc/ethernet.md @@ -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. - -
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](bridging.md#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.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 @@ -120,19 +76,23 @@ 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. +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. -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. +> [!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. @@ -149,20 +109,70 @@ 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. +List several PMDs to advertise all of them; auto-negotiation then settles +on the highest mode both ends support. > [!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. +> 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] -> 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. +> 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 diff --git a/doc/networking.md b/doc/networking.md index bbe10226..cb799a9d 100644 --- a/doc/networking.md +++ b/doc/networking.md @@ -47,7 +47,7 @@ other traffic would be bridged as usual. |----------|----------------------------|--------------------------------------------------------------| | [bridge](bridging.md) | infix-if-bridge | SW implementation of an IEEE 802.1Q bridge | | [ip](ip.md) | ietf-ip, infix-ip | IP address to the subordinate interface | -| [vlan](ethernet.md#vlan-interfaces) | infix-if-vlan | Capture all traffic belonging to a specific 802.1Q VID | +| [vlan](vlan.md) | infix-if-vlan | Capture all traffic belonging to a specific 802.1Q VID | | [lag](lag.md) | infix-if-lag | Link aggregation, static and IEEE 802.3ad (LACP) | | lo | ietf-interfaces | Software loopback interface | | [eth](ethernet.md#physical-ethernet-interfaces) | ieee802-ethernet-interface | Physical Ethernet device/port | diff --git a/doc/vlan.md b/doc/vlan.md new file mode 100644 index 00000000..687ecae2 --- /dev/null +++ b/doc/vlan.md @@ -0,0 +1,89 @@ +# VLAN Interfaces + +A VLAN interface is an interface stacked on top of another Linux interface +that filters traffic for a single 802.1Q VID. `tcpdump` on a VLAN interface +shows only frames matching that VID, compared to *all* VIDs when listening +on the lower-layer interface. + +![VLAN interface on top of Ethernet or Bridge interfaces](img/interface-vlan-variants.svg) + +This page covers VLAN interfaces stacked on Ethernet, on a VLAN-filtering +bridge, and on other VLAN interfaces. For VLAN handling *inside* a bridge +(port VIDs, tagged/untagged membership, pvid), see [VLAN Filtering +Bridge](bridging.md#vlan-filtering-bridge). + +## On Top of an Ethernet Interface + +A VLAN interface for VID 20 on top of an Ethernet interface `eth0` is by +convention named `eth0.20`. + +
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 `tag-type` defaults to `c-vlan` (802.1Q customer VLAN, EtherType 0x8100). +Set to `s-vlan` (802.1ad service VLAN, EtherType 0x88A8) to terminate an outer +S-Tag. + +> [!TIP] +> If you name your VLAN interface `foo0.N` or `vlanN`, where `N` is a +> number, the CLI infers the interface type automatically. Otherwise +> the type must be set explicitly. + +## On Top of a Bridge + +When the lower-layer interface is a VLAN-filtering bridge, the VLAN interface +gives the CPU an IP-addressable endpoint inside the bridged broadcast domain +for that VID. This pattern is named `vlanN` by convention. + +
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
+
+ +The bridge `br0` must have VLAN 10 configured with the bridge itself as a +tagged member. See [VLAN Filtering Bridge](bridging.md#vlan-filtering-bridge) +for the bridge-side configuration. + +## Stacked (Q-in-Q) + +VLAN interfaces can be stacked. A VLAN interface whose lower-layer is itself +a VLAN interface terminates the inner tag, leaving the outer tag for the +parent to handle. + +
admin@example:/> configure
+admin@example:/config/> edit interface eth0.10
+admin@example:/config/interface/eth0.10/> set vlan tag-type s-vlan
+admin@example:/config/interface/eth0.10/> leave
+admin@example:/config/> edit interface eth0.10.20
+admin@example:/config/interface/eth0.10.20/> show
+type vlan;
+vlan {
+  tag-type c-vlan;
+  id 20;
+  lower-layer-if eth0.10;
+}
+admin@example:/config/interface/eth0.10.20/> leave
+
+ +The summary view shows each VLAN row pointing at its immediate parent: + +
admin@example:/> show interface
+INTERFACE       PROTOCOL      STATE       DATA                  
+eth0.10         vlan          UP          vid: 10
+│               ipv4                      10.0.10.1/24 (static)
+└ eth0
+eth0.10.20      vlan          UP          vid: 20
+│               ipv4                      10.0.10.20/28 (static)
+└ eth0.10
+
diff --git a/mkdocs.yml b/mkdocs.yml index 9e92c10d..11769c7d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,7 @@ nav: - Bridging: bridging.md - Link Aggregation: lag.md - Ethernet Interfaces: ethernet.md + - VLAN Interfaces: vlan.md - IP Addressing: ip.md - Routing: routing.md - Firewall Configuration: firewall.md