Difference between revisions of "Network bridge"

From ArchWiki
Jump to navigation Jump to search
(Polish NetworkManager section because certain things were missing or vague before.)
 
(32 intermediate revisions by 18 users not shown)
Line 1: Line 1:
 
[[Category:Networking]]
 
[[Category:Networking]]
 
[[ja:ネットワークブリッジ]]
 
[[ja:ネットワークブリッジ]]
 +
[[zh-hans:Network bridge]]
 
{{Related articles start}}
 
{{Related articles start}}
 
{{Related|Bridge with netctl}}
 
{{Related|Bridge with netctl}}
 +
{{Related|Network_configuration#Bonding_or_LAG}}
 
{{Related articles end}}
 
{{Related articles end}}
A bridge is a piece of software used to unite two or more network segments. A bridge behaves like a virtual network switch, working transparently (the other machines don't need to know or care about its existence). Any real devices (e.g. {{ic|eth0}}) and virtual devices (e.g. {{ic|tap0}}) can be connected to it.
+
A bridge is a piece of software used to unite two or more network segments. A bridge behaves like a virtual network switch, working transparently (the other machines do not need to know or care about its existence). Any real devices (e.g. {{ic|eth0}}) and virtual devices (e.g. {{ic|tap0}}) can be connected to it.
  
 
This article explains how to create a bridge that contains at least an ethernet device. This is useful for things like the bridge mode of [[QEMU]], setting a software based access point, etc.
 
This article explains how to create a bridge that contains at least an ethernet device. This is useful for things like the bridge mode of [[QEMU]], setting a software based access point, etc.
Line 11: Line 13:
  
 
There are a number of ways to create a bridge.
 
There are a number of ways to create a bridge.
 +
 +
=== With iproute2 ===
 +
 +
This section describes the management of a network bridge using the ''ip'' tool from the {{Pkg|iproute2}} package, which is included in the {{Grp|base}} group.
 +
 +
Create a new bridge and change its state to up:
 +
 +
# ip link add name ''bridge_name'' type bridge
 +
# ip link set ''bridge_name'' up
 +
 +
To add an interface (e.g. eth0) into the bridge, its state must be up:
 +
 +
# ip link set eth0 up
 +
 +
Adding the interface into the bridge is done by setting its master to {{ic|''bridge_name''}}:
 +
 +
# ip link set eth0 master ''bridge_name''
 +
 +
To show the existing bridges and associated interfaces, use the ''bridge'' utility (also part of {{Pkg|iproute2}}). See {{man|8|bridge}} for details.
 +
 +
# bridge link
 +
 +
This is how to remove an interface from a bridge:
 +
 +
# ip link set eth0 nomaster
 +
 +
The interface will still be up, so you may also want to bring it down:
 +
 +
# ip link set eth0 down
 +
 +
To delete a bridge issue the following command:
 +
 +
# ip link delete ''bridge_name'' type bridge
 +
 +
This will automatically remove all interfaces from the bridge. The slave interfaces will still be up, though, so you may also want to bring them down after.
  
 
=== With bridge-utils ===
 
=== With bridge-utils ===
  
This section describes the management of a network bridge using the ''brctl'' tool from the {{Pkg|bridge-utils}} package, which is available in the [[official repositories]]. See {{ic|man brctl}} for full listing of options.
+
This section describes the management of a network bridge using the legacy ''brctl'' tool from the {{Pkg|bridge-utils}} package, which is available in the [[official repositories]]. See {{man|8|brctl}} for full listing of options.
  
 
Create a new bridge:
 
Create a new bridge:
Line 23: Line 60:
  
 
  # brctl addif ''bridge_name'' eth0
 
  # brctl addif ''bridge_name'' eth0
 +
 +
{{Note|Adding an interface to a bridge will cause the interface to lose its existing IP address.  If you're connected remotely via the interface you intend to add to the bridge, you will lose your connection.  This problem can be worked around by scripting the bridge to be created at system startup.}}
  
 
Show current bridges and what interfaces they are connected to:
 
Show current bridges and what interfaces they are connected to:
Line 30: Line 69:
 
Set the bridge device up:
 
Set the bridge device up:
  
  # ip link set up dev ''bridge_name''
+
  # ip link set dev ''bridge_name'' up
  
 
Delete a bridge, you need to first set it to ''down'':
 
Delete a bridge, you need to first set it to ''down'':
Line 37: Line 76:
 
  # brctl delbr ''bridge_name''
 
  # brctl delbr ''bridge_name''
  
=== With iproute2 ===
+
{{Note|To enable the [http://ebtables.netfilter.org/documentation/bridge-nf.html bridge-netfilter] functionality, you need to manually load the {{ic|br_netfilter}} module:
  
This sections describes the management of a network bridge using the ''ip'' tool from the {{Pkg|iproute2}} package, which is included in the {{Grp|base}} group.
+
# modprobe br_netfilter
  
Create a new bridge and change its state to up:
+
See also [[Kernel modules#Automatic module loading with systemd]].
 +
}}
  
# ip link add name ''bridge_name'' type bridge
+
=== With netctl ===
# ip link set dev ''bridge_name'' up
 
  
To add an interface (e.g. eth0) into the bridge, it must be first set to ''promiscuous'' mode and its state must be up:
+
See [[Bridge with netctl]].
  
# ip link set dev eth0 promisc on
+
=== With systemd-networkd ===
# ip link set dev eth0 up
 
  
Adding the interface into the bridge is done by setting its master to {{ic|''bridge_name''}}:
+
See [[systemd-networkd#Bridge interface]].
  
# ip link set dev eth0 master ''bridge_name''
+
=== With NetworkManager ===
 
 
To show the existing bridges and associated interfaces, use the ''bridge'' utility (also part of {{Pkg|iproute2}}). See {{ic|man bridge}} for details.
 
 
 
# bridge link show
 
 
 
When the bridge is to be deleted, all interfaces should be removed first. Also turn off promiscuous mode and set it down to restore the original state.
 
 
 
# ip link set eth0 promisc off
 
# ip link set eth0 down
 
# ip link set dev eth0 nomaster
 
  
When the bridge is empty, it can be deleted:
+
[[GNOME]]'s Network settings can create bridges, but currently will not auto-connect to them or slave/attached interfaces. Open Network Settings, add a new interface of type Bridge, add a new bridged connection, and select the MAC address of the device to attach to the bridge.
  
# ip link delete ''bridge_name'' type bridge
+
[[KDE]]'s {{Pkg|plasma-nm}} can't create bridges, another tool must be used for the creation. It can, however, view and modify bridges. "Show and configure virtual connections" must be enabled in the applet configuration (as opposed to the KCM dialog accessed from the applet's configure button or KDE system settings) in order to view and modify bridge interfaces.
  
=== With netctl ===
+
{{Pkg|nm-connection-editor}} can create bridges in the same manner as GNOME's Network settings.
  
See [[Bridge with netctl]].
+
{{ic|nmcli}} from {{Pkg|networkmanager}} can create bridges. Creating a bridge with STP disabled (to avoid the bridge being advertised on the network):
  
=== With systemd-networkd ===
+
$ nmcli c add type bridge ifname br0 stp no
  
See [[systemd-networkd#Bridge interface]].
+
Making interface {{ic|enp30s0}} a slave to the bridge:
  
=== With NetworkManager ===
+
$ nmcli c add type bridge-slave ifname enp30s0 master br0
  
Gnome's NetworkManager can create bridges, but currently will not auto-connect to them. Open Network Settings, add a new interface of type Bridge, add a new bridged connection, and select the MAC address of the device to attach to the bridge.
+
Setting the existing connection as down:
  
Now, find the UUID of the attached device (by default named "bridge0 slave 1"):
+
$ nmcli c down ''Connection''
  
$ nmcli connection
+
Setting the new bridge as up:
  
Finally, enable that connection:
+
  $ nmcli c up bridge-br0
 
 
  $ nmcli con up <UUID>
 
  
 
If NetworkManager's default interface for the device you added to the bridge connects automatically, you may want to disable that by clicking the gear next to it in Network Settings, and unchecking "Connect automatically" under "Identity."
 
If NetworkManager's default interface for the device you added to the bridge connects automatically, you may want to disable that by clicking the gear next to it in Network Settings, and unchecking "Connect automatically" under "Identity."
Line 103: Line 129:
 
=== Wireless interface on a bridge ===
 
=== Wireless interface on a bridge ===
  
To add a wireless interface to a bridge, you first have to assign the wireless interface to an access point or start an access point with [[Software_access_point|hostapd]]. Otherwise the wireless interface won't be added to the bridge.
+
To add a wireless interface to a bridge, you first have to assign the wireless interface to an access point or start an access point with [[Software_access_point|hostapd]]. Otherwise the wireless interface will not be added to the bridge.
  
 
See also [https://wiki.debian.org/BridgeNetworkConnections#Bridging_with_a_wireless_NIC Bridging with a wireless NIC] on Debian wiki.
 
See also [https://wiki.debian.org/BridgeNetworkConnections#Bridging_with_a_wireless_NIC Bridging with a wireless NIC] on Debian wiki.
 +
 +
=== Speeding up traffic destinated to the bridge itself ===
 +
 +
In some situations the bridge not only serves as a bridge box, but also talks to other hosts. Packets that arrive on a bridge port and that are destinated to the bridge box itself will by default enter the iptables INPUT chain with the logical bridge port as input device. These packets will be queued twice by the network code, the first time they are queued after they are received by the network device. The second time after the bridge code examined the destination MAC address and determined it was a locally destinated packet and therefore decided to pass the frame up to the higher protocol stack.[http://ebtables.netfilter.org/examples/basic.html#ex_speed]
 +
 +
The way to let locally destinated packets be queued only once is by brouting them in the BROUTING chain of the broute table. Suppose br0 has an IP address and that br0's bridge ports do not have an IP address. Using the following rule should make all locally directed traffic be queued only once:
 +
 +
# ebtables -t broute -A BROUTING -d $MAC_OF_BR0 -p ipv4 -j redirect --redirect-target DROP
 +
 +
The replies from the bridge will be sent out through the br0 device (assuming your routing table is correct and sends all traffic through br0), so everything keeps working neatly, without the performance loss caused by the packet being queued twice.
 +
 +
The redirect target is needed because the MAC address of the bridge port is not necessarily equal to the MAC address of the bridge device. The packets destinated to the bridge box will have a destination MAC address equal to that of the bridge br0, so that destination address must be changed to that of the bridge port.
  
 
== See also ==
 
== See also ==
Line 111: Line 149:
 
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge Official documentation for bridge-utils]
 
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge Official documentation for bridge-utils]
 
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/iproute2 Official documentation for iproute2]
 
* [http://www.linuxfoundation.org/collaborate/workgroups/networking/iproute2 Official documentation for iproute2]
 +
* [http://ebtables.netfilter.org/br_fw_ia/br_fw_ia.html ebtables/iptables interaction on a Linux-based bridge]

Latest revision as of 19:16, 23 June 2019

A bridge is a piece of software used to unite two or more network segments. A bridge behaves like a virtual network switch, working transparently (the other machines do not need to know or care about its existence). Any real devices (e.g. eth0) and virtual devices (e.g. tap0) can be connected to it.

This article explains how to create a bridge that contains at least an ethernet device. This is useful for things like the bridge mode of QEMU, setting a software based access point, etc.

Creating a bridge

There are a number of ways to create a bridge.

With iproute2

This section describes the management of a network bridge using the ip tool from the iproute2 package, which is included in the base group.

Create a new bridge and change its state to up:

# ip link add name bridge_name type bridge
# ip link set bridge_name up

To add an interface (e.g. eth0) into the bridge, its state must be up:

# ip link set eth0 up

Adding the interface into the bridge is done by setting its master to bridge_name:

# ip link set eth0 master bridge_name

To show the existing bridges and associated interfaces, use the bridge utility (also part of iproute2). See bridge(8) for details.

# bridge link

This is how to remove an interface from a bridge:

# ip link set eth0 nomaster

The interface will still be up, so you may also want to bring it down:

# ip link set eth0 down

To delete a bridge issue the following command:

# ip link delete bridge_name type bridge

This will automatically remove all interfaces from the bridge. The slave interfaces will still be up, though, so you may also want to bring them down after.

With bridge-utils

This section describes the management of a network bridge using the legacy brctl tool from the bridge-utils package, which is available in the official repositories. See brctl(8) for full listing of options.

Create a new bridge:

# brctl addbr bridge_name

Add a device to a bridge, for example eth0:

# brctl addif bridge_name eth0
Note: Adding an interface to a bridge will cause the interface to lose its existing IP address. If you're connected remotely via the interface you intend to add to the bridge, you will lose your connection. This problem can be worked around by scripting the bridge to be created at system startup.

Show current bridges and what interfaces they are connected to:

$ brctl show

Set the bridge device up:

# ip link set dev bridge_name up

Delete a bridge, you need to first set it to down:

# ip link set dev bridge_name down
# brctl delbr bridge_name
Note: To enable the bridge-netfilter functionality, you need to manually load the br_netfilter module:
# modprobe br_netfilter

See also Kernel modules#Automatic module loading with systemd.

With netctl

See Bridge with netctl.

With systemd-networkd

See systemd-networkd#Bridge interface.

With NetworkManager

GNOME's Network settings can create bridges, but currently will not auto-connect to them or slave/attached interfaces. Open Network Settings, add a new interface of type Bridge, add a new bridged connection, and select the MAC address of the device to attach to the bridge.

KDE's plasma-nm can't create bridges, another tool must be used for the creation. It can, however, view and modify bridges. "Show and configure virtual connections" must be enabled in the applet configuration (as opposed to the KCM dialog accessed from the applet's configure button or KDE system settings) in order to view and modify bridge interfaces.

nm-connection-editor can create bridges in the same manner as GNOME's Network settings.

nmcli from networkmanager can create bridges. Creating a bridge with STP disabled (to avoid the bridge being advertised on the network):

$ nmcli c add type bridge ifname br0 stp no

Making interface enp30s0 a slave to the bridge:

$ nmcli c add type bridge-slave ifname enp30s0 master br0

Setting the existing connection as down:

$ nmcli c down Connection

Setting the new bridge as up:

$ nmcli c up bridge-br0

If NetworkManager's default interface for the device you added to the bridge connects automatically, you may want to disable that by clicking the gear next to it in Network Settings, and unchecking "Connect automatically" under "Identity."

Assigning an IP address

When the bridge is fully set up, it can be assigned an IP address:

# ip addr add dev bridge_name 192.168.66.66/24

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: This section needs to be connected to the link-level part described in QEMU#Tap networking with QEMU. For now, see the instructions given there. (Discuss in Talk:Network bridge#)

Tips and tricks

Wireless interface on a bridge

To add a wireless interface to a bridge, you first have to assign the wireless interface to an access point or start an access point with hostapd. Otherwise the wireless interface will not be added to the bridge.

See also Bridging with a wireless NIC on Debian wiki.

Speeding up traffic destinated to the bridge itself

In some situations the bridge not only serves as a bridge box, but also talks to other hosts. Packets that arrive on a bridge port and that are destinated to the bridge box itself will by default enter the iptables INPUT chain with the logical bridge port as input device. These packets will be queued twice by the network code, the first time they are queued after they are received by the network device. The second time after the bridge code examined the destination MAC address and determined it was a locally destinated packet and therefore decided to pass the frame up to the higher protocol stack.[1]

The way to let locally destinated packets be queued only once is by brouting them in the BROUTING chain of the broute table. Suppose br0 has an IP address and that br0's bridge ports do not have an IP address. Using the following rule should make all locally directed traffic be queued only once:

# ebtables -t broute -A BROUTING -d $MAC_OF_BR0 -p ipv4 -j redirect --redirect-target DROP

The replies from the bridge will be sent out through the br0 device (assuming your routing table is correct and sends all traffic through br0), so everything keeps working neatly, without the performance loss caused by the packet being queued twice.

The redirect target is needed because the MAC address of the bridge port is not necessarily equal to the MAC address of the bridge device. The packets destinated to the bridge box will have a destination MAC address equal to that of the bridge br0, so that destination address must be changed to that of the bridge port.

See also