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

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

[Thomas Ellmenreich]

Adjusted some of the details related to VLAN setups, both with the traditional
methods as well as the SDN setup.

- Removed an outdated example and added more information to the remaining
  examples. First, by adding the VLAN interface on the bridge and then
  showcasing that VLAN tags can be set in the guest network configurations.

- Noted that, for setups using a bond connected to VLAN aware bridge,
  creating VLAN interfaces should be done on the bridge and not the bond.

- Added SDN as a possible way to configure VLANs for guests.

Suggested-by: Stefan Hanreich <s.hanreich@proxmox.com>
Signed-off-by: Thomas Ellmenreich <t.ellmenreich@proxmox.com>
---
As discussed off list, some improvements to the VLAN related documentation
were necessary. Not sure if my wording is correct as is.

 pve-network.adoc | 67 ++++++++++++++++++++----------------------------
 pvesdn.adoc      |  2 +-
 2 files changed, 29 insertions(+), 40 deletions(-)

diff --git a/pve-network.adoc b/pve-network.adoc
index 2b3e664..a00956a 100644
--- a/pve-network.adoc
+++ b/pve-network.adoc
@@ -637,6 +637,11 @@ 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:*
+Aside from manually configuring the network stack, it is also possible to
+configure VLANs by creating a VNet in the SDN configuration. A local network
+interface with the same name is then available on each node. For more
+information, see xref:pvesdn_config_vnet[here].
 
 VLAN on the Host
 ^^^^^^^^^^^^^^^^
@@ -649,52 +654,34 @@ abstraction layers between itself and the physical NIC.
 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
 ----
 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
-
 auto vmbr0
 iface vmbr0 inet manual
         bridge-ports eno1
         bridge-stp off
         bridge-fd 0
-
-----
-
-.Example: Use VLAN 5 for the {pve} management IP with VLAN aware Linux bridge
-----
-auto lo
-iface lo inet loopback
-
-iface eno1 inet manual
-
+        bridge-vlan-aware yes
+        bridge-vids 2-4094
 
 auto vmbr0.5
 iface vmbr0.5 inet static
         address  10.10.10.2/24
         gateway  10.10.10.1
+----
 
-auto vmbr0
-iface vmbr0 inet manual
-        bridge-ports eno1
-        bridge-stp off
-        bridge-fd 0
-        bridge-vlan-aware yes
-        bridge-vids 2-4094
+Guests can then reference the VLAN tag directly in their network
+configuration. Compared to an SDN-configured solution, this has the
+disadvantage that specific VLANs cannot be named, but the advantage that
+each VLAN does not have to be configured individually.
+
+----
+net0: name=eth0,bridge=vmbr0,tag=5,...
 ----
 
 The next example is the same setup but a bond is used to
@@ -716,24 +703,26 @@ iface bond0 inet manual
       bond-mode 802.3ad
       bond-xmit-hash-policy layer2+3
 
-iface bond0.5 inet manual
-
-auto vmbr0v5
-iface vmbr0v5 inet static
-        address  10.10.10.2/24
-        gateway  10.10.10.1
-        bridge-ports bond0.5
-        bridge-stp off
-        bridge-fd 0
-
 auto vmbr0
 iface vmbr0 inet manual
         bridge-ports bond0
+        bridge-vlan-aware yes
+        bridge-vids 2-4094
         bridge-stp off
         bridge-fd 0
 
+auto vmbr0.5
+iface vmbr0.5 inet static
+        address 10.10.10.2/24
+        gateway 10.10.10.1
+
 ----
 
+Please note that when using a bond with a VLAN-aware bridge, the VLAN
+interface should be created on the bridge and not on the bond. Configuring the
+VLAN interface on the bond can cause issues for the traffic arriving on
+the bond.
+
 Disabling IPv6 on the Node
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/pvesdn.adoc b/pvesdn.adoc
index 3fd3533..a515a13 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 brige should be VLAN aware to work properly.
 
 
 [[pvesdn_zone_plugin_qinq]]
-- 
2.47.3

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

[Stefan Hanreich]

Thanks for looking into this!

