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 296Forwarding database (FDB) management 297------------------------------------ 298 299The existing DSA switches do not have the necessary hardware support to keep 300the software FDB of the bridge in sync with the hardware tables, so the two 301tables are managed separately (``bridge fdb show`` queries both, and depending 302on whether the ``self`` or ``master`` flags are being used, a ``bridge fdb 303add`` or ``bridge fdb del`` command acts upon entries from one or both tables). 304 305Up until kernel v4.14, DSA only supported user space management of bridge FDB 306entries using the bridge bypass operations (which do not update the software 307FDB, just the hardware one) using the ``self`` flag (which is optional and can 308be omitted). 309 310 .. code-block:: sh 311 312 bridge fdb add dev swp0 00:01:02:03:04:05 self static 313 # or shorthand 314 bridge fdb add dev swp0 00:01:02:03:04:05 static 315 316Due to a bug, the bridge bypass FDB implementation provided by DSA did not 317distinguish between ``static`` and ``local`` FDB entries (``static`` are meant 318to be forwarded, while ``local`` are meant to be locally terminated, i.e. sent 319to the host port). Instead, all FDB entries with the ``self`` flag (implicit or 320explicit) are treated by DSA as ``static`` even if they are ``local``. 321 322 .. code-block:: sh 323 324 # This command: 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 331 332The last command is an incorrect way of adding a static bridge FDB entry to a 333DSA switch using the bridge bypass operations, and works by mistake. Other 334drivers will treat an FDB entry added by the same command as ``local`` and as 335such, will not forward it, as opposed to DSA. 336 337Between kernel v4.14 and v5.14, DSA has supported in parallel two modes of 338adding a bridge FDB entry to the switch: the bridge bypass discussed above, as 339well as a new mode using the ``master`` flag which installs FDB entries in the 340software bridge too. 341 342 .. code-block:: sh 343 344 bridge fdb add dev swp0 00:01:02:03:04:05 master static 345 346Since kernel v5.14, DSA has gained stronger integration with the bridge's 347software FDB, and the support for its bridge bypass FDB implementation (using 348the ``self`` flag) has been removed. This results in the following changes: 349 350 .. code-block:: sh 351 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 360 361Script writers are therefore encouraged to use the ``master static`` set of 362flags when working with bridge FDB entries on DSA switch interfaces. 363