Cumulus Linux VLAN-Aware Bridge Configuration Guide

Cumulus Linux does not configure VLANs the way a traditional switch OS does. Instead of creating a separate bridge per VLAN, it uses the kernel bridge with vlan_filtering enabled — a single VLAN-aware bridge that carries every VLAN as a member, with tag and untag operations applied per port. NVIDIA recommends this model because it scales to large Layer 2 fabrics without creating hundreds of bridge devices, and because one bridge means one instance of spanning tree across the whole access layer. This guide covers the model, the access/trunk configuration patterns, the SVI setup for inter-VLAN routing, and how to verify what the kernel actually programmed.

Why VLAN-Aware Mode Instead of Multiple Bridges

In the older model each VLAN got its own bridge, and inter-VLAN traffic required a veth pair or routing between SVIs on separate bridges. VLAN-aware mode collapses all of that into one bridge: the bridge holds no IP address of its own, and each VLAN interface (SVI) is created on top of the bridge with an 802.1Q tag. The result is a configuration that maps one-to-one onto the physical topology and interoperates predictably with vendor switches using standard 802.1Q.

The practical differences you will notice:

• One bridge, one spanning tree instance — no per-VLAN tree explosion.
• Ports are never "in a VLAN"; they carry a VLAN list, and the bridge decides tag or untag per VLAN.
• Bond members, not the bond itself, are the bridge ports — this is a frequent source of confusion.

Step 1 - Create the Bridge and Add Ports

With nvconfig on Cumulus 5.x, the bridge is defined as a single object and ports are attached as members. The example below puts swp1 through swp4 into a VLAN-aware bridge and leaves swp5 unused:

cumulus@leaf01:~$ nv set interface br_default type bridge
cumulus@leaf01:~$ nv set interface br_default bridge domain br_default type vlan-aware
cumulus@leaf01:~$ nv set interface swp1-4 bridge domain br_default
cumulus@leaf01:~$ nv config apply

nvconfig versus ifupdown2 syntax

On the older ifupdown2 model of Cumulus Linux 4.x, the equivalent lives in /etc/network/interfaces:

auto br_default
iface br_default
    bridge-ports swp1 swp2 swp3 swp4
    bridge-vlan-aware yes
    bridge-vids 10 20 30
    bridge-pvid 1
    mtu 9000

auto swp1
iface swp1

VLAN pruning on the bridge

The bridge-vids list defines which VLANs the bridge may carry. A port that receives a VLAN not in this list drops the frame, which is the intended pruning behaviour for a large fabric.

Step 2 - Configure Access and Trunk Ports

Access behaviour is expressed as "untagged VLAN X, no other VLANs":

cumulus@leaf01:~$ nv set interface swp1 bridge domain br_default access 10
cumulus@leaf01:~$ nv set interface swp2 bridge domain br_default access 20

Trunk behaviour is a VLAN list with a native (untagged) VLAN. In Cumulus, the untagged VLAN is set with untagged and the tagged VLANs with vlan:

cumulus@leaf01:~$ nv set interface swp3 bridge domain br_default untagged 1
cumulus@leaf01:~$ nv set interface swp3 bridge domain br_default vlan 10,20,30
cumulus@leaf01:~$ nv set interface swp4 bridge domain br_default vlan 10,20,30
cumulus@leaf01:~$ nv config apply

If a VLAN must be carried on a port but should not appear in the bridge's global VLAN database, mark it as a member of that port only. Conversely, to stop a VLAN from being forwarded anywhere, remove it from the bridge VLAN list rather than from individual ports.

Step 3 - Add SVIs for Inter-VLAN Routing

Each routed VLAN gets a VLAN interface on the bridge. The tag on the SVI is what makes the Linux host a router for that VLAN:

cumulus@leaf01:~$ nv set interface vlan10 type svi
cumulus@leaf01:~$ nv set interface vlan10 ip address 10.10.10.1/24
cumulus@leaf01:~$ nv set interface vlan20 type svi
cumulus@leaf01:~$ nv set interface vlan20 ip address 10.10.20.1/24
cumulus@leaf01:~$ nv config apply

On the 4.x model the same thing is expressed as an address on the bridge with a VLAN tag:

auto br_default.10
iface br_default.10
    address 10.10.10.1/24

auto br_default.20
iface br_default.20
    address 10.10.20.1/24

Once the SVI exists, enable IPv4 forwarding and make sure the kernel accepts traffic for the addresses it now owns — net.ipv4.ip_forward=1 in /etc/sysctl.d/.

Step 4 - Verify From the Kernel Up

Never trust the configuration alone on Cumulus; the useful verification is what the kernel bridge and the hardware datapath actually contain.

cumulus@leaf01:~$ bridge -c vlan show
cumulus@leaf01:~$ bridge link show
cumulus@leaf01:~$ ip -d link show br_default
cumulus@leaf01:~$ bridge fdb show | head -20
cumulus@leaf01:~$ nv show interface br_default
cumulus@leaf01:~$ ip -br addr

bridge -c vlan show is the single most useful command: it lists every port with the VLANs it carries and flags each as tagged, untagged, or pvid. If a VLAN is missing from a port, the configuration was not applied to the correct member — check that you configured the physical interface and not a bond, and that no switch upperlink is silently forcing a different VLAN list.

For forwarding verification, confirm MAC learning on the expected port, then test with a tagged capture:

cumulus@leaf01:~$ sudo tcpdump -i swp3 -e -n vlan

Operational Notes

• Bridge ports are the physical interfaces or bond members — setting bridge VLANs on a bond name alone will not work.
• Keep the bridge MTU at or above the desired L3 MTU so that tagged frames and VXLAN encapsulation are not silently dropped.
• Use bridge-vids (4.x) or the domain VLAN list (5.x) to prune VLANs globally; per-port membership should be the exception.
• Cumulus configurations are declarative and idempotent — apply with nv config apply rather than editing live kernel state, or the next reload reverts you.
• Because it is plain Linux underneath, every standard tool (ip, bridge, tcpdump, ethtool) works, which makes remote troubleshooting far easier than on a closed switch OS.

Related reading: our Linux VLAN tagging with ip link and 802.1Q guide, the Linux bonding 802.3ad LACP configuration article, and the SONiC VLAN configuration and verification guide.

原文链接：https://docs.nvidia.com/networking-ethernet-software/cumulus-linux-44/Layer-2/Ethernet-Bridging-VLANs/VLAN-aware-Bridge-Mode/