On 10/1/26 3:08 PM, Thomas Ellmenreich wrote:
> Adjusted some of the details related to VLAN setups, both with the traditional
> methods as well as the SDN setup.
> 
> - Removed an outdated example and added more information to the remaining
>   examples. First, by adding the VLAN interface on the bridge and then
>   showcasing that VLAN tags can be set in the guest network configurations.
> 
> - Noted that, for setups using a bond connected to VLAN aware bridge,
>   creating VLAN interfaces should be done on the bridge and not the bond.
> 
> - Added SDN as a possible way to configure VLANs for guests.
> 
> Suggested-by: Stefan Hanreich <s.hanreich@proxmox.com>
> Signed-off-by: Thomas Ellmenreich <t.ellmenreich@proxmox.com>
> ---
> As discussed off list, some improvements to the VLAN related documentation
> were necessary. Not sure if my wording is correct as is.
> 
>  pve-network.adoc | 67 ++++++++++++++++++++----------------------------
>  pvesdn.adoc      |  2 +-
>  2 files changed, 29 insertions(+), 40 deletions(-)
> 
> diff --git a/pve-network.adoc b/pve-network.adoc
> index 2b3e664..a00956a 100644
> --- a/pve-network.adoc
> +++ b/pve-network.adoc
> @@ -637,6 +637,11 @@ 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:*
> +Aside from manually configuring the network stack, it is also possible to
> +configure VLANs by creating a VNet in the SDN configuration. A local network
> +interface with the same name is then available on each node. For more
> +information, see xref:pvesdn_config_vnet[here].

Maybe something like this would be better:

[..] it is also possible to configure VLANs in SDN by creating a VLAN zone on
the bridge and then create VNets for every VLAN tag. In this case, it is also
recommended to use a VLAN-aware bridge.

>  VLAN on the Host
>  ^^^^^^^^^^^^^^^^
> @@ -649,52 +654,34 @@ abstraction layers between itself and the physical NIC.
>  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
>  ----
>  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
> -
>  auto vmbr0
>  iface vmbr0 inet manual
>          bridge-ports eno1
>          bridge-stp off
>          bridge-fd 0
> -
> -----
> -
> -.Example: Use VLAN 5 for the {pve} management IP with VLAN aware Linux bridge
> -----
> -auto lo
> -iface lo inet loopback
> -
> -iface eno1 inet manual
> -
> +        bridge-vlan-aware yes
> +        bridge-vids 2-4094
>  
>  auto vmbr0.5
>  iface vmbr0.5 inet static
>          address  10.10.10.2/24
>          gateway  10.10.10.1
> +----
>  
> -auto vmbr0
> -iface vmbr0 inet manual
> -        bridge-ports eno1
> -        bridge-stp off
> -        bridge-fd 0
> -        bridge-vlan-aware yes
> -        bridge-vids 2-4094
> +Guests can then reference the VLAN tag directly in their network
> +configuration. Compared to an SDN-configured solution, this has the
> +disadvantage that specific VLANs cannot be named, but the advantage that
> +each VLAN does not have to be configured individually.
> +
> +----
> +net0: name=eth0,bridge=vmbr0,tag=5,...
>  ----
>  
>  The next example is the same setup but a bond is used to
> @@ -716,24 +703,26 @@ iface bond0 inet manual
>        bond-mode 802.3ad
>        bond-xmit-hash-policy layer2+3
>  
> -iface bond0.5 inet manual
> -
> -auto vmbr0v5
> -iface vmbr0v5 inet static
> -        address  10.10.10.2/24
> -        gateway  10.10.10.1
> -        bridge-ports bond0.5
> -        bridge-stp off
> -        bridge-fd 0
> -
>  auto vmbr0
>  iface vmbr0 inet manual
>          bridge-ports bond0
> +        bridge-vlan-aware yes
> +        bridge-vids 2-4094
>          bridge-stp off
>          bridge-fd 0
>  
> +auto vmbr0.5
> +iface vmbr0.5 inet static
> +        address 10.10.10.2/24
> +        gateway 10.10.10.1
> +
>  ----
>  
> +Please note that when using a bond with a VLAN-aware bridge, the VLAN
> +interface should be created on the bridge and not on the bond. Configuring the
> +VLAN interface on the bond can cause issues for the traffic arriving on
> +the bond.

Maybe we could make that a general warning? Configuring a VLAN on an interface, that
is member of a bridge, will "blackhole" all traffic of that VLAN on the bridge. 

>  Disabling IPv6 on the Node
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> diff --git a/pvesdn.adoc b/pvesdn.adoc
> index 3fd3533..a515a13 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 brige should be VLAN aware to work properly.
>  
>  
>  [[pvesdn_zone_plugin_qinq]]

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

[Thomas Ellmenreich]

On Thu Oct 1, 2026 at 5:14 PM CEST, Stefan Hanreich wrote:

[snip]

>> +Please note that when using a bond with a VLAN-aware bridge, the VLAN
>> +interface should be created on the bridge and not on the bond. Configuring the
>> +VLAN interface on the bond can cause issues for the traffic arriving on
>> +the bond.
>
> Maybe we could make that a general warning? Configuring a VLAN on an interface, that
> is member of a bridge, will "blackhole" all traffic of that VLAN on the bridge. 

[snip]

As discussed off list, it might make sense to create a new section,
called something like "Common Issues", "Troubleshooting" or "Pitfalls"
and mention this piece of information there.

I'm quite convinced of this approach, so are there any other "Common
Issues" with VLAN's that we should mention there?