Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Ubuntu - Networking - Configuration - Bridge ======

To bridge traffic between two or more Ethernet interfaces on Linux.

----

===== Background =====

An Ethernet bridge is a device for forwarding packets between two or more Ethernets so that they behave in most respects as if they were a single network.  It could be a physical device, but it is also possible for a bridge to be implemented entirely in software.  The Linux kernel has the ability to perform bridging by means of the bridge module.

If you would like your virtual machines to be visible on your network and have them accept connections from other computers and devices on your network, so they appear as though they were distinct physical machines, then you need to create what is called a Network Bridge.  This process will "share" the physical network adapter on your host computer with each of the virtual machines.  You can only configure a Network Bridge using a wired network adapter. It is not possible to use a wireless device for this.

----

===== Install the bridge utilities package =====

Bridging is performed by a kernel module, but a userspace package is needed to configure it.  This can be found in the **bridge-utils** package on Debian-based systems:

<code bash>
apt install bridge-utils
</code>

and similarly on Red Hat-based systems:

<code bash>
yum install bridge-utils
</code>

----

===== Non-persistent method =====

==== Create the bridge ====

The bridge can be created using the **brctl addbr** command:

<code bash>
brctl addbr br0
</code>

Each bridge must be given a name.  In this case the name **br0** has been chosen, however it is not necessary to follow any particular naming convention provided it does not clash with another network device.


----

==== Enable STP support if required ====

If there is any possibility of the bridge creating a loop in the network then STP (Spanning Tree Protocol) support must be enabled.  This must be done before the bridge is brought up, and to avoid accidents, preferably before any interfaces are attached to it.  STP can be enabled using the **brctl stp** command:

<code bash>
brctl stp br0 on
</code>

Enabling STP should always be safe, but it is not necessarily desirable because of the substantial delay that can occur between a new link being added and it being able to pass traffic.  For this reason you may want to leave STP disabled in simple cases (such as when bridging a set of virtual machines to a single physical interface).


----

==== Remove any IP addresses from the Ethernet interfaces ====

Once an interface has been attached to a bridge it cannot be used for other purposes.  In particular it cannot be used as an endpoint for Internet protocol traffic, so if the interface has been bound to any IP addresses then those addresses should be removed before the interface is attached to a bridge.  If they are not removed then spurious entries will be left in the routing table which can disrupt connectivity.

Addresses can be removed from an interface using the **ifconfig** command:

<code bash>
ifconfig eth0 0.0.0.0 down
ifconfig eth1 0.0.0.0 down
</code>

IPv6 addresses are automatically removed when an interface is brought down, but IPv4 addresses is not.  This is the reason for explicitly setting the IPv4 address to zero.

----

==== Attach the Ethernet interfaces to the bridge ====

To be useful the bridge must have at least two interfaces attached to it.  This can be done using the **brctl addif** command:

<code bash>
brctl addif br0 eth0
brctl addif br0 eth1
</code>

The first argument is the name of the bridge and the second argument is the name of the Ethernet interface to be attached.  More interfaces can be added if required.

<WRAP important>
**WARNING**:  A common mistake when administering a machine remotely via SSH is to incapacitate the network interface that the SSH connection is using.  If you have followed the procedure described above and removed any addresses bound to the interface before attaching it to the bridge then there should be no surprises when you execute the **addif** commands.  If not then a loss of connectivity could occur at this point.
</WRAP>


----

==== Bring the bridge up ====

Like the Ethernet interfaces, the bridge will not become operational until it is brought into the '**up**' state.  This can be done for all three of these devices using the **ifconfig** command:

<code bash>
ifconfig eth0 up
ifconfig eth1 up
ifconfig br0 up
</code>

The bridge should now be ready for use, however there may be a delay before traffic starts to flow (typically about 30 seconds if STP is enabled or half that if not).

----

===== Persistently bridge traffic =====

You need to make a couple of changes to a file on the host computer.  So, issue the following command:

<code bash>
sudo vi /etc/network/interfaces
</code>

The contents of your file probably looks something similar to this:

<file bash /etc/network/interfaces>
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
iface eth0 inet dhcp
</file>

Note: If you're currently using a fixed IP address then the **auto eth0** section of the file will look different to the above.

----

==== How to create a network bridge using DHCP ====

If you are using DHCP to allocate an IP address to your server then change the contents of the file as follows:

