diff mbox series

[PATCHv3,net-next,05/10] docs: bridge: add STP doc

Message ID 20231128084943.637091-6-liuhangbin@gmail.com (mailing list archive)
State Superseded
Delegated to: Netdev Maintainers
Headers show
Series Doc: update bridge doc | expand

Checks

Context Check Description
netdev/series_format success Posting correctly formatted
netdev/codegen success Generated files up to date
netdev/tree_selection success Clearly marked for net-next
netdev/fixes_present success Fixes tag not required for -next series
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 8 this patch: 8
netdev/cc_maintainers warning 2 maintainers not CCed: linux-doc@vger.kernel.org corbet@lwn.net
netdev/build_clang success Errors and warnings before: 8 this patch: 8
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 8 this patch: 8
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 100 lines checked
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0

Commit Message

Hangbin Liu Nov. 28, 2023, 8:49 a.m. UTC
Add STP part for bridge document.

Signed-off-by: Hangbin Liu <liuhangbin@gmail.com>
---
 Documentation/networking/bridge.rst | 94 +++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

Comments

Stephen Hemminger Nov. 28, 2023, 10:48 p.m. UTC | #1
On Tue, 28 Nov 2023 16:49:38 +0800
Hangbin Liu <liuhangbin@gmail.com> wrote:

> +STP is a Layer 2 protocol that operates at the Data Link Layer of the OSI
> +model. It was originally developed as IEEE 802.1D and has since evolved into
> +multiple versions, including Rapid Spanning Tree Protocol (RSTP) and
> +`Multiple Spanning Tree Protocol (MSTP)
> +<https://lore.kernel.org/netdev/20220316150857.2442916-1-tobias@waldekranz.com/>`_.
> +

Last time I checked, IEEE folded RSTP into the standard in 2004.
https://en.wikipedia.org/wiki/IEEE_802.1D
Florian Fainelli Nov. 29, 2023, 4:21 a.m. UTC | #2
On 11/28/2023 12:49 AM, Hangbin Liu wrote:
> Add STP part for bridge document.
> 
> Signed-off-by: Hangbin Liu <liuhangbin@gmail.com>

Reviewed-by: Florian Fainelli <florian.fainelli@broadcom.com>
Hangbin Liu Nov. 29, 2023, 7:43 a.m. UTC | #3
On Tue, Nov 28, 2023 at 02:48:40PM -0800, Stephen Hemminger wrote:
> On Tue, 28 Nov 2023 16:49:38 +0800
> Hangbin Liu <liuhangbin@gmail.com> wrote:
> 
> > +STP is a Layer 2 protocol that operates at the Data Link Layer of the OSI
> > +model. It was originally developed as IEEE 802.1D and has since evolved into
> > +multiple versions, including Rapid Spanning Tree Protocol (RSTP) and
> > +`Multiple Spanning Tree Protocol (MSTP)
> > +<https://lore.kernel.org/netdev/20220316150857.2442916-1-tobias@waldekranz.com/>`_.
> > +

The STP was originally developed as IEEE 802.1D. So how about keep this part,

> 
> Last time I checked, IEEE folded RSTP into the standard in 2004.
> https://en.wikipedia.org/wiki/IEEE_802.1D

and add a new paragraph like:

The 802.1D-2004, removed the original Spanning Tree Protocol, instead
incorporating the Rapid Spanning Tree Protocol (RSTP). By 2014, all the
functionality defined by IEEE 802.1D has been incorporated into either
IEEE 802.1Q-2014 (Bridges and Bridged Networks) or IEEE 802.1AC (MAC Service
Definition). 802.1D is expected to be officially withdrawn in 2022.

Thanks
Hangbin
Stephen Hemminger Nov. 29, 2023, 3:10 p.m. UTC | #4
On Wed, 29 Nov 2023 15:43:24 +0800
Hangbin Liu <liuhangbin@gmail.com> wrote:

