VLAN on OpenWrt: swconfig, driver VLANs, and DSA

VLANs on OpenWrt are not just a matter of adding .106 to an interface name. First identify whether the device uses a legacy hardware switch, driver-created VLANs, or DSA; since the OpenWrt 21.02 transition, the syntax and port mapping can differ substantially. This guide keeps all three paths from the official documentation.¹

Warning: A wrong tagged/untagged state or CPU port can remove the entire LAN. Back up the configuration and keep a console path before editing /etc/config/network. Never copy a port map from another model.¹

VLAN, tagged, untagged, and off

OpenWrt supports IEEE 802.1Q and IEEE 802.1ad (QinQ). In the common router example, the internal switch uses VLAN 1 for LAN and VLAN 2 for WAN; the CPU receives both as tagged data while end-device ports are usually untagged. Tagged ports normally form trunks between switches or routers, while untagged ports normally connect end devices.¹

• Tagged on the CPU port means frames carry a VLAN tag to the CPU; the peer must understand VLANs.
• Untagged accepts untagged frames and removes the tag when sending them out; one untagged port has one VLAN ID and can use a PVID.
• Off means that VLAN does not reach the port.
• Traffic crossing the LAN/WAN boundary must pass through the CPU/firewall when the VLANs do not share external ports; a switch can also be configured to bypass the CPU.¹

Identify the hardware and driver

Read the model's hardware page first. On the router, inspect interfaces with:

1
2
3
4
5

# ls -l /sys/class/net
...
lrwxrwxrwx    1 root     root             0 Jul 25 14:10 eth0 -> ../../devices/pci0000:00/0000:00:09.0/net/eth0
lrwxrwxrwx    1 root     root             0 Jul 25 14:10 eth1 -> ../../devices/pci0000:00/0000:00:0a.0/net/eth1
lrwxrwxrwx    1 root     root             0 Jul 25 14:10 eth2 -> ../../devices/pci0000:00/0000:00:0b.0/net/eth2

A second source example for a device with one physical interface and switch-created VLANs is:

1
2
3
4
5

# ls -l /sys/class/net
...
lrwxrwxrwx    1 root     root             0 Jan 1 1970 eth0 -> ../../devices/platform/ag71xx.0/net/eth0
lrwxrwxrwx    1 root     root             0 Jul 21 22:13 eth0.1 -> ../../devices/virtual/net/eth0.1
lrwxrwxrwx    1 root     root             0 Jul 21 22:13 eth0.2 -> ../../devices/virtual/net/eth0.2

A single physical interface accompanied by eth0.1 and eth0.2 may indicate a VLAN-capable switch or driver VLANs. DSA exposes switch ports as independent interfaces; not every device migrated from swconfig to DSA. Because migration changes the configuration syntax, applying an old example to a DSA device can leave the network down.¹

Path 1: legacy swconfig hardware switch

This is the source's example for a system not using DSA. switch stores common properties, switch_vlan assigns VLANs to the switch device, and switch_port sets a PVID. A port with the t suffix is tagged; the example's CPU port is 5.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

config 'switch' 'eth0'
        option 'reset' '1'
        option 'enable_vlan' '1'

config 'switch_vlan' 'eth0_1'
        option 'device' 'eth0'
        option 'vlan' '1'
        option 'ports' '0 1 3t 5t'

config 'switch_vlan' 'eth0_2'
        option 'device' 'eth0'
        option 'vlan' '2'
        option 'ports' '2 4t 5t'

config 'switch_vlan' 'eth0_3'
        option 'device' 'eth0'
        option 'vlan' '3'
        option 'ports' '3t 4t'

config 'switch_port'
        option 'device' 'eth0'
        option 'port' '3'
        option 'pvid' '3'

In this example an untagged frame entering port 0 is assigned VLAN 1, leaves port 1 untagged, leaves port 3 and the CPU tagged, and appears to Linux as eth0.1. VLAN 2 traffic entering port 2 goes to port 4 and the CPU tagged and appears as eth0.2. An untagged port cannot carry several VLAN IDs at the same time.¹

