Mini tutorial for DSA network config

[rmilecki]

Update from 2021-05-31:

• Option ifname was renamed to device
• This tutorial is valid for 21.02-rc2 (or newer) and recent snapshots

Introduction

DSA stands for Distributed Switch Architecture and is Linux kernel subsystem for network switches. It's an upstream replacement for OpenWrt's swconfig framework and many new routers use DSA drivers instead of swconfig drivers.

In DSA each switch port is a separated Linux interface. It means ip / ifconfig command will show interfaces like lan1, lan2, wan, etc.

DSA switch ports can be used as standalone interfaces (common solution for WAN) or can be bridged using Linux bridge interface. In the later case switch will still be able to route traffic on the hardware level so it won't affect performance.

Each port can be part of maximum of one bridge only.

Simple ports bridging

In the simplest scenario switch ports are simply bridged using Linux bridge interface and OpenWrt configures that interface with an IP protocol.

In such case all devices connected to bridged ports can communicate each other and router itself.

Example:

config device
	option name 'br-lan'
	option type 'bridge'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4'

config interface 'lan'
	option device 'br-lan'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

Multiple networks (using bridges)

A switch can be setup to group selected ports into separated networks by using multiple bridge interfaces. With separated firewall zones devices connected to different port groups won't be able to communicate each other.

Example:

config device
	option name 'br-home'
	option type 'bridge'
	list ports 'lan1'
	list ports 'lan2'

config device
	option name 'office'
	option type 'bridge'
	list ports 'lan3'
	list ports 'lan4'

config interface 'home'
	option device 'br-home'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

config interface 'office'
	option device 'office'
	option proto 'static'
	option ipaddr '192.168.13.1'
	option netmask '255.255.255.0'

Multiple networks (using VLANs)

Ports can also be separated (grouped) using single bridge with multiple VLANs. That requires assigning interfaces to correct software VLANs.

Example:

config device
	option name 'br-lan'
	option type 'bridge'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4'

config bridge-vlan
	option device 'br-lan'
	option vlan '1'
	list ports 'lan1'
	list ports 'lan2'

config bridge-vlan
	option device 'br-lan'
	option vlan '2'
	list ports 'lan3'
	list ports 'lan4'

config interface 'home'
	option device 'br-lan.1'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

config interface 'office'
	option device 'br-lan.2'
	option proto 'static'
	option ipaddr '192.168.13.1'
	option netmask '255.255.255.0'

VLAN tagged traffic

With proper bridge VLAN configuration it's also possible for selected port to use VLAN tagged traffic. It also requires assigning OpenWrt interface to the correct software VLAN.

Example:

Port lan4 uses tagged packets for VLAN 1 and has PVID 2.

config device
	option name 'br-lan'
	option type 'bridge'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4'

config bridge-vlan
	option device 'br-lan'
	option vlan '1'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4:t'

config bridge-vlan
	option device 'br-lan'
	option vlan '2'
	list ports 'lan4:u*'

config interface 'lan'
	option device 'br-lan.1'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

[rsalvaterra]

Outstanding guide, thanks, @rmilecki! Like I said on IRC, the only thing missing is how to specify a PVID. Add that, and it will be perfect!

[cesarvog]

Excelent Guide. Thanks for taking the time to share this with us non-developers. It makes everything much, much clearer.

[Borromini]

Thanks a lot for your time and code @rmilecki

[tmomas]

Would be well worth including it in the wiki!

[anomeome]

For the CLI orientated, patch is a useful addition to ones build.

[flygarn12]

Maybe this should be pinned at the top regarding the high pressure of never ending DSA questions in the forum right now, at least pinned at the top until the user guide get updated.

If it’s not pinned it will just be buried down in the forum stream.

[Sylvan]

Do I really need to create an extra bridge device myself?
So far I have entered the ports directly at the interface and as I understood it, a corresponding bridge is automatically created:

config interface 'lan'
        [...]
        option ifname 'lan1 lan2 wan'
        option type 'bridge'

config interface 'office'
        [...]
        option ifname 'lan1.3 lan2.3 wan.3'
        option type 'bridge'

