Skip to content

Commit 80e7cfa

Browse files
troglobittroglobit
committed
doc: add vlan.md, update ChangeLog for the branch
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>
1 parent 32b7dfd commit 80e7cfa

6 files changed

Lines changed: 114 additions & 54 deletions

File tree

‎doc/ChangeLog.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,36 @@ All notable changes to the project are documented in this file.
1010

1111
- Upgrade Linux kernel to 6.18.32 (LTS)
1212
- Upgrade FRR to 10.5.4
13-
- Add support for [Acer Connect Vero W6m][AcerConnectVero], a COTS home router,
14-
based upon the same hardware as [Banana Pi BPI-R3][BPI-R3], but
13+
- Add support for [Acer Connect Vero W6m][AcerConnectVero], a low-cost COTS
14+
home router, based on the same hardware as [Banana Pi BPI-R3][BPI-R3], but
1515
with a Wi-Fi 6E (6 GHz band) chip.
1616
- Add configurable channel-width in Wi-Fi configuration.
17+
- Upgrade `ieee802-ethernet-interface` YANG model to revision 2025-09-10 (IEEE
18+
Std 802.3.2-2025), adding the standard `phy-type` and `pmd-type` operational
19+
leaves. Speed is now exposed via `ietf-interfaces:speed` (bps, RFC 8343);
20+
the now obsolete `eth:speed` is no longer returned
21+
- Rework `show interface` summary output as layered protocol rows. When a
22+
port has link, a physical-medium row (e.g. `1000baseT`, `10GbaseLR`) appears
23+
above the `ethernet` row. VLAN, GRE, VXLAN and WiFi interfaces likewise get
24+
one row per protocol layer, with type-specific data on each (`vid:`,
25+
`remote:`, `vni:`, `station ssid:`, etc.), issue #530
1726

1827
### Fixes
1928

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

42+
[BPI-R3]: https://docs.banana-pi.org/en/BPI-R3/BananaPi_BPI-R3
2843
[AcerConnectVero]: ../board/aarch64/acer-connect-vero-w/
2944

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

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

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

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

182196
[v26.01.0][] - 2026-02-03

‎doc/bridging.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,8 +73,8 @@ admin@example:/config/interface/br0/> <b>set bridge vlans vlan 20 tagged br0</b>
7373
</code></pre>
7474

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

7979
> [!NOTE]
8080
> In some use-cases only a single management VLAN on the bridge is used.

‎doc/ethernet.md‎

Lines changed: 3 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,8 @@
11
# Ethernet Interfaces
22

