Re: [PATCH pve-docs v2 1/1] network/sdn: update and clean up VLAN information

["Michael Köppl" <m.koeppl@proxmox.com>]

On Tue Oct 20, 2026 at 8:45 AM CEST, Thomas Ellmenreich wrote:

[snip]

> diff --git a/pve-network.adoc b/pve-network.adoc
> index 2b3e664..b1a598c 100644
> --- a/pve-network.adoc
> +++ b/pve-network.adoc
> @@ -637,6 +637,53 @@ completely done inside the guest and can not be influenced from the
>  outside. The benefit is that you can use more than one VLAN on a
>  single virtual NIC.
>
> +* *SDN configured VLAN:*
> +It is also possible to xref:pvesdn_config_vnet[configure VLANs in SDN] by
> +creating a VLAN zone on the bridge and then creating VNets for every VLAN tag.
> +In this case, it is also recommended to use a VLAN-aware bridge.
> +
> +.Example: SDN VLAN Zones with VLAN aware bridges

nit: VLAN-aware

> +
> +This is the preferred solution if users have a small amount of VLANs inside
> +their cluster. On every node, users should configure a VLAN-aware bridge with
> +the respective carrier for their VLANs:
> +
> +----
> +auto vmbr0
> +iface vmbr0 inet manual
> +        bridge-ports nic0

[snip]

>  VLAN on the Host
>  ^^^^^^^^^^^^^^^^
> @@ -644,63 +691,47 @@ VLAN on the Host
>  To allow host communication with an isolated network. It is possible
>  to apply VLAN tags to any network device (NIC, Bond, Bridge). In
>  general, you should configure the VLAN on the interface with the least
> -abstraction layers between itself and the physical NIC.
> +abstraction layers between itself and the physical NIC. But it would still
> +be best to configure the VLAN on a bridge instead of a bond or the NIC
> +directly to avoid some of the issues mentioned xref:vlan_common_issues[here].
>
>  For example, in a default configuration where you want to place
>  the host management address on a separate VLAN.
>
> -
> -.Example: Use VLAN 5 for the {pve} management IP with traditional Linux bridge
> +.Example: Use VLAN 5 for the {pve} management IP with VLAN aware Linux bridge

nit: VLAN-aware

>  ----
>  auto lo
>  iface lo inet loopback
>
>  iface eno1 inet manual
>
> -iface eno1.5 inet manual
> -
> -auto vmbr0v5
> -iface vmbr0v5 inet static
> -        address  10.10.10.2/24
> -        gateway  10.10.10.1
> -        bridge-ports eno1.5
> -        bridge-stp off
> -        bridge-fd 0

[snip]

> -auto vmbr0
> -iface vmbr0 inet manual
> -        bridge-ports eno1
> -        bridge-stp off
> -        bridge-fd 0
> -        bridge-vlan-aware yes
> -        bridge-vids 2-4094
> +----
> +net0: name=eth0,bridge=vmbr0,tag=5,...
>  ----
>
>  The next example is the same setup but a bond is used to
>  make this network fail-safe.
>
> -.Example: Use VLAN 5 with bond0 for the {pve} management IP with traditional Linux bridge
> +.Example: Use VLAN 5 with bond0 for the {pve} management IP with VLAN aware Linux bridge

nit: VLAN-aware

>  ----
>  auto lo
>  iface lo inet loopback
> @@ -716,24 +747,72 @@ iface bond0 inet manual
>        bond-mode 802.3ad
>        bond-xmit-hash-policy layer2+3
>
> -iface bond0.5 inet manual

[snip]

> +auto vmbr0.5
> +iface vmbr0.5 inet static
> +        address 10.10.10.2/24
> +        gateway 10.10.10.1
> +
>  ----
>
> +Troubleshooting
> +^^^^^^^^^^^^^^^
> +
> +There are some helpful commands that can be utilised when debugging such issues:

nit: usually US English, so "utilize". A quick grep also suggests we do
no use "utilise" anywhere.

> +
> +----
> +$ bridge -compressvlans vlan show
> +----
> +

[snip]

> +----
> +$ bridge fdb show
> +----
> +
> +This prints a list of the current forwarding database entries of all bridges.
> +The bridge decides how to forward a given packet based on this table. An entry
> +of the fdb generally looks like this:
> +
> +----
> +aa:aa:aa:d8:36:7c dev nic0 vlan 49 master vmbr0 permanent
> +----
> +
> +This means that packets arriving on vmbr0, that have VLAN Tag 49 set and
> +destination MAC address aa:aa:aa:d8:36:7c will get forwarded to the port nic0.

Is this correct? According to the docs [0], permanent is a synonym for
local. So wouldn't this mean that packages with this destination address
are NOT forwarded, but handled locally? Or am I misinterpreting this?

[0] https://www.man7.org/linux/man-pages/man8/bridge.8.html

> +
> +[[vlan_common_issues]]
> +Common Issues
> +^^^^^^^^^^^^^
> +
> +.Issue: Configuring VLAN on interface that is member of bridge
> +
> +It's not recommended to configure a VLAN on an interface that is a member of a
> +bridge. Doing so will "blackhole" all traffic of that VLAN on the bridge.
> +
> +.Issue: Limited number of tags when VLAN offloading to NIC
> +
> +Certain NIC's, only support VLAN offloading only for a reduced number of tags.

nit: "NICs"
nit: the comma should also be removed
nit: theres 2 "only"s

> +In these cases it is best to either reduce the VLAN tag range on the bridge or
> +disable offloading altogether. The exact problems that can arise depend on
> +the exact hardware used.
> +
>  Disabling IPv6 on the Node
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> diff --git a/pvesdn.adoc b/pvesdn.adoc
> index 3fd3533..8e40ab4 100644
> --- a/pvesdn.adoc
> +++ b/pvesdn.adoc
> @@ -251,7 +251,7 @@ the network segments.  This allows connectivity of VMs between different nodes.
>  VLAN zone configuration options:
>
>  Bridge:: The local bridge or OVS switch, already configured on *each* node that
> -  allows node-to-node connection.
> +  allows node-to-node connection. This bridge should be VLAN aware to work properly.

nit: VLAN-aware

>
>
>  [[pvesdn_zone_plugin_qinq]]