Everything seems to work as it should in my case - untagged ends up in lan and everything with VLAN ID 3 ends up in office.
Is there a problem if I configure it this way?

[hnyman]

Hmm....
I think that this guide is currently only right for master, but not for the forthcoming 21.02 release, right? Your brand new port / bridge device related config changes have not been backported to 21.02.

If I have understood the situation right, you might clearly specify in your message that to which branches this guide applies.

Ps. And as 21.02 does not know about the new config syntax, it will be impossible to downgrade from up-to-date master to a 21.02 build is DSA if used, right?

[flygarn12]

21.02 has full DSA support if your device has DSA support. But 21.02 doesn’t have LUCI DSA config support.
But there are no problem moving config files from master snapshot back and forth to 21.02 (done that my self). The problem is actually going back to 19.07 if you have installed 21.02.

[Sylvan]

I have my config running on 21.02 rc1.
So you mean in future releases I can no longer use this but must configure it as in the tutorial here? - I hope not....

[hnyman]

@flygarn12

But there are no problem moving config files from master snapshot back and forth to 21.02 (done that my self

After yesterday's config changes in master?
Really?

(It has worked earlier, sure. But I doubt that it works from the current master f716c30241 or later)

[rmilecki]

@Sylvan

Do I really need to create an extra bridge device myself?
So far I have entered the ports directly at the interface and as I understood it, a corresponding bridge is automatically created:

Yes. UCI sections interface are meant for layer 3 configuration. Bridge works in layer 2 and should use UCI section device.
What you are using is legacy (deprecated) syntax that the recent LuCI doesn't support anymore and is planned to be dropped at some point.
Related commits:

• base-files: generate "device" UCI type section for bridge
• luci-mod-network: drop support for adding legacy bridges
• luci-mod-network: drop support for editing legacy bridges
• luci-mod-network: use "ports" option for setting bridge ports

Patch that will switch all old syntax users at some point:
[PATCH] base-files: migrate old UCI network sections defining bridges

[rmilecki]

@tmomas

Would be well worth including it in the wiki!

Absolutely. It was just easier for me to sit down and write quickly this tutorial without integrating it into existing wiki content. I'll work on that later.

[alexrebell]

Tell me, please, and how to make the bridge between the local and wireless interface now?
Thank you

[Sylvan]

@rmilecki

What you are using is legacy (deprecated) syntax that the recent LuCI doesn't support anymore and is planned to be dropped at some point.

Nice trick: Make the file configuration much more cumbersome than before to push people towards LUci.

But of course - I can understand the reasoning behind it - I still found the previous solution pretty smart and now it sadly becomes significantly more cumbersome.

[Borromini]

DSA already greatly complicated UCI configuration so I'm happy people decided to sanitise and document it.

[rsalvaterra]

@Sylvan

Make the file configuration much more cumbersome than before to push people towards LUci.

Why? Cumbersome is to mix both L2 and L3 configuration. It doesn't make sense, they're independent layers and should be treated as such. The new DSA configuration in UCI is, in fact, a lot similar in intent to the old swconfig, with a more explicit structure. The extra verboseness makes it largely self-documenting (the exception being the PVID configuration which, granted, is rather cryptic).

[Sylvan]

Yes - for my sake, this corresponds to pure doctrine.
In my practice, however, the configuration of a new network is always a combination of L2 and L3.
And even if I am always aware that I am working on several layers of a theoretical concept at the same time, I have no noticeable disadvantage when I do this combined in one place.

What is the bad consequence if I also set layer2 settings in the interface section?

9 additional lines with named links to other places in the configuration file with completely the same final result do not promote clarity for me.

A solution which respects the layer concept and could be configured similarly elegantly as the past ifname solution would have been dearer to me simply than the construct which was presented here. And yes - the concept is quite clear to me - but so was the previous one.

But I am neither a network expert nor an active developer - this is just the view of a normal end user.
So consider my limited knowledge and inability to fully assess the consequences of such a decision. I therefore plead for nothing and ask no one to reconsider the concept - I only regret that the solution, which has been elegant for me so far, is to be abolished.