> On Tue, Nov 28, 2023 at 02:48:40PM -0800, Stephen Hemminger wrote:
> > On Tue, 28 Nov 2023 16:49:38 +0800
> > Hangbin Liu <liuhangbin@gmail.com> wrote:
> >   
> > > +STP is a Layer 2 protocol that operates at the Data Link Layer of the OSI
> > > +model. It was originally developed as IEEE 802.1D and has since evolved into
> > > +multiple versions, including Rapid Spanning Tree Protocol (RSTP) and
> > > +`Multiple Spanning Tree Protocol (MSTP)
> > > +<https://lore.kernel.org/netdev/20220316150857.2442916-1-tobias@waldekranz.com/>`_.
> > > +  
> 
> The STP was originally developed as IEEE 802.1D. So how about keep this part,
> 
> > 
> > Last time I checked, IEEE folded RSTP into the standard in 2004.
> > https://en.wikipedia.org/wiki/IEEE_802.1D  
> 
> and add a new paragraph like:
> 
> The 802.1D-2004, removed the original Spanning Tree Protocol, instead
> incorporating the Rapid Spanning Tree Protocol (RSTP). By 2014, all the
> functionality defined by IEEE 802.1D has been incorporated into either
> IEEE 802.1Q-2014 (Bridges and Bridged Networks) or IEEE 802.1AC (MAC Service
> Definition). 802.1D is expected to be officially withdrawn in 2022.
> 
> Thanks
> Hangbin

Looks good, I have some old code to modify in kernel STP to do RSTP
but porting is a lot of work (mostly testing).
Vladimir Oltean Nov. 29, 2023, 6:46 p.m. UTC | #5
On Wed, Nov 29, 2023 at 03:43:24PM +0800, Hangbin Liu wrote:
> 802.1D is expected to be officially withdrawn in 2022.

2022 is in the past.
Vladimir Oltean Nov. 29, 2023, 6:48 p.m. UTC | #6
On Tue, Nov 28, 2023 at 04:49:38PM +0800, Hangbin Liu wrote:
> +User space STP helper
> +---------------------
> +The user space STP helper *bridge-stp* is a program to control whether to use
> +user mode spanning tree. The ``/sbin/bridge-stp <bridge> <start|stop>`` is
> +called by the kernel when STP is enabled/disabled on a bridge
> +(via ``brctl stp <bridge> <on|off>`` or ``ip link set <bridge> type bridge
> +stp_state <0|1>``).  The kernel enables user_stp mode if that command returns
> +0, or enables kernel_stp mode if that command returns any other value.

Blank line between section title and content, just like everywhere else.
diff mbox series

Patch

diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst
index 5d6d3c0c15c1..9d07da681bc5 100644
--- a/Documentation/networking/bridge.rst
+++ b/Documentation/networking/bridge.rst
@@ -38,6 +38,100 @@  Bridge port netlink attributes
 .. kernel-doc:: include/uapi/linux/if_link.h
    :doc: Bridge port enum definition
 
