1.. SPDX-License-Identifier: GPL-2.0
2
3=======================================
4DSA switch configuration from userspace
5=======================================
6
7The DSA switch configuration is not integrated into the main userspace
8network configuration suites by now and has to be performed manualy.
9
10.. _dsa-config-showcases:
11
12Configuration showcases
13-----------------------
14
15To configure a DSA switch a couple of commands need to be executed. In this
16documentation some common configuration scenarios are handled as showcases:
17
18*single port*
19  Every switch port acts as a different configurable Ethernet port
20
21*bridge*
22  Every switch port is part of one configurable Ethernet bridge
23
24*gateway*
25  Every switch port except one upstream port is part of a configurable
26  Ethernet bridge.
27  The upstream port acts as different configurable Ethernet port.
28
29All configurations are performed with tools from iproute2, which is available
30at https://www.kernel.org/pub/linux/utils/net/iproute2/
31
32Through DSA every port of a switch is handled like a normal linux Ethernet
33interface. The CPU port is the switch port connected to an Ethernet MAC chip.
34The corresponding linux Ethernet interface is called the master interface.
35All other corresponding linux interfaces are called slave interfaces.
36
37The slave interfaces depend on the master interface being up in order for them
38to send or receive traffic. Prior to kernel v5.12, the state of the master
39interface had to be managed explicitly by the user. Starting with kernel v5.12,
40the behavior is as follows:
41
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.
46
47In this documentation the following Ethernet interfaces are used:
48
49*eth0*
50  the master interface
51
52*lan1*
53  a slave interface
54
55*lan2*
56  another slave interface
57
58*lan3*
59  a third slave interface
60
61*wan*
62  A slave interface dedicated for upstream traffic
63
64Further Ethernet interfaces can be configured similar.
65The configured IPs and networks are:
66
67*single port*
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)
71
72*bridge*
73  * br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
74
75*gateway*
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)
78
79.. _dsa-tagged-configuration:
80
81Configuration with tagging support
82----------------------------------
83
84The tagging based configuration is desired and supported by the majority of
85DSA switches. These switches are capable to tag incoming and outgoing traffic
86without using a VLAN based configuration.
87
88*single port*
89  .. code-block:: sh
90
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
95
96    # For kernels earlier than v5.12, the master interface needs to be
97    # brought up manually before the slave ports.
98    ip link set eth0 up
99
100    # bring up the slave interfaces
101    ip link set lan1 up
102    ip link set lan2 up
103    ip link set lan3 up
104
105*bridge*
106  .. code-block:: sh
107
108    # For kernels earlier than v5.12, the master interface needs to be
109    # brought up manually before the slave ports.
110    ip link set eth0 up
111
112    # bring up the slave interfaces
113    ip link set lan1 up
114    ip link set lan2 up
115    ip link set lan3 up
116
117    # create bridge
118    ip link add name br0 type bridge
119
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
124
125    # configure the bridge
126    ip addr add 192.0.2.129/25 dev br0
127
128    # bring up the bridge
129    ip link set dev br0 up
130
131*gateway*
132  .. code-block:: sh
133
134    # For kernels earlier than v5.12, the master interface needs to be
135    # brought up manually before the slave ports.
136    ip link set eth0 up
137
138    # bring up the slave interfaces
139    ip link set wan up
140    ip link set lan1 up
141    ip link set lan2 up
142
143    # configure the upstream port
144    ip addr add 192.0.2.1/30 dev wan
145
146    # create bridge
147    ip link add name br0 type bridge
148
149    # add ports to bridge
150    ip link set dev lan1 master br0
151    ip link set dev lan2 master br0
152
153    # configure the bridge
154    ip addr add 192.0.2.129/25 dev br0
155
156    # bring up the bridge
157    ip link set dev br0 up
158
159.. _dsa-vlan-configuration:
160
161Configuration without tagging support
162-------------------------------------
163
164A 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
166configuration.
167
168*single port*
169  The configuration can only be set up via VLAN tagging and bridge setup.
170
171  .. code-block:: sh
172
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
177
178    # For kernels earlier than v5.12, the master interface needs to be
179    # brought up manually before the slave ports.
180    ip link set eth0 up
181    ip link set eth0.1 up
182    ip link set eth0.2 up
183    ip link set eth0.3 up
184
185    # bring up the slave interfaces
186    ip link set lan1 up
187    ip link set lan2 up
188    ip link set lan3 up
189
190    # create bridge
191    ip link add name br0 type bridge
192
193    # activate VLAN filtering
194    ip link set dev br0 type bridge vlan_filtering 1
195
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
200
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
205
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
210
211    # bring up the bridge devices
212    ip link set br0 up
213
214
215*bridge*
216  .. code-block:: sh
217
218    # tag traffic on CPU port
219    ip link add link eth0 name eth0.1 type vlan id 1
220
221    # For kernels earlier than v5.12, the master interface needs to be
222    # brought up manually before the slave ports.
223    ip link set eth0 up
224    ip link set eth0.1 up
225
226    # bring up the slave interfaces
227    ip link set lan1 up
228    ip link set lan2 up
229    ip link set lan3 up
230
231    # create bridge
232    ip link add name br0 type bridge
233
234    # activate VLAN filtering
235    ip link set dev br0 type bridge vlan_filtering 1
236
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
242
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
247
248    # configure the bridge
249    ip addr add 192.0.2.129/25 dev br0
250
251    # bring up the bridge
252    ip link set dev br0 up
253
254*gateway*
255  .. code-block:: sh
256
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
260
261    # For kernels earlier than v5.12, the master interface needs to be
262    # brought up manually before the slave ports.
263    ip link set eth0 up
264    ip link set eth0.1 up
265    ip link set eth0.2 up
266
267    # bring up the slave interfaces
268    ip link set wan up
269    ip link set lan1 up
270    ip link set lan2 up
271
272    # create bridge
273    ip link add name br0 type bridge
274
275    # activate VLAN filtering
276    ip link set dev br0 type bridge vlan_filtering 1
277
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
283
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
288
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
292
293    # bring up the bridge devices
294    ip link set br0 up
295