Documentation/networking/dsa/configuration.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================================
   4 DSA switch configuration from userspace
   5 =======================================
   6
   7 The DSA switch configuration is not integrated into the main userspace
   8 network configuration suites by now and has to be performed manualy.
   9
  10 .. _dsa-config-showcases:
  11
  12 Configuration showcases
  13 -----------------------
  14
  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:
  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
  29 All configurations are performed with tools from iproute2, which is available
  30 at https://www.kernel.org/pub/linux/utils/net/iproute2/
  31
  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.
  36
  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:
  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
  47 In 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
  64 Further Ethernet interfaces can be configured similar.
  65 The 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
  81 Configuration with tagging support
  82 ----------------------------------
  83
  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.
  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
 161 Configuration without tagging support
 162 -------------------------------------
 163
 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
 166 configuration.
 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
 296 Forwarding database (FDB) management
 297 ------------------------------------
 298
 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).
 304
 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
 308 be 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
 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``.
 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
 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.
 336
 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
 340 software bridge too.
 341
 342   .. code-block:: sh
 343
 344     bridge fdb add dev swp0 00:01:02:03:04:05 master static
 345
 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:
 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
 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.