Network bridge: Difference between revisions
Lahwaacz.bot (talk | contribs) (update http to https) |
|||
(89 intermediate revisions by 35 users not shown) | |||
Line 3: | Line 3: | ||
{{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 | A network bridge is a virtual network device that forwards packets between two or more network segments. A bridge behaves like a virtual network switch and works transparently. Other machines in the network do not need to know about its existence. Physical network devices (e.g. {{ic|eth1}}) and virtual network devices (e.g. {{ic|tap0}}) can be connected to it. | ||
This | == Creating a bridge == | ||
There are a number of ways to create a network bridge. This section outlines the steps required to set up a bridge with at least one ethernet interface. This is useful for things like the bridge mode of [[QEMU]], setting a software based access point, etc. | |||
{{Warning|If you are creating a bridge on a remote server, and you plan to add the main network interface to the bridge, make sure you first add the main network interface's IP address on the bridge, set the bridge up, and set up a backup default route, '''before''' adding the interface to the bridge. Otherwise the server will lose network connectivity and you will not be able to SSH back into it.}} | |||
=== With iproute2 === | |||
This section describes the management of a network bridge using the ''ip'' tool from the {{Pkg|iproute2}} package, which is required by the {{Pkg|base}} [[meta package]]. | |||
Create a new bridge and change its state to up: | |||
# ip link add name ''bridge_name'' type bridge | |||
# ip link set dev ''bridge_name'' up | |||
== | To add an interface (e.g. {{ic|eth1}}) into the bridge, its state must be up: | ||
# ip link set eth1 up | |||
Adding the interface into the bridge is done by setting its master to {{ic|''bridge_name''}}: | |||
# ip link set eth1 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 eth1 nomaster | |||
The interface will still be up, so you may also want to bring it down: | |||
# ip link set eth1 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. | |||
==== Adding the main network interface ==== | |||
If you are doing this on a remote server, and the plan is to add the main network interface (e.g. {{ic|eth0}}) to the bridge, first take note of the current network status: | |||
$ ip address show eth0 | |||
$ ip route show dev eth0 | |||
For this example, this is the relevant info: | |||
* IP address attached to {{ic|eth0}}: {{ic|10.2.3.4/8}} | |||
* Default gateway: {{ic|10.0.0.1}} | |||
* Bridge name: {{ic|br0}} | |||
Initial setup for the bridge: | |||
# ip link add name br0 type bridge | |||
# ip link set dev br0 up | |||
# ip address add 10.2.3.4/8 dev br0 | |||
# ip route append default via 10.0.0.1 dev br0 | |||
Then, execute these commands in quick succession. It is advisable to put them in a script file and execute the script: | |||
# ip link set eth0 master br0 | |||
# ip address del 10.2.3.4/8 dev eth0 | |||
Explanation: | |||
* Once {{ic|eth0}} is added to the bridge, it won't be used for routing anymore. {{ic|br0}} will take its place, so it needs an IP and have the default route attached. | |||
* We cannot delete the IP address on {{ic|eth0}} before adding the interface to {{ic|br0}}, otherwise network connectivity will be lost. | |||
* However, we need to quickly remove the ip address on {{ic|eth0}}, otherwise network connectivity will be lost after a short period. | |||
* Linux does not allow two default routes on the same routing table. The easy workaround is just to append the new default route. | |||
* Once the IP address of {{ic|eth0}} is removed, the default route attached to it is automatically removed. | |||
=== 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 | This section describes the management of a network bridge using the legacy ''brctl'' tool from the {{Pkg|bridge-utils}} package. See {{man|8|brctl}} for full listing of options. | ||
{{Note|The use of ''brctl'' is deprecated and is considered obsolete. See the Notes section in {{man|8|brctl|NOTES}} for details.}} | |||
Create a new bridge: | Create a new bridge: | ||
Line 20: | Line 89: | ||
# brctl addbr ''bridge_name'' | # brctl addbr ''bridge_name'' | ||
Add a device to a bridge, for example {{ic| | Add a device to a bridge, for example {{ic|eth1}}: | ||
# brctl addif ''bridge_name'' | {{Note|Adding an interface to a bridge will cause the interface to lose its existing IP address. If you are 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.}} | ||
# brctl addif ''bridge_name'' eth1 | |||
Show current bridges and what interfaces they are connected to: | Show current bridges and what interfaces they are connected to: | ||
Line 30: | Line 101: | ||
Set the bridge device up: | Set the bridge device up: | ||
# ip link set | # 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 108: | ||
# brctl delbr ''bridge_name'' | # brctl delbr ''bridge_name'' | ||
{{Note|To enable the [https://ebtables.netfilter.org/documentation/bridge-nf.html bridge-netfilter] functionality, you need to manually load the {{ic|br_netfilter}} module: | |||
# modprobe br_netfilter | |||
You can also [[load the module at boot]]. | |||
}} | |||
==== Adding the main network interface ==== | |||
First, take note of the current network status: | |||
$ ip address show eth0 | |||
$ ip route show dev eth0 | |||
For this example, this is the relevant info: | |||
* IP address attached to {{ic|eth0}}: {{ic|10.2.3.4/8}} | |||
* Default gateway: {{ic|10.0.0.1}} | |||
* Bridge name: {{ic|br0}} | |||
Initial setup for the bridge: | |||
# brctl addbr br0 | |||
# ip address add 10.2.3.4/8 dev br0 | |||
# ip link set dev br0 up | |||
Then, execute these commands in quick succession. It is advisable to put them in a script file and execute the script: | |||
# brctl addif br0 eth0 | |||
# ip address del 10.2.3.4/8 dev eth0 | |||
# | |||
# ip | |||
=== With netctl === | === With netctl === | ||
Line 79: | Line 148: | ||
=== With NetworkManager === | === 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 {{Pkg|plasma-nm}} can create bridges. In order to view, create and modify bridge interfaces open the Connections window either by right clicking the Networks applet in the system tray and selecting ''Configure Network Connections...'' or from ''System Settings > Connections''. Click the ''Configuration'' button in the lower left corner of the module and enable "Show virtual connections". A session restart will be necessary to use the enabled functionality. | |||
{{Pkg|nm-connection-editor}} can create bridges in the same manner as GNOME's Network settings. [https://www.xmodulo.com/configure-linux-bridge-network-manager-ubuntu.html This] page shows these steps with screenshots. | |||
''nmcli'' from {{Pkg|networkmanager}} can create bridges. For example, to create a bridge {{ic|br0}} with [[Wikipedia:Spanning Tree Protocol|STP]] disabled (to avoid the bridge being advertised on the network) run: | |||
$ nmcli connection add type bridge ifname br0 stp no | |||
Make your Ethernet interface ({{ic|enp30s0}} in this example, see [[Network configuration#Network interfaces]] for instructions on finding out the name) into a slave to the bridge: | |||
$ nmcli connection add type bridge-slave ifname enp30s0 master br0 | |||
Bring the existing connection down (you can acquire the connection name with {{ic|nmcli connection show --active}}): | |||
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 | $ nmcli connection down ''Connection'' | ||
Bring the new bridge up: | |||
$ nmcli connection up bridge-br0 | |||
$ nmcli connection up bridge-slave-enp30s0 | |||
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 == | == Assigning an IP address == | ||
{{Expansion|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.}} | |||
When the bridge is fully set up, it can be assigned an IP address: | When the bridge is fully set up, it can be assigned an IP address: | ||
# ip | === With iproute2 === | ||
# ip address add dev ''bridge_name'' 192.168.66.66/24 | |||
=== With NetworkManager === | |||
Give it the desired address: | |||
# nmcli connection modify ''Connection'' ipv4.addresses ''desired_IP'' | |||
Set up a DNS server (this will also avoid not being able to load any pages after you apply the changes): | |||
# nmcli connection modify ''Connection'' ipv4.dns ''DNS_server'' | |||
Set the IP address to static: | |||
# nmcli connection modify ''Connection'' ipv4.method manual | |||
Apply the changes: | |||
# nmcli connection up ''Connection'' | |||
== Tips and tricks == | == Tips and tricks == | ||
Line 103: | Line 205: | ||
=== 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 [[ | 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 [[Debian:BridgeNetworkConnections#Bridging with a wireless NIC]]. | |||
=== 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.[https://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. | |||
== Troubleshooting == | |||
=== No networking after bridge configuration === | |||
{{Style|This problem is pointed out as a note in [[#With bridge-utils]]. It should be made clear in all other sections and running a DHCP client should be added to [[#Assigning an IP address]].}} | |||
It may help to remove all IP addresses and routes from the interface (e.g. {{ic|eth1}}) that was added to the bridge and configure these parameters for the bridge instead. | |||
First of all, make sure there is no [[dhcpcd]] instance running for {{ic|eth1}}, otherwise the deleted addresses may be reassigned. | |||
Remove address and route from the {{ic|eth1}} interface: | |||
# ip addr del ''address'' dev eth1 | |||
# ip route del ''address'' dev eth1 | |||
Now IP address and route for the earlier configured bridge must be set. This is usually done by starting a DHCP client for this interface. Otherwise, consult [[Network configuration]] for manual configuration. | |||
=== No networking on hosted servers after bridge configuration === | |||
{{Style|"Hosted server" is not a generally obvious term.}} | |||
As the MAC address of the bridge is not necessarily equal to the MAC address of the networking card usually used by the server, the server provider might drop traffic coming out from the bridge, resulting in a loss of connectivity when bridging e.g. the server ethernet interface. Configuring the bridge to clone the mac address of the ethernet interface might therefore be needed for hosted servers. | |||
=== Cannot connect to bridge connection after connecting to usual connection === | |||
In Network Manager applet, if you have usual ethernet/wireless connection (not a bridge slave connection), and if you first connect to it, and then try to connect to bridged connection (with or without disconnecting from usual connection first), then you are not able to connect to it. For some reason, the bridge slave connection (it is not listed in network applet) is not activated, even when the auto connect checkbox is enabled. | |||
The workaround is to activate it manually via terminal: | |||
nmcli connection up br1\ slave\ 1 | |||
Then immediately your bridge connections works. | |||
{{Expansion|Is there a bug report for this?}} | |||
=== Bridge appears to not be working on one side of the network === | |||
See | See [[QEMU#Internal networking]]. | ||
== See also == | == See also == | ||
* [ | * [https://www.linuxfoundation.org/collaborate/workgroups/networking/bridge Official documentation for bridge-utils]{{Dead link|2022|09|22|status=404}} | ||
* [ | * [https://www.linuxfoundation.org/collaborate/workgroups/networking/iproute2 Official documentation for iproute2] | ||
* [https://ebtables.netfilter.org/br_fw_ia/br_fw_ia.html ebtables/iptables interaction on a Linux-based bridge] |
Latest revision as of 20:56, 21 March 2024
A network bridge is a virtual network device that forwards packets between two or more network segments. A bridge behaves like a virtual network switch and works transparently. Other machines in the network do not need to know about its existence. Physical network devices (e.g. eth1
) and virtual network devices (e.g. tap0
) can be connected to it.
Creating a bridge
There are a number of ways to create a network bridge. This section outlines the steps required to set up a bridge with at least one ethernet interface. This is useful for things like the bridge mode of QEMU, setting a software based access point, etc.
With iproute2
This section describes the management of a network bridge using the ip tool from the iproute2 package, which is required by the base meta package.
Create a new bridge and change its state to up:
# ip link add name bridge_name type bridge # ip link set dev bridge_name up
To add an interface (e.g. eth1
) into the bridge, its state must be up:
# ip link set eth1 up
Adding the interface into the bridge is done by setting its master to bridge_name
:
# ip link set eth1 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 eth1 nomaster
The interface will still be up, so you may also want to bring it down:
# ip link set eth1 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.
Adding the main network interface
If you are doing this on a remote server, and the plan is to add the main network interface (e.g. eth0
) to the bridge, first take note of the current network status:
$ ip address show eth0 $ ip route show dev eth0
For this example, this is the relevant info:
- IP address attached to
eth0
:10.2.3.4/8
- Default gateway:
10.0.0.1
- Bridge name:
br0
Initial setup for the bridge:
# ip link add name br0 type bridge # ip link set dev br0 up # ip address add 10.2.3.4/8 dev br0 # ip route append default via 10.0.0.1 dev br0
Then, execute these commands in quick succession. It is advisable to put them in a script file and execute the script:
# ip link set eth0 master br0 # ip address del 10.2.3.4/8 dev eth0
Explanation:
- Once
eth0
is added to the bridge, it won't be used for routing anymore.br0
will take its place, so it needs an IP and have the default route attached. - We cannot delete the IP address on
eth0
before adding the interface tobr0
, otherwise network connectivity will be lost. - However, we need to quickly remove the ip address on
eth0
, otherwise network connectivity will be lost after a short period. - Linux does not allow two default routes on the same routing table. The easy workaround is just to append the new default route.
- Once the IP address of
eth0
is removed, the default route attached to it is automatically removed.
With bridge-utils
This section describes the management of a network bridge using the legacy brctl tool from the bridge-utils package. See brctl(8) for full listing of options.
Create a new bridge:
# brctl addbr bridge_name
Add a device to a bridge, for example eth1
:
# brctl addif bridge_name eth1
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
br_netfilter
module:
# modprobe br_netfilter
You can also load the module at boot.
Adding the main network interface
First, take note of the current network status:
$ ip address show eth0 $ ip route show dev eth0
For this example, this is the relevant info:
- IP address attached to
eth0
:10.2.3.4/8
- Default gateway:
10.0.0.1
- Bridge name:
br0
Initial setup for the bridge:
# brctl addbr br0 # ip address add 10.2.3.4/8 dev br0 # ip link set dev br0 up
Then, execute these commands in quick succession. It is advisable to put them in a script file and execute the script:
# brctl addif br0 eth0 # ip address del 10.2.3.4/8 dev eth0
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 create bridges. In order to view, create and modify bridge interfaces open the Connections window either by right clicking the Networks applet in the system tray and selecting Configure Network Connections... or from System Settings > Connections. Click the Configuration button in the lower left corner of the module and enable "Show virtual connections". A session restart will be necessary to use the enabled functionality.
nm-connection-editor can create bridges in the same manner as GNOME's Network settings. This page shows these steps with screenshots.
nmcli from networkmanager can create bridges. For example, to create a bridge br0
with STP disabled (to avoid the bridge being advertised on the network) run:
$ nmcli connection add type bridge ifname br0 stp no
Make your Ethernet interface (enp30s0
in this example, see Network configuration#Network interfaces for instructions on finding out the name) into a slave to the bridge:
$ nmcli connection add type bridge-slave ifname enp30s0 master br0
Bring the existing connection down (you can acquire the connection name with nmcli connection show --active
):
$ nmcli connection down Connection
Bring the new bridge up:
$ nmcli connection up bridge-br0 $ nmcli connection up bridge-slave-enp30s0
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:
With iproute2
# ip address add dev bridge_name 192.168.66.66/24
With NetworkManager
Give it the desired address:
# nmcli connection modify Connection ipv4.addresses desired_IP
Set up a DNS server (this will also avoid not being able to load any pages after you apply the changes):
# nmcli connection modify Connection ipv4.dns DNS_server
Set the IP address to static:
# nmcli connection modify Connection ipv4.method manual
Apply the changes:
# nmcli connection up Connection
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 Debian:BridgeNetworkConnections#Bridging with a wireless NIC.
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.
Troubleshooting
No networking after bridge configuration
It may help to remove all IP addresses and routes from the interface (e.g. eth1
) that was added to the bridge and configure these parameters for the bridge instead.
First of all, make sure there is no dhcpcd instance running for eth1
, otherwise the deleted addresses may be reassigned.
Remove address and route from the eth1
interface:
# ip addr del address dev eth1 # ip route del address dev eth1
Now IP address and route for the earlier configured bridge must be set. This is usually done by starting a DHCP client for this interface. Otherwise, consult Network configuration for manual configuration.
No networking on hosted servers after bridge configuration
As the MAC address of the bridge is not necessarily equal to the MAC address of the networking card usually used by the server, the server provider might drop traffic coming out from the bridge, resulting in a loss of connectivity when bridging e.g. the server ethernet interface. Configuring the bridge to clone the mac address of the ethernet interface might therefore be needed for hosted servers.
Cannot connect to bridge connection after connecting to usual connection
In Network Manager applet, if you have usual ethernet/wireless connection (not a bridge slave connection), and if you first connect to it, and then try to connect to bridged connection (with or without disconnecting from usual connection first), then you are not able to connect to it. For some reason, the bridge slave connection (it is not listed in network applet) is not activated, even when the auto connect checkbox is enabled.
The workaround is to activate it manually via terminal:
nmcli connection up br1\ slave\ 1
Then immediately your bridge connections works.