DSA Mini-Tutorial

DSA stands for Distributed Switch Architecture and is the Linux kernel subsystem for network switches. Because upstream kernel development now uses DSA, the OpenWrt Project is implementing DSA to replace the earlier swconfig framework. Many new routers also use DSA drivers instead of swconfig drivers.

This DSA Mini-Tutorial explains how DSA works with OpenWrt, and how it is configured with the LuCI web interface and the uci configuration file at /etc/config/network.

(Note: DSA support does not affect wireless configuration in /etc/config/wireless. In particular the wireless config option ifname continues to be valid for specifying a custom name for a WiFi interface.)

If you are upgrading your OpenWrt device to 21.02 or later, you should read the Converting to DSA and Upgrading to OpenWrt 21.02.0 articles. There is also a very good Youtube video from onemarcfifty that talks about the theory of VLANs and describes the differences between OpenWrt 19.0x and 21.0x.

This page is a Work In Process. It contains requests for information from future editors. Specifically, it needs:

  • An example for a config file for wireless in Item 1 below
  • A discussion of configuring wireless devices and interfaces
  • Careful vetting of the information for Items 3 & 4 below

If you can contribute your knowledge, we would be pleased for the help.

NOTE: This section is under heavy revision (mid-September 2022). Please refer to the DSA Terminology conversation on the OpenWrt-devel mailing list for the latest information. http://lists.openwrt.org/pipermail/openwrt-devel/2022-September/thread.html

DSA distinguishes between interfaces and networks. * Interfaces (sometimes called “network interfaces” or “devices”) are the software names given to physical connections that convey bits/frames to other computers. They operate at layer 2 in the protocol stack and generally have a MAC address along with several other configurable parameters. (TRUE?) * Interfaces identify and configure hardware components of the device: individual Ethernet switch ports, wireless radios, USB networking devices, VLANs, or virtual ethernets. (TRUE?) * A bridge is an interface that groups several individual interfaces together so they can be treated as a single entity. A bridge functions like a separate unmanaged (hardware) switch, forwarding traffic between member ports as needed at the hardware level to maintain performance. Each interface can be a member of only a single bridge. (TRUE?) * Networks route IP packets and operate at layer 3 in the protocol stack. (TRUE?) * A network is associated with a single interface that sends/receives its packets. (TRUE?) * Networks get their IP address parameters by the choice of protocol: Static, DHCP, PPP, 6in4, Wireguard, OpenVPN, etc. (TRUE?) Naming Conventions: Interfaces are assigned a name like lan1, lan2, wan, wlan1, vlan1, etc. By convention, a bridge gets a prefix of br-, like br-lan. Networks by convention, have upper-case names, such as LAN, WAN, WG1, etc.

OpenWrt configuration facilities allow you to configure the ports of your device using either the LuCI web interface, or by editing /etc/config/network. The remainder of this document describes several common configurations:

  1. Bridging all LAN ports
  2. Multiple bridged networks
  3. Multiple networks using VLANs
  4. Multiple networks using VLAN tagging

NOTE: THE TERMINOLOGY FOR LuCI IS NOT ENTIRELY CONSISTENT WITH THE DEFINITIONS ABOVE. STAY TUNED AS THIS PAGE IS UPDATED.

In the initial (and very common) scenario, all LAN switch ports are bridged together into a single 'br-lan' device. OpenWrt configures that device with an IP protocol, address, etc. In this configuration, everything that's connected to those physical bridged ports can communicate with each other and the router itself.

Configuring the LuCI web interface for a Bridged LAN: The first image shows all the LAN ports (lan1 .. lan4) are part of a Bridge device named “br-lan”. The second image shows an interface (“LAN”) that incorporates the “br-lan” device and been assigned a static address 192.168.1.1.

To add a wireless device (such as wlan0), open Network → Wireless. Edit the Device Configuration section to select the proper radio channel etc. Edit the Interface Configuration section (third image) to select the desired interface (from the Network: dropdown) and the SSID, security mode, etc.

Configuration file for a Bridged LAN: The first half of the file below shows how the config device section groups the physical ports into a bridge device named 'br-lan'. The config interface 'lan' section then incorporates that 'br-lan' device, and sets its IP protocol type, address, etc. Need to add the configuration for wlan0 to this file.

# ... in /etc/config/network

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'

OpenWrt can set up its switch to group multiple ports together into different bridge interfaces so their traffic remains separate, even though devices are plugged into the same router. For example, it might be useful to set aside certain ports for “home use” and others for “office use”.

You need only create two bridge devices: one for home and one for office, and assign different ports to each. You then create separate interfaces, and assign different IP address ranges (“subnets”) to each of those bridge devices. For example, home devices might have addresses from the range 192.168.1.1 to 192.168.1.254, while the office devices will be 192.168.13.1 to 192.168.13.254. Devices plugged into the home ports will be able to communicate with each other, and the devices in the office ports can also talk together. But the “home” ports will not be able to communicate with “office” ports unless there is a routing or firewall rule to allow it.