Path 2: driver-level VLANs

On a device with one NIC, such as a CPE, a VLAN can be described with a parent interface and VLAN ID. The source allows explicit config device sections using type '8021q', ifname, vid, and name; type can be 8021q or 8021ad, while name, ifname, and vid are required.

Explicit VLAN 106 and 204 configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

config device
	option type '8021q'
	option ifname 'eth0'
	option vid '106'
	option name 'vlan1'

config device
	option type '8021q'
	option ifname 'eth0'
	option vid '204'
	option name 'vlan2'

config interface 'lan'
	option type 'bridge'
	option ifname 'vlan1'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

config interface 'wan'
	option ifname 'vlan2'
	option proto 'dhcp'

The equivalent shorthand lets netifd infer the parent and VID from dot notation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

config interface 'lan'
	option type 'bridge'
	option ifname 'eth0.106'
	option proto 'static'
	option ipaddr '192.168.1.1'
	option netmask '255.255.255.0'

config interface 'wan'
	option ifname 'eth0.204'
	option proto 'dhcp'

If a tagged frame arrives on eth1 without a corresponding VLAN interface, it may be dropped; untagged frames arrive on the parent interface as usual. When a VLAN interface is bridged with a non-VLAN interface, the kernel adds and removes tags at that boundary. This is separate from hardware-switch configuration.¹

Path 3: DSA on a one-port device

The following is the source's full working example. It creates br-lan, places VLAN 1 untagged on lan, places VLANs 2 and 3 tagged, and assigns iot to br-lan.2 and guest to br-lan.3. For WLAN to work, wireless networks must bridge to the correct iot or guest interface.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

config interface 'loopback'
        option ifname 'lo'
        option proto 'static'
        option ipaddr '127.0.0.1'
        option netmask '255.0.0.0'

config globals 'globals'
        option packet_steering '1'
        option ula_prefix 'fdfe:bdca:64ed::/48'

config device
        option name 'br-lan'
        option type 'bridge'
        list ports 'lan'

config bridge-vlan 'lan_vlan'
	option device 'br-lan'
	option vlan '1'
	list ports 'lan:u*'

config interface 'lan'
	option device 'br-lan.1'
	option proto 'dhcp'

config bridge-vlan
        option device 'br-lan'
        option vlan '2'
        list ports 'lan:t'

config interface 'iot'
        option device 'br-lan.2'
        option proto 'none'

config bridge-vlan
        option device 'br-lan'
        option vlan '3'
        list ports 'lan:t'

config interface 'guest'
        option device 'br-lan.3'
        option proto 'none'

Inspect the bridge and VLANs after reloading:

1
2
3
4
5
6
7
8

bridge name     bridge id               STP enabled     interfaces
br-lan          7fff.74acb915ff33       no              lan
                                                        wlan0
                                                        wlan1
                                                        lan.3
                                                        wlan0-1
                                                        lan.2
                                                        wlan1-1

If the supporting package is installed, inspect the VLAN table with:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

bridge v
port              vlan-id
lan               1 PVID Egress Untagged
                  2
                  3
br-lan            1
                  2
                  3
wlan0             1 PVID Egress Untagged
wlan1             1 PVID Egress Untagged
wlan0-1           2 PVID Egress Untagged
wlan1-1           3 PVID Egress Untagged

If bridge v is unavailable, the source notes that ip-full may be required. The DSA example also assumes another device provides DHCP for untagged LAN and tagged VLANs 2 and 3 on the same link; do not enable extra DHCP servers until the topology is understood.¹

Final checks

After every change, compare the physical port, VLAN ID, tag state, parent interface, bridge, and firewall zone. Test each segment with a wired client and an SSID, confirm the expected DHCP lease, and confirm that forbidden segments are not reachable. If the result is wrong, restore the backed-up /etc/config/network through the console; do not apply a complete file from another model.¹

Sources