0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================
0004 DSA switch configuration from userspace
0005 =======================================
0006
0007 The DSA switch configuration is not integrated into the main userspace
0008 network configuration suites by now and has to be performed manualy.
0009
0010 .. _dsa-config-showcases:
0011
0012 Configuration showcases
0013 -----------------------
0014
0015 To configure a DSA switch a couple of commands need to be executed. In this
0016 documentation some common configuration scenarios are handled as showcases:
0017
0018 *single port*
0019 Every switch port acts as a different configurable Ethernet port
0020
0021 *bridge*
0022 Every switch port is part of one configurable Ethernet bridge
0023
0024 *gateway*
0025 Every switch port except one upstream port is part of a configurable
0026 Ethernet bridge.
0027 The upstream port acts as different configurable Ethernet port.
0028
0029 All configurations are performed with tools from iproute2, which is available
0030 at https://www.kernel.org/pub/linux/utils/net/iproute2/
0031
0032 Through DSA every port of a switch is handled like a normal linux Ethernet
0033 interface. The CPU port is the switch port connected to an Ethernet MAC chip.
0034 The corresponding linux Ethernet interface is called the master interface.
0035 All other corresponding linux interfaces are called slave interfaces.
0036
0037 The slave interfaces depend on the master interface being up in order for them
0038 to send or receive traffic. Prior to kernel v5.12, the state of the master
0039 interface had to be managed explicitly by the user. Starting with kernel v5.12,
0040 the behavior is as follows:
0041
0042 - when a DSA slave interface is brought up, the master interface is
0043 automatically brought up.
0044 - when the master interface is brought down, all DSA slave interfaces are
0045 automatically brought down.
0046
0047 In this documentation the following Ethernet interfaces are used:
0048
0049 *eth0*
0050 the master interface
0051
0052 *lan1*
0053 a slave interface
0054
0055 *lan2*
0056 another slave interface
0057
0058 *lan3*
0059 a third slave interface
0060
0061 *wan*
0062 A slave interface dedicated for upstream traffic
0063
0064 Further Ethernet interfaces can be configured similar.
0065 The configured IPs and networks are:
0066
0067 *single port*
0068 * lan1: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
0069 * lan2: 192.0.2.5/30 (192.0.2.4 - 192.0.2.7)
0070 * lan3: 192.0.2.9/30 (192.0.2.8 - 192.0.2.11)
0071
0072 *bridge*
0073 * br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
0074
0075 *gateway*
0076 * br0: 192.0.2.129/25 (192.0.2.128 - 192.0.2.255)
0077 * wan: 192.0.2.1/30 (192.0.2.0 - 192.0.2.3)
0078
0079 .. _dsa-tagged-configuration:
0080
0081 Configuration with tagging support
0082 ----------------------------------
0083
0084 The tagging based configuration is desired and supported by the majority of
0085 DSA switches. These switches are capable to tag incoming and outgoing traffic
0086 without using a VLAN based configuration.
0087
0088 *single port*
0089 .. code-block:: sh
0090
0091 # configure each interface
0092 ip addr add 192.0.2.1/30 dev lan1
0093 ip addr add 192.0.2.5/30 dev lan2
0094 ip addr add 192.0.2.9/30 dev lan3
0095
0096 # For kernels earlier than v5.12, the master interface needs to be
0097 # brought up manually before the slave ports.
0098 ip link set eth0 up
0099
0100 # bring up the slave interfaces
0101 ip link set lan1 up
0102 ip link set lan2 up
0103 ip link set lan3 up
0104
0105 *bridge*
0106 .. code-block:: sh
0107
0108 # For kernels earlier than v5.12, the master interface needs to be
0109 # brought up manually before the slave ports.
0110 ip link set eth0 up
0111
0112 # bring up the slave interfaces
0113 ip link set lan1 up
0114 ip link set lan2 up
0115 ip link set lan3 up
0116
0117 # create bridge
0118 ip link add name br0 type bridge
0119
0120 # add ports to bridge
0121 ip link set dev lan1 master br0
0122 ip link set dev lan2 master br0
0123 ip link set dev lan3 master br0
0124
0125 # configure the bridge
0126 ip addr add 192.0.2.129/25 dev br0
0127
0128 # bring up the bridge
0129 ip link set dev br0 up
0130
0131 *gateway*
0132 .. code-block:: sh
0133
0134 # For kernels earlier than v5.12, the master interface needs to be
0135 # brought up manually before the slave ports.
0136 ip link set eth0 up
0137
0138 # bring up the slave interfaces
0139 ip link set wan up
0140 ip link set lan1 up
0141 ip link set lan2 up
0142
0143 # configure the upstream port
0144 ip addr add 192.0.2.1/30 dev wan
0145
0146 # create bridge
0147 ip link add name br0 type bridge
0148
0149 # add ports to bridge
0150 ip link set dev lan1 master br0
0151 ip link set dev lan2 master br0
0152
0153 # configure the bridge
0154 ip addr add 192.0.2.129/25 dev br0
0155
0156 # bring up the bridge
0157 ip link set dev br0 up
0158
0159 .. _dsa-vlan-configuration:
0160
0161 Configuration without tagging support
0162 -------------------------------------
0163
0164 A minority of switches are not capable to use a taging protocol
0165 (DSA_TAG_PROTO_NONE). These switches can be configured by a VLAN based
0166 configuration.
0167
0168 *single port*
0169 The configuration can only be set up via VLAN tagging and bridge setup.
0170
0171 .. code-block:: sh
0172
0173 # tag traffic on CPU port
0174 ip link add link eth0 name eth0.1 type vlan id 1
0175 ip link add link eth0 name eth0.2 type vlan id 2
0176 ip link add link eth0 name eth0.3 type vlan id 3
0177
0178 # For kernels earlier than v5.12, the master interface needs to be
0179 # brought up manually before the slave ports.
0180 ip link set eth0 up
0181 ip link set eth0.1 up
0182 ip link set eth0.2 up
0183 ip link set eth0.3 up
0184
0185 # bring up the slave interfaces
0186 ip link set lan1 up
0187 ip link set lan2 up
0188 ip link set lan3 up
0189
0190 # create bridge
0191 ip link add name br0 type bridge
0192
0193 # activate VLAN filtering
0194 ip link set dev br0 type bridge vlan_filtering 1
0195
0196 # add ports to bridges
0197 ip link set dev lan1 master br0
0198 ip link set dev lan2 master br0
0199 ip link set dev lan3 master br0
0200
0201 # tag traffic on ports
0202 bridge vlan add dev lan1 vid 1 pvid untagged
0203 bridge vlan add dev lan2 vid 2 pvid untagged
0204 bridge vlan add dev lan3 vid 3 pvid untagged
0205
0206 # configure the VLANs
0207 ip addr add 192.0.2.1/30 dev eth0.1
0208 ip addr add 192.0.2.5/30 dev eth0.2
0209 ip addr add 192.0.2.9/30 dev eth0.3
0210
0211 # bring up the bridge devices
0212 ip link set br0 up
0213
0214
0215 *bridge*
0216 .. code-block:: sh
0217
0218 # tag traffic on CPU port
0219 ip link add link eth0 name eth0.1 type vlan id 1
0220
0221 # For kernels earlier than v5.12, the master interface needs to be
0222 # brought up manually before the slave ports.
0223 ip link set eth0 up
0224 ip link set eth0.1 up
0225
0226 # bring up the slave interfaces
0227 ip link set lan1 up
0228 ip link set lan2 up
0229 ip link set lan3 up
0230
0231 # create bridge
0232 ip link add name br0 type bridge
0233
0234 # activate VLAN filtering
0235 ip link set dev br0 type bridge vlan_filtering 1
0236
0237 # add ports to bridge
0238 ip link set dev lan1 master br0
0239 ip link set dev lan2 master br0
0240 ip link set dev lan3 master br0
0241 ip link set eth0.1 master br0
0242
0243 # tag traffic on ports
0244 bridge vlan add dev lan1 vid 1 pvid untagged
0245 bridge vlan add dev lan2 vid 1 pvid untagged
0246 bridge vlan add dev lan3 vid 1 pvid untagged
0247
0248 # configure the bridge
0249 ip addr add 192.0.2.129/25 dev br0
0250
0251 # bring up the bridge
0252 ip link set dev br0 up
0253
0254 *gateway*
0255 .. code-block:: sh
0256
0257 # tag traffic on CPU port
0258 ip link add link eth0 name eth0.1 type vlan id 1
0259 ip link add link eth0 name eth0.2 type vlan id 2
0260
0261 # For kernels earlier than v5.12, the master interface needs to be
0262 # brought up manually before the slave ports.
0263 ip link set eth0 up
0264 ip link set eth0.1 up
0265 ip link set eth0.2 up
0266
0267 # bring up the slave interfaces
0268 ip link set wan up
0269 ip link set lan1 up
0270 ip link set lan2 up
0271
0272 # create bridge
0273 ip link add name br0 type bridge
0274
0275 # activate VLAN filtering
0276 ip link set dev br0 type bridge vlan_filtering 1
0277
0278 # add ports to bridges
0279 ip link set dev wan master br0
0280 ip link set eth0.1 master br0
0281 ip link set dev lan1 master br0
0282 ip link set dev lan2 master br0
0283
0284 # tag traffic on ports
0285 bridge vlan add dev lan1 vid 1 pvid untagged
0286 bridge vlan add dev lan2 vid 1 pvid untagged
0287 bridge vlan add dev wan vid 2 pvid untagged
0288
0289 # configure the VLANs
0290 ip addr add 192.0.2.1/30 dev eth0.2
0291 ip addr add 192.0.2.129/25 dev br0
0292
0293 # bring up the bridge devices
0294 ip link set br0 up
0295
0296 Forwarding database (FDB) management
0297 ------------------------------------
0298
0299 The existing DSA switches do not have the necessary hardware support to keep
0300 the software FDB of the bridge in sync with the hardware tables, so the two
0301 tables are managed separately (``bridge fdb show`` queries both, and depending
0302 on whether the ``self`` or ``master`` flags are being used, a ``bridge fdb
0303 add`` or ``bridge fdb del`` command acts upon entries from one or both tables).
0304
0305 Up until kernel v4.14, DSA only supported user space management of bridge FDB
0306 entries using the bridge bypass operations (which do not update the software
0307 FDB, just the hardware one) using the ``self`` flag (which is optional and can
0308 be omitted).
0309
0310 .. code-block:: sh
0311
0312 bridge fdb add dev swp0 00:01:02:03:04:05 self static
0313 # or shorthand
0314 bridge fdb add dev swp0 00:01:02:03:04:05 static
0315
0316 Due to a bug, the bridge bypass FDB implementation provided by DSA did not
0317 distinguish between ``static`` and ``local`` FDB entries (``static`` are meant
0318 to be forwarded, while ``local`` are meant to be locally terminated, i.e. sent
0319 to the host port). Instead, all FDB entries with the ``self`` flag (implicit or
0320 explicit) are treated by DSA as ``static`` even if they are ``local``.
0321
0322 .. code-block:: sh
0323
0324 # This command:
0325 bridge fdb add dev swp0 00:01:02:03:04:05 static
0326 # behaves the same for DSA as this command:
0327 bridge fdb add dev swp0 00:01:02:03:04:05 local
0328 # or shorthand, because the 'local' flag is implicit if 'static' is not
0329 # specified, it also behaves the same as:
0330 bridge fdb add dev swp0 00:01:02:03:04:05
0331
0332 The last command is an incorrect way of adding a static bridge FDB entry to a
0333 DSA switch using the bridge bypass operations, and works by mistake. Other
0334 drivers will treat an FDB entry added by the same command as ``local`` and as
0335 such, will not forward it, as opposed to DSA.
0336
0337 Between kernel v4.14 and v5.14, DSA has supported in parallel two modes of
0338 adding a bridge FDB entry to the switch: the bridge bypass discussed above, as
0339 well as a new mode using the ``master`` flag which installs FDB entries in the
0340 software bridge too.
0341
0342 .. code-block:: sh
0343
0344 bridge fdb add dev swp0 00:01:02:03:04:05 master static
0345
0346 Since kernel v5.14, DSA has gained stronger integration with the bridge's
0347 software FDB, and the support for its bridge bypass FDB implementation (using
0348 the ``self`` flag) has been removed. This results in the following changes:
0349
0350 .. code-block:: sh
0351
0352 # This is the only valid way of adding an FDB entry that is supported,
0353 # compatible with v4.14 kernels and later:
0354 bridge fdb add dev swp0 00:01:02:03:04:05 master static
0355 # This command is no longer buggy and the entry is properly treated as
0356 # 'local' instead of being forwarded:
0357 bridge fdb add dev swp0 00:01:02:03:04:05
0358 # This command no longer installs a static FDB entry to hardware:
0359 bridge fdb add dev swp0 00:01:02:03:04:05 static
0360
0361 Script writers are therefore encouraged to use the ``master static`` set of
0362 flags when working with bridge FDB entries on DSA switch interfaces.
