diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst | 291 |
1 files changed, 183 insertions, 108 deletions
diff --git a/docs/configuration/interfaces/bridge.rst b/docs/configuration/interfaces/bridge.rst index 5e79107b..7f4d3e43 100644 --- a/docs/configuration/interfaces/bridge.rst +++ b/docs/configuration/interfaces/bridge.rst @@ -1,4 +1,4 @@ -:lastproofread: 2024-07-04 +:lastproofread: 2025-12-22 .. _bridge-interface: @@ -6,15 +6,19 @@ Bridge ###### -A Bridge is a way to connect two Ethernet segments together in a -protocol independent way. Packets are forwarded based on Ethernet -address, rather than IP address (like a router). Since forwarding is -done at Layer 2, all protocols can go transparently through a bridge. -The Linux bridge code implements a subset of the ANSI/IEEE 802.1d -standard. +VyOS bridges connect Ethernet segments by grouping multiple interfaces into a +single bridge interface, which acts as a virtual software switch. Unlike +routers, which forward traffic based on Layer 3 IP addresses, bridges operate +at Layer 2 and forward traffic based on MAC addresses. Operating at Layer 2, +bridges are protocol-agnostic and transparently forward all Ethernet- +encapsulated traffic, whether it is IPv4, IPv6, or specialized industrial +protocols. -.. note:: Spanning Tree Protocol is not enabled by default in VyOS. - :ref:`stp` can be easily enabled if needed. +This implementation utilizes the Linux bridge subsystem to support a subset of +the ANSI/IEEE 802.1d standard for transparent bridging and MAC address learning. + +.. note:: :abbr:`STP (Spanning Tree Protocol)` is disabled by default in VyOS + and must be explicitly enabled if required. See :ref:`stp` for details. ************* Configuration @@ -27,125 +31,175 @@ Common interface configuration :var0: bridge :var1: br0 -Member Interfaces +Member interfaces ================= .. cfgcmd:: set interfaces bridge <interface> member interface <member> - Assign `<member>` interface to bridge `<interface>`. A completion - helper will help you with all allowed interfaces which can be - bridged. This includes :ref:`ethernet-interface`, - :ref:`bond-interface`, :ref:`l2tpv3-interface`, :ref:`openvpn`, - :ref:`vxlan-interface`, :ref:`wireless-interface`, - :ref:`tunnel-interface` and :ref:`geneve-interface`. + **Configure an interface as a bridge member.** + + Valid interface types are: :ref:`ethernet-interface`, :ref:`bond-interface`, + :ref:`l2tpv3-interface`, :ref:`openvpn`, :ref:`vxlan-interface`, + :ref:`wireless-interface`, :ref:`tunnel-interface`, and + :ref:`geneve-interface`. + Use tab completion to list interfaces that can be bridged. .. cfgcmd:: set interfaces bridge <interface> member interface <member> priority <priority> - Configure individual bridge port `<priority>`. + **Configure the** :abbr:`STP (Spanning Tree Protocol)` **port priority + for a specific member interface within a bridge.** + + Within the :abbr:`STP (Spanning Tree Protocol)` topology, each member interface + in a bridge operates as a port with an assigned **priority** and **path cost**. + :abbr:`STP (Spanning Tree Protocol)` uses these values to determine the + **lowest-cost path** to the root bridge, maintaining a loop-free topology. + Traffic flows through the path with the lowest path cost, while alternate + paths remain in standby. - Each bridge has a relative priority and cost. Each interface is - associated with a port (number) in the STP code. Each has a priority - and a cost, that is used to decide which is the shortest path to - forward a packet. The lowest cost path is always used unless the - other path is down. If you have multiple bridges and interfaces then - you may need to adjust the priorities to achieve optimum - performance. + A **lower** priority value means **higher** precedence in path selection. + + :abbr:`STP (Spanning Tree Protocol)` considers the port priority only if + multiple member interfaces have the same path costs. .. cfgcmd:: set interfaces bridge <interface> member interface <member> cost <cost> - Path `<cost>` value for Spanning Tree Protocol. Each interface in a - bridge could have a different speed and this value is used when - deciding which link to use. Faster interfaces should have lower - costs. + **Configure the** :abbr:`STP (Spanning Tree Protocol)` **path cost for a + specific member interface within the bridge.** + + Path cost is the primary metric :abbr:`STP (Spanning Tree Protocol)` uses to + determine the path to the root bridge. This value is based on interface + bandwidth; faster interfaces receive lower costs. + + By assigning a lower cost, you give the interface higher precedence during + path selection. -Bridge Options +Bridge options ============== +Configure how bridge interfaces maintain their :abbr:`FDB (Forwarding Database)` +, react to topology changes, and optimize multicast data streams. + .. cfgcmd:: set interfaces bridge <interface> aging <time> - MAC address aging `<time`> in seconds (default: 300). + **Configure the MAC address aging time for the bridge.** + + The duration in seconds that a MAC address remains in the bridge’s :abbr:`FDB + (Forwarding Database)` before removal if no traffic is received from that + address. + + The default value is 300 seconds. .. cfgcmd:: set interfaces bridge <interface> max-age <time> - Bridge maximum aging `<time>` in seconds (default: 20). + **Configure the** :abbr:`STP (Spanning Tree Protocol)` **max age timer for + the bridge.** - If an another bridge in the spanning tree does not send out a hello - packet for a long period of time, it is assumed to be dead. + The duration in seconds that the bridge waits for a :abbr:`BPDU (Bridge + Protocol Data Unit)` from the root bridge. + + If the bridge does not receive a :abbr:`BPDU (Bridge Protocol Data Unit)` + within this period, it recalculates the path to the root bridge or initiates + a new root bridge election. .. cfgcmd:: set interfaces bridge <interface> igmp querier - Enable IGMP and MLD querier. + **Configure the bridge interface to act as the** :abbr:`IGMP (Internet Group + Management Protocol)`/:abbr:`MLD (Multicast Listener Discovery)` **Querier.** + + **When configured:** The bridge interface sends :abbr:`IGMP (Internet Group + Management Protocol)` (IPv4) and :abbr:`MLD (Multicast Listener Discovery)` + (IPv6) general queries to all connected hosts to identify active multicast + listeners. .. cfgcmd:: set interfaces bridge <interface> igmp snooping - Enable IGMP and MLD snooping. + **Configure the bridge interface to perform** :abbr:`IGMP (Internet Group + Management Protocol)`/:abbr:`MLD (Multicast Listener Discovery)` + **snooping.** + + **When configured:** The bridge interface monitors :abbr:`IGMP (Internet Group + Management Protocol)` (IPv4) and :abbr:`MLD (Multicast Listener Discovery)` + (IPv6) join requests and restricts multicast traffic forwarding to only active + listeners. This prevents network flooding. .. _stp: -STP Parameter -------------- +STP configuration +----------------- -:abbr:`STP (Spanning Tree Protocol)` is a network protocol that builds a -loop-free logical topology for Ethernet networks. The basic function of -STP is to prevent bridge loops and the broadcast radiation that results -from them. Spanning tree also allows a network design to include backup -links providing fault tolerance if an active link fails. +:abbr:`STP (Spanning Tree Protocol)` is a Layer 2 protocol that prevents loops +in Ethernet networks by ensuring only one logical path exists between any two +bridges. This creates a loop-free topology and prevents broadcast storms that +can crash the network. -.. cfgcmd:: set interfaces bridge <interface> stp +By default, :abbr:`STP (Spanning Tree Protocol)` is disabled on bridge interfaces. +To activate loop prevention, you must explicitly enable the protocol and +configure its parameters. - Enable spanning tree protocol. STP is disabled by default. +.. cfgcmd:: set interfaces bridge <interface> stp + Enable :abbr:`STP (Spanning Tree Protocol)` on the bridge interface. .. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> - Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + **Configure the** :abbr:`STP (Spanning Tree Protocol)` **delay, in seconds, + for the bridge interface.** - The forwarding delay time is the time spent in each of the listening and - learning states before the Forwarding state is entered. This delay is - so that when a new bridge comes onto a busy network it looks at some - traffic before participating. + This parameter defines how long the bridge interface remains in the listening + and learning states before forwarding traffic. The delay ensures that the + bridge has sufficient time to detect loops (in the listening state) and learn + the MAC addresses of connected devices (in the learning state). + The default value is 15 seconds. The total time before forwarding begins is + twice this value. .. cfgcmd:: set interfaces bridge <interface> hello-time <interval> - Spanning Tree Protocol hello advertisement `<interval>` in seconds - (default: 2). + **Configure the** :abbr:`STP (Spanning Tree Protocol)` **Hello advertisement + interval, in seconds.** + + This parameter sets the frequency at which the bridge interface transmits + Hello packets (:abbr:`BPDUs (Bridge Protocol Data Units)`). These packets + originate from the root bridge and are propagated by designated bridges. If + neighbors stop receiving Hello packets, they assume a connection failure and + trigger a topology recalculation. - Periodically, a hello packet is sent out by the Root Bridge and the - Designated Bridges. Hello packets are used to communicate information - about the topology throughout the entire Bridged Local Area Network. + The default value is 2 seconds. VLAN ==== -Enable VLAN-Aware Bridge ------------------------- +VLAN-aware bridges +------------------ .. cfgcmd:: set interfaces bridge <interface> enable-vlan - To activate the VLAN aware bridge, you must activate this setting to use VLAN - settings for the bridge + **Enable VLAN filtering (also known as VLAN awareness) on the bridge interface.** -.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad|802.1q> + When enabled, the bridge strictly segregates traffic among VLANs configured + on its member interfaces. - Define used ethertype of bridge interface. + .. note:: + Do not configure **vif 1** on a VLAN-aware bridge. The main bridge + interface acts as VLAN 1 (the default native VLAN) and automatically + handles all untagged traffic. - Ethertype ``0x8100`` is used for ``802.1q`` and ethertype ``0x88a8`` is used - for ``802.1ad``. +.. cfgcmd:: set interfaces bridge <interface> protocol <802.1ad | 802.1q> - The default is ``802.1q``. + **Configure the VLAN protocol (EtherType) for the bridge interface.** -VLAN Options ------------- + The following options are available: -.. note:: It is not valid to use the `vif 1` option for VLAN aware bridges - because VLAN aware bridges assume that all unlabeled packets belong to - the default VLAN 1 member and that the VLAN ID of the bridge's parent - interface is always 1 + * ``802.1q`` (default): Sets the EtherType to ``0x8100``. Used for standard + enterprise VLANs. + * ``802.1ad``: Sets the EtherType to ``0x88a8``. Used for QinQ (provider bridging). + +VLAN configuration +------------------ .. cmdinclude:: /_include/interface-vlan-8021q.txt :var0: bridge @@ -154,11 +208,16 @@ VLAN Options .. cfgcmd:: set interfaces bridge <interface> member interface <member> native-vlan <vlan-id> - Set the native VLAN ID flag of the interface. When a data packet without a - VLAN tag enters the port, the data packet will have a specific vlan id added - to it. When the packet flows out, the native vlan tag will be stripped. + **Configure the native VLAN ID for a specific member interface within a + VLAN-aware bridge.** + + This assigns the specified ``<vlan-id>`` to untagged traffic entering the member + interface. The bridge strips the VLAN tag from outgoing traffic matching this + ID. + + **Example:** - Example: Set `eth0` member port to be native VLAN 2 + Set the native VLAN ID to 2 for the member interface ``eth0``: .. code-block:: none @@ -167,24 +226,29 @@ VLAN Options .. cfgcmd:: set interfaces bridge <interface> member interface <member> allowed-vlan <vlan-id> - Allows specific VLAN IDs to pass through the bridge member interface. This - can either be an individual VLAN id or a range of VLAN ids delimited by a - hyphen. + **Configure allowed VLAN IDs for a specific member interface within a + VLAN-aware bridge.** - Example: Set `eth0` member port to be allowed VLAN 4 + Enter a single VLAN ID or a range of VLAN IDs separated by a hyphen. + + **Example:** + + To allow VLAN ID 4 on member interface ``eth0``: .. code-block:: none set interfaces bridge br1 member interface eth0 allowed-vlan 4 - Example: Set `eth0` member port to be allowed VLAN 6-8 + **Example:** + + To allow VLAN IDs 6 through 8 on member interface ``eth0``: .. code-block:: none set interfaces bridge br1 member interface eth0 allowed-vlan 6-8 -Port Mirror (SPAN) -================== +SPAN port mirroring +=================== .. cmdinclude:: ../../_include/interface-mirror.txt :var0: bridge :var1: br1 @@ -194,16 +258,18 @@ Port Mirror (SPAN) Examples ******** -Create a basic bridge -===================== +Configure a standard bridge +=========================== -Creating a bridge interface is very simple. In this example, we will -have: +The following example creates a bridge named br100 with :abbr:`STP (Spanning +Tree Protocol)` enabled. -* A bridge named `br100` -* Member interfaces `eth1` and VLAN 10 on interface `eth2` -* Enable STP -* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 +Configuration requirements: + +* **Bridge name:** ``br100`` +* **Member interfaces:** Physical interface ``eth1`` and VLAN interface ``eth2.10``. +* **STP:** Enabled. +* **Bridge IP addresses:** ``192.0.2.1/24`` (IPv4) and ``2001:db8::ffff/64`` (IPv6). .. code-block:: none @@ -213,7 +279,7 @@ have: set interfaces bridge br100 member interface eth2.10 set interfaces bridge br100 stp -This results in the active configuration: +Verify the configuration: .. code-block:: none @@ -229,16 +295,22 @@ This results in the active configuration: stp -Using VLAN aware Bridge -======================= +Configure a VLAN-aware bridge +============================= + +The following example creates a VLAN-aware bridge named br100. In this setup, +one member interface is configured as a trunk port, and the other as an access +port. The VLAN interface is configured with IP addresses. -An example of creating a VLAN-aware bridge is as follows: +**Configuration requirements:** -* A bridge named `br100` -* The member interface `eth1` is a trunk that allows VLAN 10 to pass -* VLAN 10 on member interface `eth2` (ACCESS mode) -* Enable STP -* Bridge answers on IP address 192.0.2.1/24 and 2001:db8::ffff/64 +* **Bridge name:** ``br100``. +* **Trunk port** (``eth1``): Handles **tagged** traffic for VLAN 10. +* **Access port** (``eth2``): Handles **untagged** traffic (assigned to native + VLAN 10). +* **STP:** Enabled. +* **VLAN IP addresses** (``vif 10``): ``192.0.2.1/24`` (IPv4) and + ``2001:db8::ffff/64`` (IPv6). .. code-block:: none @@ -249,7 +321,7 @@ An example of creating a VLAN-aware bridge is as follows: set interfaces bridge br100 vif 10 address 2001:db8::ffff/64 set interfaces bridge br100 stp -This results in the active configuration: +Verify the configuration: .. code-block:: none @@ -270,13 +342,12 @@ This results in the active configuration: } -Using the operation mode command to view Bridge Information -=========================================================== +Operation +========= .. opcmd:: show bridge - The `show bridge` operational command can be used to display - configured bridges: + Show the status of member interfaces for all configured bridges. .. code-block:: none @@ -288,7 +359,7 @@ Using the operation mode command to view Bridge Information .. opcmd:: show bridge <name> fdb - Show bridge `<name>` fdb displays the current forwarding table: + Show the :abbr:`FDB (Forwarding Database)` for the specified bridge. .. code-block:: none @@ -315,9 +386,12 @@ Using the operation mode command to view Bridge Information .. opcmd:: show bridge <name> mdb - Show bridge `<name>` mdb displays the current multicast group membership - table.The table is populated by IGMP and MLD snooping in the bridge driver - automatically. + Show the :abbr:`MDB (Multicast group Database)` for the specified bridge. + + The :abbr:`MDB (Multicast group Database)` is populated by :abbr:`IGMP + (Internet Group Management Protocol)`/:abbr:`MLD (Multicast Listener + Discovery)` snooping and lists the multicast groups currently active on the + bridge. .. code-block:: none @@ -327,9 +401,10 @@ Using the operation mode command to view Bridge Information dev br0 port br0 grp ff02::1:ff08:1 temp vid 1 dev br0 port br0 grp ff02::6a temp vid 1 -.. opcmd: show bridge <name> macs +.. opcmd:: show bridge <name> macs - Show bridge Media Access Control (MAC) address table + Show the learned :abbr:`MAC (Media Access Control)` address table for the + specified bridge. .. code-block:: none |