peter/infix
1
0
Fork 0
mirror of https://github.com/kernelkit/infix.git synced 2026-07-22 01:13:00 +02:00
Code Issues Packages Projects Releases Wiki Activity

doc: add vlan.md, update ChangeLog for the branch

Browse Source 
Fix #1506: restore the VLAN interface documentation that was lost when
networking.md was split into per-topic pages.  Content adapted from the
v25.11.0 networking.md VLAN section, plus a new "Stacked (Q-in-Q)"
section showing `eth0.10.20`-style nesting and the layered `show
interface` rendering of the parent chain.

Update the interface-type table in networking.md to point at the new
vlan.md instead of the dangling ethernet.md#vlan-interfaces anchor.

ChangeLog: document the user-facing changes on this branch (YANG model
upgrade, layered show interface output, auto-negotation typo fix) and
the new VLAN documentation.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2026-05-27 20:53:30 +02:00
parent 4c17a79de6
commit c3d17586fd
6 changed files with 205 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/ChangeLog.md
+33 -4
View File
@@ -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
doc/bridging.md
+2 -2
View File
@@ -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.
doc/ethernet.md
+79 -69
View File
@@ -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
@@ -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/> <b>leave</b>
admin@example:/>
</code></pre>
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:
<pre class="cli"><code>admin@example:/config/interface/eth3/ethernet/> <b>set auto-negotiation enable false</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 full</b>
</code></pre>
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):
<pre class="cli"><code>admin@example:/config/interface/eth3/ethernet/> <b>set mdi-x false</b>
</code></pre>
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
doc/networking.md
+1 -1
View File
@@ -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 |
doc/vlan.md
+89
View File
@@ -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`.
<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 `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.
<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>
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.
<pre class="cli"><code>admin@example:/> <b>configure</b>
admin@example:/config/> <b>edit interface eth0.10</b>
admin@example:/config/interface/eth0.10/> <b>set vlan tag-type s-vlan</b>
admin@example:/config/interface/eth0.10/> <b>leave</b>
admin@example:/config/> <b>edit interface eth0.10.20</b>
admin@example:/config/interface/eth0.10.20/> <b>show</b>
type vlan;
vlan {
tag-type c-vlan;
id 20;
lower-layer-if eth0.10;
}
admin@example:/config/interface/eth0.10.20/> <b>leave</b>
</code></pre>
The summary view shows each VLAN row pointing at its immediate parent:
<pre class="cli"><code>admin@example:/> <b>show interface</b>
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
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
</code></pre>
mkdocs.yml
+1
View File
@@ -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