<file bash /etc/network/interfaces>
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
#auto eth0
#iface eth0 inet dhcp

auto br0
iface br0 inet dhcp
        bridge_ports eth0
        bridge_fd 9
        bridge_hello 2
        bridge_maxage 12
        bridge_stp off
</file>

The //auto// stanza causes the bridge to be brought up automatically at boot time.  Without this the bridge must be brought up manually using ifup.

The //iface// stanza specifies what should be bridged and how. The manual configuration method is used in this example because the bridge is not intended to have an IP address. See below if it should be bound to an address.

The //bridge_ports// option gives a list of interfaces to be attached to the bridge when it is brought up.  More can be added later if required.  For example, when hosting virtual machines you might want to connect a physical network card to the bridge at boot time, but then attach individual virtual machines as and when they are started.  If you want to create a bridge with no attached interfaces then use a bridge_ports value of **none**:

The //bridge_stp// option specifies whether or not the Spanning Tree Protocol should be enabled.  This is essential if there is any possibility of the bridge creating a loop in the network.  It is safe in other cases, but it will increase the delay between a new link being added and it being able to pass traffic.  For this reason you may want to leave STP disabled in simple cases (such as when bridging a set of virtual machines to a single physical interface).

Unlike VLANs, bridges are not required to follow any special naming convention. It is the presence of a //bridge_ports// line that causes the device to be treated as a bridge (hence the need to specify a value of none if no interfaces are to be attached).

If an Ethernet interface is connected to a bridge then it should not be configured separately in ///etc/network/interfaces//.  Any required configuration is performed automatically when the bridge is brought up.

Don't forget to mask out the auto eth0 and iface eth0 inet dhcp lines.

Once you've made the changes then save the file.

Once you've made the changes to the file then issue the following command to make them active:

<code bash>
sudo /etc/init.d/networking restart
</code>

<WRAP important>
**WARNING**:  Be warned that once an interface has been attached to a bridge it cannot be used for other purposes, and in particular, cannot be used as an endpoint for Internet Protocol traffic.  A common mistake when administering a machine remotely via SSH is to incapacitate the network interface that the SSH connection is using.  Before acting on these instructions you should ensure that you will still be able to control the machine after the bridge has been created.
</WRAP>


----

==== How to create a network bridge using a static IP address. ====

If you are currently using a static IP address for your server or you wish to switch to using a static IP address for your server then change the contents of the file as follows:

Obviously you must substitute the values for address, broadcast, netmask & gateway to those applicable to your own network.  Don't simply use the ones that work in my setup!

<file bash /etc/network/interfaces>
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
#auto eth0
#iface eth0 inet dhcp

auto br0
iface br0 inet static
        address 192.168.1.200
        broadcast 192.168.1.255
        netmask 255.255.255.0
        gateway 192.168.1.254
        bridge_ports eth0
        bridge_fd 9
        bridge_hello 2
        bridge_maxage 12
        bridge_stp off
</file>

Don't forget to mask out the auto eth0 and iface eth0 inet dhcp lines.

Once you've made the changes then save the file.

Once you've made the changes to the file then issue the following command to make them active:

<code bash>
sudo /etc/init.d/networking restart
</code>

----

===== Troubleshooting =====

  * [[Ubuntu:Network:Troubleshooting Ethernet bridging|Troubleshooting Ethernet bridging]]

----

===== See also =====

  * Bridge traffic between two or more Ethernet interfaces on Linux
  * Persistently bridge traffic between two or more Ethernet interfaces (Red Hat)
  * Persistently bridge traffic between two or more Ethernet interfaces (SUSE)

----

===== References =====

  * [[http://wiki.debian.org/BridgeNetworkConnections|Bridging Network Connections, Debian Wiki]]
  * [[http://manpages.ubuntu.com/manpages/precise/man5/bridge-utils-interfaces.5.html|bridge-utils-interfaces(5)]] (Ubuntu manpage)
  * [[http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge|bridge]], The Linux Foundation (bridge module official website)
  * Uwe Böhme, [[http://tldp.org/HOWTO/BRIDGE-STP-HOWTO/index.html|Linux BRIDGE-STP-HOWTO]], v0.04, January 2001
  * [[http://www.microhowto.info/howto/persistently_bridge_traffic_between_two_or_more_ethernet_interfaces_on_debian.html]]