3-
This document covers VLAN interfaces, physical Ethernet interfaces,
4-
and virtual Ethernet (VETH) pairs.
5-
6-
7-
## VLAN Interfaces
8-
9-
Creating a VLAN can be done in many ways. This section assumes VLAN
10-
interfaces created atop another Linux interface. E.g., the VLAN
11-
interfaces created on top of the Ethernet interface or bridge in the
12-
picture below.
13-
14-
![VLAN interface on top of Ethernet or Bridge interfaces](img/interface-vlan-variants.svg)
15-
16-
A VLAN interface is basically a filtering abstraction. When you run
17-
`tcpdump` on a VLAN interface you will only see the frames matching the
18-
VLAN ID of the interface, compared to *all* the VLAN IDs if you run
19-
`tcpdump` on the lower-layer interface.
20-
21-
<pre class="cli"><code>admin@example:/> <b>configure</b>
22-
admin@example:/config/> <b>edit interface eth0.20</b>
23-
admin@example:/config/interface/eth0.20/> <b>show</b>
24-
type vlan;
25-
vlan {
26-
tag-type c-vlan;
27-
id 20;
28-
lower-layer-if eth0;
29-
}
30-
admin@example:/config/interface/eth0.20/> <b>leave</b>
31-
</code></pre>
32-
33-
The example below assumes bridge br0 is already created, see [VLAN
34-
Filtering Bridge](bridging.md#vlan-filtering-bridge).
35-
36-
<pre class="cli"><code>admin@example:/> <b>configure</b>
37-
admin@example:/config/> <b>edit interface vlan10</b>
38-
admin@example:/config/interface/vlan10/> <b>set vlan id 10</b>
39-
admin@example:/config/interface/vlan10/> <b>set vlan lower-layer-if br0</b>
40-
admin@example:/config/interface/vlan10/> <b>leave</b>
41-
</code></pre>
42-
43-
As conventions, a VLAN interface for VID 20 on top of an Ethernet
44-
interface *eth0* is named *eth0.20*, and a VLAN interface for VID 10 on
45-
top of a bridge interface *br0* is named *vlan10*.
46-
47-
> [!NOTE]
48-
> If you name your VLAN interface `foo0.N` or `vlanN`, where `N` is a
49-
> number, the CLI infers the interface type automatically.
3+
This document covers physical Ethernet interfaces and virtual Ethernet
4+
(VETH) pairs. For VLAN interfaces stacked on top of an Ethernet port
5+
or bridge, see [VLAN Interfaces](vlan.md).
506

517

528
## Physical Ethernet Interfaces

‎doc/networking.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ other traffic would be bridged as usual.
4747
|----------|----------------------------|--------------------------------------------------------------|
4848
| [bridge](bridging.md) | infix-if-bridge | SW implementation of an IEEE 802.1Q bridge |
4949
| [ip](ip.md) | ietf-ip, infix-ip | IP address to the subordinate interface |
50-
| [vlan](ethernet.md#vlan-interfaces) | infix-if-vlan | Capture all traffic belonging to a specific 802.1Q VID |
50+
| [vlan](vlan.md) | infix-if-vlan | Capture all traffic belonging to a specific 802.1Q VID |
5151
| [lag](lag.md) | infix-if-lag | Link aggregation, static and IEEE 802.3ad (LACP) |
5252
| lo | ietf-interfaces | Software loopback interface |
5353
| [eth](ethernet.md#physical-ethernet-interfaces) | ieee802-ethernet-interface | Physical Ethernet device/port |

‎doc/vlan.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# VLAN Interfaces
2+
3+
A VLAN interface is an interface stacked on top of another Linux interface
4+
that filters traffic for a single 802.1Q VID. `tcpdump` on a VLAN interface
5+
shows only frames matching that VID, compared to *all* VIDs when listening
6+
on the lower-layer interface.
7+
8+
![VLAN interface on top of Ethernet or Bridge interfaces](img/interface-vlan-variants.svg)
9+
10+
This page covers VLAN interfaces stacked on Ethernet, on a VLAN-filtering
11+
bridge, and on other VLAN interfaces. For VLAN handling *inside* a bridge
12+
(port VIDs, tagged/untagged membership, pvid), see [VLAN Filtering
13+
Bridge](bridging.md#vlan-filtering-bridge).
14+
15+
## On Top of an Ethernet Interface
16+
17+
A VLAN interface for VID 20 on top of an Ethernet interface `eth0` is by
18+
convention named `eth0.20`.
19+
20+
<pre class="cli"><code>admin@example:/> <b>configure</b>
21+
admin@example:/config/> <b>edit interface eth0.20</b>
22+
admin@example:/config/interface/eth0.20/> <b>show</b>
23+
type vlan;
24+
vlan {
25+
tag-type c-vlan;
26+
id 20;
27+
lower-layer-if eth0;
28+
}
29+
admin@example:/config/interface/eth0.20/> <b>leave</b>
30+
</code></pre>
31+
32+
The `tag-type` defaults to `c-vlan` (802.1Q customer VLAN, EtherType 0x8100).
33+
Set to `s-vlan` (802.1ad service VLAN, EtherType 0x88A8) to terminate an outer
34+
S-Tag.
35+
36+
> [!TIP]
37+
> If you name your VLAN interface `foo0.N` or `vlanN`, where `N` is a
38+
> number, the CLI infers the interface type automatically. Otherwise
39+
> the type must be set explicitly.
40+
41+
## On Top of a Bridge
42+
43+
When the lower-layer interface is a VLAN-filtering bridge, the VLAN interface
44+
gives the CPU an IP-addressable endpoint inside the bridged broadcast domain
45+
for that VID. This pattern is named `vlanN` by convention.
46+
47+
<pre class="cli"><code>admin@example:/> <b>configure</b>
48+
admin@example:/config/> <b>edit interface vlan10</b>
49+
admin@example:/config/interface/vlan10/> <b>set vlan id 10</b>
50+
admin@example:/config/interface/vlan10/> <b>set vlan lower-layer-if br0</b>
51+
admin@example:/config/interface/vlan10/> <b>leave</b>
52+
</code></pre>
53+
54+
The bridge `br0` must have VLAN 10 configured with the bridge itself as a
55+
tagged member. See [VLAN Filtering Bridge](bridging.md#vlan-filtering-bridge)
56+
for the bridge-side configuration.
57+
58+
## Stacked (Q-in-Q)
59+
60+
VLAN interfaces can be stacked. A VLAN interface whose lower-layer is itself
61+
a VLAN interface terminates the inner tag, leaving the outer tag for the
62+
parent to handle.
63+
64+
<pre class="cli"><code>admin@example:/> <b>configure</b>
65+
admin@example:/config/> <b>edit interface eth0.10</b>
66+
admin@example:/config/interface/eth0.10/> <b>set vlan tag-type s-vlan</b>
67+
admin@example:/config/interface/eth0.10/> <b>leave</b>
68+
admin@example:/config/> <b>edit interface eth0.10.20</b>
69+
admin@example:/config/interface/eth0.10.20/> <b>show</b>
70+
type vlan;
71+
vlan {
72+
tag-type c-vlan;
73+
id 20;
74+
lower-layer-if eth0.10;
75+
}
76+
admin@example:/config/interface/eth0.10.20/> <b>leave</b>
77+
</code></pre>
78+
79+
The summary view shows each VLAN row pointing at its immediate parent:
80+
81+
<pre class="cli"><code>admin@example:/> <b>show interface</b>
82+
<span class="header">INTERFACE PROTOCOL STATE DATA </span>
83+
eth0.10 vlan UP vid: 10
84+
│ ipv4 10.0.10.1/24 (static)
85+
└ eth0
86+
eth0.10.20 vlan UP vid: 20
87+
│ ipv4 10.0.10.20/28 (static)
88+
└ eth0.10
89+
</code></pre>

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ nav:
3333
- Bridging: bridging.md
3434
- Link Aggregation: lag.md
3535
- Ethernet Interfaces: ethernet.md
36+
- VLAN Interfaces: vlan.md
3637
- IP Addressing: ip.md
3738
- Routing: routing.md
3839
- Firewall Configuration: firewall.md

0 commit comments

Comments
 (0)