+STP
+===
+
+The STP (Spanning Tree Protocol) implementation in the Linux bridge driver
+is a critical feature that helps prevent loops and broadcast storms in
+Ethernet networks by identifying and disabling redundant links. In a Linux
+bridge context, STP is crucial for network stability and availability.
+
+STP is a Layer 2 protocol that operates at the Data Link Layer of the OSI
+model. It was originally developed as IEEE 802.1D and has since evolved into
+multiple versions, including Rapid Spanning Tree Protocol (RSTP) and
+`Multiple Spanning Tree Protocol (MSTP)
+<https://lore.kernel.org/netdev/20220316150857.2442916-1-tobias@waldekranz.com/>`_.
+
+Bridge Ports and STP States
+---------------------------
+
+In the context of STP, bridge ports can be in one of the following states:
+  * Blocking: The port is disabled for data traffic and only listens for
+    BPDUs (Bridge Protocol Data Units) from other devices to determine the
+    network topology.
+  * Listening: The port begins to participate in the STP process and listens
+    for BPDUs.
+  * Learning: The port continues to listen for BPDUs and begins to learn MAC
+    addresses from incoming frames but does not forward data frames.
+  * Forwarding: The port is fully operational and forwards both BPDUs and
+    data frames.
+  * Disabled: The port is administratively disabled and does not participate
+    in the STP process. The data frames forwarding are also disabled.
+
+Root Bridge and Convergence
+---------------------------
+
+In the context of networking and Ethernet bridging in Linux, the root bridge
+is a designated switch in a bridged network that serves as a reference point
+for the spanning tree algorithm to create a loop-free topology.
+
+Here's how the STP works and root bridge is chosen:
+  1. Bridge Priority: Each bridge running a spanning tree protocol, has a
+     configurable Bridge Priority value. The lower the value, the higher the
+     priority. By default, the Bridge Priority is set to a standard value
+     (e.g., 32768).
+  2. Bridge ID: The Bridge ID is composed of two components: Bridge Priority
+     and the MAC address of the bridge. It uniquely identifies each bridge
+     in the network. The Bridge ID is used to compare the priorities of
+     different bridges.
+  3. Bridge Election: When the network starts, all bridges initially assume
+     that they are the root bridge. They start advertising Bridge Protocol
+     Data Units (BPDU) to their neighbors, containing their Bridge ID and
+     other information.
+  4. BPDU Comparison: Bridges exchange BPDUs to determine the root bridge.
+     Each bridge examines the received BPDUs, including the Bridge Priority
+     and Bridge ID, to determine if it should adjust its own priorities.
+     The bridge with the lowest Bridge ID will become the root bridge.
+  5. Root Bridge Announcement: Once the root bridge is determined, it sends
+     BPDUs with information about the root bridge to all other bridges in the
+     network. This information is used by other bridges to calculate the
+     shortest path to the root bridge and, in doing so, create a loop-free
+     topology.
+  6. Forwarding Ports: After the root bridge is selected and the spanning tree
+     topology is established, each bridge determines which of its ports should
+     be in the forwarding state (used for data traffic) and which should be in
+     the blocking state (used to prevent loops). The root bridge's ports are
+     all in the forwarding state. while other bridges have some ports in the
+     blocking state to avoid loops.
+  7. Root Ports: After the root bridge is selected and the spanning tree
+     topology is established, each non-root bridge processes incoming
+     BPDUs and determines which of its ports provides the shortest path to the
+     root bridge based on the information in the received BPDUs. This port is
+     designated as the root port. And it is in the Forwarding state, allowing
+     it to actively forward network traffic.
+  8. Designated ports: A designated port is the port through which the non-root
+     bridge will forward traffic towards the designated segment. Designated ports
+     are placed in the Forwarding state. All other ports on the non-root
+     bridge that are not designated for specific segments are placed in the
+     Blocking state to prevent network loops.
+
+STP ensures network convergence by calculating the shortest path and disabling
+redundant links. When network topology changes occur (e.g., a link failure),
+STP recalculates the network topology to restore connectivity while avoiding loops.
+
+Proper configuration of STP parameters, such as the bridge priority, can
+influence network performance, path selection and which bridge becomes the
+Root Bridge.
+
+User space STP helper
+---------------------
+The user space STP helper *bridge-stp* is a program to control whether to use
+user mode spanning tree. The ``/sbin/bridge-stp <bridge> <start|stop>`` is
+called by the kernel when STP is enabled/disabled on a bridge
+(via ``brctl stp <bridge> <on|off>`` or ``ip link set <bridge> type bridge
+stp_state <0|1>``).  The kernel enables user_stp mode if that command returns
+0, or enables kernel_stp mode if that command returns any other value.
+
 FAQ
 ===