Configuring the LuCI web interface for multiple bridged networks: The LuCI interface created two separate bridge devices - br-home with the first two lan ports, and office with the next two ports. Next, two interfaces are created:

  • HOME, that uses the br-home bridge device, and assigns the address range 192.168.1.1 to 192.168.1.254
  • OFFICE, that uses the office bridge device, and assigns the address range 192.168.13.1 to 192.168.13.254

Configuration file for multiple bridged LANs: Here's the same example in /etc/config/network. The first half of the file below shows how each config device section groups two physical ports into a bridge device named br-home and two more ports into office. The config interface 'home' section defines an interface that incorporates the br-home device, and sets its IP protocol type, address, etc. Similarly, the config interface 'office' section incorporates the office device, and sets its configuration.

# ... in /etc/config/network
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'

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

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'

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. This item needs careful vetting...

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'

Every interface should have a correctly configured firewall zone. However, if you want to only use layer 2 and not layer 3 routing on a VLAN (only switching, no traffic between VLANs), you can set the interface as unmanaged (option proto 'none'), in which case do not set a firewall zone for the interface.

Keep in mind, that at least one interface should have an address (static or DHCP) in order to connect to the device for administrative purposes. That interface must be associated with a firewall zone (or rules) to accept input.

Example, where VLAN 1, 2 and 3 are only used for switching and VLAN 1 can be used to connect to the device:

config/network

config device 'switch'
	option name 'switch'
	option type 'bridge'
	option macaddr 'REDACTED'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4'

config bridge-vlan 'lan_vlan'
	option device 'switch'
	option vlan '1'
	list ports 'lan1:u*'
	list ports 'lan4:t'

config bridge-vlan
	option device 'switch'
	option vlan '2'
	list ports 'lan1:u*'
	list ports 'lan4:t'

config bridge-vlan
	option device 'switch'
	option vlan '3'
	list ports 'lan3:u*'
	list ports 'lan4:t'

config interface 'lan'
	option proto 'dhcp'
	option device 'switch.1'
	
config interface 'iot'
	option proto 'none'
	option device 'switch.2'

config interface 'guest'
	option proto 'none'
	option device 'switch.3'

config/firewall

config defaults
	option syn_flood '1'
	option input 'ACCEPT'
	option output 'ACCEPT'
	option forward 'REJECT'

config zone
	option name 'lan'
	option input 'ACCEPT'
	option output 'ACCEPT'
	option forward 'ACCEPT'
	list network 'lan'

See Wikipedia - VLAN Hopping

  • If using separated VLANs, it is often recommended not to use VLAN 1 for any data networks. This is because VLAN 1 is often hardcoded as a default on a lot of networking equipment and is therefore more often used in attacks and prone to accidental misconfiguration.
  • It is also often recommended to change the native VLAN on all trunk ports to an unused VLAN ID to explicitly only allow tagged traffic on trunk ports. Note that some hardware doesn't allow to mix tagged with untagged VLAN on one port, so this method cannot be used on it.
  • Similarly, for added security any unused LAN ports can be also added (as u|*) to an unused VLAN ID.

As an example let's assume a setup where:

  • VLANS 10, 20 and 30 are used for seperated VLANs without any layer 3 routing
  • the ports lan1 and lan2 are trunked ports with all VLANs
  • port lan3 is only for untagged VLAN 1
  • port lan4 is unused
  • VLAN 90 is not used anywhere else and is only there for added security
+---------+-------+------+------+------+------+
| VLAN ID | Local | lan1 | lan2 | lan3 | lan4 |
+---------+-------+------+------+------+------+
|    10   |   X   |   t  |   t  |  u|* |   -  |
+---------+-------+------+------+------+------+
|    20   |   X   |   t  |   t  |   -  |   -  |
+---------+-------+------+------+------+------+
|    30   |   X   |   t  |   t  |   -  |   -  |
+---------+-------+------+------+------+------+
|    90   |       |  u|* |  u|* |   -  |  u|* |
+---------+-------+------+------+------+------+
config device 'switch'
	option name 'switch'
	option type 'bridge'
	option macaddr 'REDACTED'
	list ports 'lan1'
	list ports 'lan2'
	list ports 'lan3'
	list ports 'lan4'

config bridge-vlan 'lan_vlan'
	option device 'switch'
	option vlan '10'
	list ports 'lan1:t'
	list ports 'lan2:t'
	list ports 'lan3:u*'

config bridge-vlan
	option device 'switch'
	option vlan '20'
	list ports 'lan1:t'
	list ports 'lan2:t'

config bridge-vlan
	option device 'switch'
	option vlan '30'
	list ports 'lan1:t'
	list ports 'lan2:t'

config bridge-vlan
	option device 'switch'
	option vlan '90'
	list ports 'lan1:u*'
	list ports 'lan2:u*'
	list ports 'lan4:u*'
	option local '0'

config interface 'lan'
	option proto 'dhcp'
	option device 'switch.10'
	
config interface 'iot'
	option proto 'none'
	option device 'switch.20'

config interface 'guest'
	option proto 'none'
	option device 'switch.30'

Note: Because local is not checked for VLAN 90, OpenWrt won't even create a device for it and there should be no interface for it, unlike the other VLANs.

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2023/10/19 02:58
  • by saudiqbal