diff options
| -rw-r--r-- | docs/interfaces/bridge.rst | 308 |
1 files changed, 230 insertions, 78 deletions
diff --git a/docs/interfaces/bridge.rst b/docs/interfaces/bridge.rst index 50f0a58c..18fb19ba 100644 --- a/docs/interfaces/bridge.rst +++ b/docs/interfaces/bridge.rst @@ -4,110 +4,262 @@ Bridge ###### -Interfaces in VyOS can be bridged together to provide software switching of -Layer-2 traffic. +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. -A bridge is created when a bridge interface is defined. In the example below -we create a bridge named br100 with eth1 and eth2 as the bridge member ports. +Configuration +############# -.. code-block:: none +Address +------- - set interfaces bridge 'br100' - set interfaces bridge br100 member interface eth1 - set interfaces bridge br100 member interface eth2 +.. cfgcmd:: set interfaces bridge <interface> address <address | dhcp | dhcpv6> -Each bridge member can be assiged a port cost and priority using the following -commands: + Configure interface `<interface>` with one or more interface addresses. -.. code-block:: none + * **address** can be specified multiple times as IPv4 and/or IPv6 address, + e.g. 192.0.2.1/24 and/or 2001:db8::1/64 + * **dhcp** interface address is received by DHCP from a DHCP server on this + segment. + * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 server on + this segment. - set interfaces bridge br100 member interface eth1 cost 10 - set interfaces bridge br100 member interface eth1 priority 1024 + Example: -Interfaces assigned to a bridge do not have address configuration. An IP -address can be assigned to the bridge interface itself, however, like any -normal interface. + .. code-block:: none -.. code-block:: none + set interfaces bridge br0 address 192.0.2.1/24 + set interfaces bridge br0 address 192.0.2.2/24 + set interfaces bridge br0 address 2001:db8::ffff/64 + set interfaces bridge br0 address 2001:db8:100::ffff/64 - set interfaces bridge br100 address '192.168.100.1/24' - set interfaces bridge br100 address '2001:db8:100::1/64' -Example Result: +.. cfgcmd:: set interfaces bridge <interface> ipv6 address autoconf -.. code-block:: none + :abbr:`SLAAC (Stateless Address Autoconfiguration)` + :rfc:`4862`. IPv6 hosts can configure themselves automatically when connected + to an IPv6 network using the Neighbor Discovery Protocol via :abbr:`ICMPv6 + (Internet Control Message Protocol version 6)` router discovery messages. + When first connected to a network, a host sends a link-local router + solicitation multicast request for its configuration parameters; routers + respond to such a request with a router advertisement packet that contains + Internet Layer configuration parameters. - bridge br100 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - member { - interface eth1 { - cost 10 - priority 1024 - } - interface eth2 { - } - } + .. note:: This method automatically disables IPv6 traffic forwarding on the + interface in question. - } - [...] -In addition to normal IP interface configuration, bridge interfaces support -Spanning-Tree Protocol. STP is disabled by default. +.. cfgcmd:: set interfaces bridge <interface> ipv6 address eui64 <prefix> -.. note:: Please use caution when introducing spanning-tree protocol on a - network as it may result in topology changes. + :abbr:`EUI-64 (64-Bit Extended Unique Identifier)` as specified in + :rfc:`4291` allows a host to assign iteslf a unique 64-Bit IPv6 address. -To enable spanning-tree use the `set interfaces bridge <name> stp` command: + .. code-block:: none -.. code-block:: none + set interfaces bridge eth0 ipv6 address eui64 2001:db8:beef::/64 - set interfaces bridge br100 stp -STP `priority`, `forwarding-delay`, `hello-time`, and `max-age` can be -configured for the bridge. The MAC aging time can also be configured -using the `aging` directive. +.. cfgcmd:: set interfaces bridge <interface> aging <time> -The `show bridge` operational command can be used to display configured -bridges: + MAC address aging `<time`> in seconds (default: 300). + + +.. cfgcmd:: set interfaces bridge <interface> max-age <time> + + Bridge maximum aging `<time>` in seconds (default: 20). + + If a 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. + + +Link Administration +------------------- + +.. cfgcmd:: set interfaces bridge <interface> description <description> + + Assign given `<description>` to interface. Description will also be passed + to SNMP monitoring systems. + + +.. cfgcmd:: set interfaces bridge <interface> disable + + Disable given `<interface>`. It will be placed in administratively down + (``A/D``) state. + + +.. cfgcmd:: set interfaces bridge <interface> disable-flow-control + + Disable Ethernet flow control (pause frames). + + +.. cfgcmd:: set interfaces bridge <interface> mac <mac-address> + + Configure user defined :abbr:`MAC (Media Access Control)` address on given + `<interface>`. + + +.. cfgcmd:: set interfaces bridge <interface> igmp querier + + Enable IGMP querier + + +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`. + + +.. cfgcmd:: set interfaces bridge <interface> member interface <member> priority <priority> + + Configure individual bridge port `<priority>`. + + 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 + optimium performance. -.. code-block:: none - vyos@vyos:~$ show bridge - bridge name bridge id STP enabled interfaces - br100 0000.000c29443b19 yes eth1.100 +.. cfgcmd:: set interfaces bridge <interface> member interface <member> cost <cost> -If spanning-tree is enabled, the `show bridge <name> spanning-tree` command -can be used to show STP configuration: + 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. + + +STP Parameter +------------- + +: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. + +.. cfgcmd:: set interfaces bridge <interface> stp + + Enable spanning tree protocol. STP is disabled by default. + + +.. cfgcmd:: set interfaces bridge <interface> forwarding-delay <delay> + + Spanning Tree Protocol forwarding `<delay>` in seconds (default: 15). + + 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. + + +.. cfgcmd:: set interfaces bridge <interface> hello-time <interval> + + Spanning Tree Protocol hello advertisement `<interval>` in seconds + (default: 2). + + 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. + + +Exammple +-------- + +Creating a bridge interface is very simple. In this example we will have: + +* 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 .. code-block:: none - vyos@vyos:~$ show bridge br100 spanning-tree - br100 - bridge id 0000.000c29443b19 - designated root 0000.000c29443b19 - root port 0 path cost 0 - max age 20.00 bridge max age 20.00 - hello time 2.00 bridge hello time 2.00 - forward delay 15.00 bridge forward delay 15.00 - ageing time 300.00 - hello timer 0.47 tcn timer 0.00 - topology change timer 0.00 gc timer 64.63 - flags - - eth1.100 (1) - port id 8001 state forwarding - designated root 0000.000c29443b19 path cost 4 - designated bridge 0000.000c29443b19 message age timer 0.00 - designated port 8001 forward delay timer 0.00 - designated cost 0 hold timer 0.00 - flags - -The MAC address-table for a bridge can be displayed using the -`show bridge <name> macs` command: + set interfaces bridge br100 address 192.0.2.1/24 + set interfaces bridge br100 address 2001:db8::ffff/64 + set interfaces bridge br100 member interface eth1 + set interfaces bridge br100 member interface eth2.10 + set interfaces bridge br100 stp + +This results in the active configuration: .. code-block:: none - vyos@vyos:~$ show bridge br100 macs - port no mac addr is local? ageing timer - 1 00:53:29:44:3b:19 yes 0.00 + vyos@vyos# show interfaces bridge br100 + address 192.0.2.1/24 + address 2001:db8::ffff/64 + member { + interface eth1 { + } + interface eth2.10 { + } + } + stp + + +Operation +========= + +.. opcmd:: show bridge + + The `show bridge` operational command can be used to display configured + bridges: + + .. code-block:: none + + vyos@vyos:~$ show bridge + bridge name bridge id STP enabled interfaces + br100 8000.0050569d11df yes eth1 + eth2.10 + +.. opcmd:: show bridge <name> spanning-tree + + Show bridge `<name>` STP configuration. + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 spanning-tree + br100 + bridge id 8000.0050569d11df + designated root 8000.0050569d11df + root port 0 path cost 0 + max age 20.00 bridge max age 20.00 + hello time 2.00 bridge hello time 2.00 + forward delay 14.00 bridge forward delay 14.00 + ageing time 300.00 + hello timer 0.06 tcn timer 0.00 + topology change timer 0.00 gc timer 242.02 + flags + + eth1 (1) + port id 8001 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8001 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + flags + + eth2.10 (2) + port id 8002 state disabled + designated root 8000.0050569d11df path cost 100 + designated bridge 8000.0050569d11df message age timer 0.00 + designated port 8002 forward delay timer 0.00 + designated cost 0 hold timer 0.00 + +.. opcmd: show bridge <name> macs + + Show bridge Media Access Control (MAC) address table + + .. code-block:: none + + vyos@vyos:~$ show bridge br100 macs + port no mac addr is local? ageing timer + 1 00:53:29:44:3b:19 yes 0.00 |