1 .. SPDX-License-Identifier: GPL-2.0
3 =======================================
4 DSA switch configuration from userspace
5 =======================================
7 The DSA switch configuration is not integrated into the main userspace
8 network configuration suites by now and has to be performed manualy.
10 .. _dsa-config-showcases:
12 Configuration showcases
13 -----------------------
15 To configure a DSA switch a couple of commands need to be executed. In this
16 documentation some common configuration scenarios are handled as showcases:
19 Every switch port acts as a different configurable Ethernet port
22 Every switch port is part of one configurable Ethernet bridge
25 Every switch port except one upstream port is part of a configurable
27 The upstream port acts as different configurable Ethernet port.
29 All configurations are performed with tools from iproute2, which is available
30 at https://www.kernel.org/pub/linux/utils/net/iproute2/
32 Through DSA every port of a switch is handled like a normal linux Ethernet
33 interface. The CPU port is the switch port connected to an Ethernet MAC chip.
34 The corresponding linux Ethernet interface is called the master interface.
35 All other corresponding linux interfaces are called slave interfaces.
37 The slave interfaces depend on the master interface being up in order for them
38 to send or receive traffic. Prior to kernel v5.12, the state of the master
39 interface had to be managed explicitly by the user. Starting with kernel v5.12,
40 the behavior is as follows:
42 - when a DSA slave interface is brought up, the master interface is
43 automatically brought up.
44 - when the master interface is brought down, all DSA slave interfaces are
45 automatically brought down.
47 In this documentation the following Ethernet interfaces are used:
56 another slave interface
59 a third slave interface
62 A slave interface dedicated for upstream traffic
64 Further Ethernet interfaces can be configured similar.
65 The configured IPs and networks are:
68 * lan1: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
69 * lan2: 192.0.2.5/30 (192.0.2.4 - 192.0.2.7)
70 * lan3: 192.0.2.9/30 (192.0.2.8 - 192.0.2.11)
73 * br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
76 * br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
77 * wan: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
79 .. _dsa-tagged-configuration:
81 Configuration with tagging support
82 ----------------------------------
84 The tagging based configuration is desired and supported by the majority of
85 DSA switches. These switches are capable to tag incoming and outgoing traffic
86 without using a VLAN based configuration.
91 # configure each interface
92 ip addr add 192.0.2.1/30 dev lan1
93 ip addr add 192.0.2.5/30 dev lan2
94 ip addr add 192.0.2.9/30 dev lan3
96 # For kernels earlier than v5.12, the master interface needs to be
97 # brought up manually before the slave ports.
100 # bring up the slave interfaces
108 # For kernels earlier than v5.12, the master interface needs to be
109 # brought up manually before the slave ports.
112 # bring up the slave interfaces
118 ip link add name br0 type bridge
120 # add ports to bridge
121 ip link set dev lan1 master br0
122 ip link set dev lan2 master br0
123 ip link set dev lan3 master br0
125 # configure the bridge
126 ip addr add 192.0.2.129/25 dev br0
128 # bring up the bridge
129 ip link set dev br0 up
134 # For kernels earlier than v5.12, the master interface needs to be
135 # brought up manually before the slave ports.
138 # bring up the slave interfaces
143 # configure the upstream port
144 ip addr add 192.0.2.1/30 dev wan
147 ip link add name br0 type bridge
149 # add ports to bridge
150 ip link set dev lan1 master br0
151 ip link set dev lan2 master br0
153 # configure the bridge
154 ip addr add 192.0.2.129/25 dev br0
156 # bring up the bridge
157 ip link set dev br0 up
159 .. _dsa-vlan-configuration:
161 Configuration without tagging support
162 -------------------------------------
164 A minority of switches are not capable to use a taging protocol
165 (DSA_TAG_PROTO_NONE). These switches can be configured by a VLAN based
169 The configuration can only be set up via VLAN tagging and bridge setup.
173 # tag traffic on CPU port
174 ip link add link eth0 name eth0.1 type vlan id 1
175 ip link add link eth0 name eth0.2 type vlan id 2
176 ip link add link eth0 name eth0.3 type vlan id 3
178 # For kernels earlier than v5.12, the master interface needs to be
179 # brought up manually before the slave ports.
181 ip link set eth0.1 up
182 ip link set eth0.2 up
183 ip link set eth0.3 up
185 # bring up the slave interfaces
191 ip link add name br0 type bridge
193 # activate VLAN filtering
194 ip link set dev br0 type bridge vlan_filtering 1
196 # add ports to bridges
197 ip link set dev lan1 master br0
198 ip link set dev lan2 master br0
199 ip link set dev lan3 master br0
201 # tag traffic on ports
202 bridge vlan add dev lan1 vid 1 pvid untagged
203 bridge vlan add dev lan2 vid 2 pvid untagged
204 bridge vlan add dev lan3 vid 3 pvid untagged
206 # configure the VLANs
207 ip addr add 192.0.2.1/30 dev eth0.1
208 ip addr add 192.0.2.5/30 dev eth0.2
209 ip addr add 192.0.2.9/30 dev eth0.3
211 # bring up the bridge devices
218 # tag traffic on CPU port
219 ip link add link eth0 name eth0.1 type vlan id 1
221 # For kernels earlier than v5.12, the master interface needs to be
222 # brought up manually before the slave ports.
224 ip link set eth0.1 up
226 # bring up the slave interfaces
232 ip link add name br0 type bridge
234 # activate VLAN filtering
235 ip link set dev br0 type bridge vlan_filtering 1
237 # add ports to bridge
238 ip link set dev lan1 master br0
239 ip link set dev lan2 master br0
240 ip link set dev lan3 master br0
241 ip link set eth0.1 master br0
243 # tag traffic on ports
244 bridge vlan add dev lan1 vid 1 pvid untagged
245 bridge vlan add dev lan2 vid 1 pvid untagged
246 bridge vlan add dev lan3 vid 1 pvid untagged
248 # configure the bridge
249 ip addr add 192.0.2.129/25 dev br0
251 # bring up the bridge
252 ip link set dev br0 up
257 # tag traffic on CPU port
258 ip link add link eth0 name eth0.1 type vlan id 1
259 ip link add link eth0 name eth0.2 type vlan id 2
261 # For kernels earlier than v5.12, the master interface needs to be
262 # brought up manually before the slave ports.
264 ip link set eth0.1 up
265 ip link set eth0.2 up
267 # bring up the slave interfaces
273 ip link add name br0 type bridge
275 # activate VLAN filtering
276 ip link set dev br0 type bridge vlan_filtering 1
278 # add ports to bridges
279 ip link set dev wan master br0
280 ip link set eth0.1 master br0
281 ip link set dev lan1 master br0
282 ip link set dev lan2 master br0
284 # tag traffic on ports
285 bridge vlan add dev lan1 vid 1 pvid untagged
286 bridge vlan add dev lan2 vid 1 pvid untagged
287 bridge vlan add dev wan vid 2 pvid untagged
289 # configure the VLANs
290 ip addr add 192.0.2.1/30 dev eth0.2
291 ip addr add 192.0.2.129/25 dev br0
293 # bring up the bridge devices
296 Forwarding database (FDB) management
297 ------------------------------------
299 The existing DSA switches do not have the necessary hardware support to keep
300 the software FDB of the bridge in sync with the hardware tables, so the two
301 tables are managed separately (``bridge fdb show`` queries both, and depending
302 on whether the ``self`` or ``master`` flags are being used, a ``bridge fdb
303 add`` or ``bridge fdb del`` command acts upon entries from one or both tables).
305 Up until kernel v4.14, DSA only supported user space management of bridge FDB
306 entries using the bridge bypass operations (which do not update the software
307 FDB, just the hardware one) using the ``self`` flag (which is optional and can
312 bridge fdb add dev swp0 00:01:02:03:04:05 self static
314 bridge fdb add dev swp0 00:01:02:03:04:05 static
316 Due to a bug, the bridge bypass FDB implementation provided by DSA did not
317 distinguish between ``static`` and ``local`` FDB entries (``static`` are meant
318 to be forwarded, while ``local`` are meant to be locally terminated, i.e. sent
319 to the host port). Instead, all FDB entries with the ``self`` flag (implicit or
320 explicit) are treated by DSA as ``static`` even if they are ``local``.
325 bridge fdb add dev swp0 00:01:02:03:04:05 static
326 # behaves the same for DSA as this command:
327 bridge fdb add dev swp0 00:01:02:03:04:05 local
328 # or shorthand, because the 'local' flag is implicit if 'static' is not
329 # specified, it also behaves the same as:
330 bridge fdb add dev swp0 00:01:02:03:04:05
332 The last command is an incorrect way of adding a static bridge FDB entry to a
333 DSA switch using the bridge bypass operations, and works by mistake. Other
334 drivers will treat an FDB entry added by the same command as ``local`` and as
335 such, will not forward it, as opposed to DSA.
337 Between kernel v4.14 and v5.14, DSA has supported in parallel two modes of
338 adding a bridge FDB entry to the switch: the bridge bypass discussed above, as
339 well as a new mode using the ``master`` flag which installs FDB entries in the
344 bridge fdb add dev swp0 00:01:02:03:04:05 master static
346 Since kernel v5.14, DSA has gained stronger integration with the bridge's
347 software FDB, and the support for its bridge bypass FDB implementation (using
348 the ``self`` flag) has been removed. This results in the following changes:
352 # This is the only valid way of adding an FDB entry that is supported,
353 # compatible with v4.14 kernels and later:
354 bridge fdb add dev swp0 00:01:02:03:04:05 master static
355 # This command is no longer buggy and the entry is properly treated as
356 # 'local' instead of being forwarded:
357 bridge fdb add dev swp0 00:01:02:03:04:05
358 # This command no longer installs a static FDB entry to hardware:
359 bridge fdb add dev swp0 00:01:02:03:04:05 static
361 Script writers are therefore encouraged to use the ``master static`` set of
362 flags when working with bridge FDB entries on DSA switch interfaces.