BRIDGE-UTILS-INTERFACES(5)

💖 bridge-utils-interfaces(5) 💖

okay bestie, so this is a File formats manual page (section 5) for bridge-utils — the bridge-utils extensions for the interfaces(5) file format. let's get into it ✨

---

🌸 NAME 🌸

bridge-utils-interfaces — bridge-utils extensions for the interfaces(5) file format. yes that's the whole name, it's giving long but it's giving descriptive 💅

---

🎀 DESCRIPTION 🎀

So /etc/network/interfaces holds all your network interface configuration info for the ifup(8) and ifdown(8) commands. This page right here? It's all about the bridge extensions to the standard interfaces(5) file format. 🌉

The main character of this whole thing is the bridge_ports option — with it you say "hey, this interface is a bridge, and here's what ports it has." Those ports are the interfaces that are part of the bridge, and they shouldn't have any stanzas defining them in the interfaces file (important!! don't do it!!). Other extensions let you tune the bridge options or change a bridge's behaviour. 🔧

Let's see it with an example, fr fr:

auto br0
iface br0 inet static
    address 192.168.1.2
    network 192.168.1.0
    netmask 255.255.255.0
    broadcast 192.168.1.255
    gateway 192.168.1.1
    bridge_ports all

Well, after setting this up, an ifup br0, or just the next reboot, should let you have a bridge up and running — after waiting for the ports to get to the forwarding status, of course 😌. This bridge will be using all your ethX interfaces, as we stated on the bridge_ports line.

The Debian bridge setup scripts will wait for it to get ready to work. They do this by trying to guess the maximum time the bridge will need to reach forwarding status, and by default they'll wait for the bridge to get there, or for the estimated maximum time to go by. Why tho? So that services loaded after the bridge setup have a working network interface and don't fail just because the bridge isn't ready yet 💀. See bridge_maxwait if you wanna change this behaviour.

An example of how to set up a so-called anonymous bridge (a bridge with no IP assigned) looks like this:

iface br1 inet manual
     bridge_ports eth1 eth2
     bridge_maxwait 0

Here we pick eth1 and eth2 to be added to the bridge interface br1, which will be an anonymous bridge, and we also tell the scripts not to wait, since we won't have any service running on that interface (it doesn't even have an IP, bestie). 🫶

An example of a slightly more complex bridge setup could be:

auto br0
iface br0 inet static
    address 192.168.1.2
    network 192.168.1.0
    netmask 255.255.255.0
    broadcast 192.168.1.255
    bridge_ports all weird0
    bridge_bridgeprio 32767
    bridge_portprio eth0 129
    bridge_fd 5
    pre-up ip addr flush dev eth0

In this example we select all the eth* devices plus a weird device to be added to the bridge, and we also change the bridge default priority to a higher one so this bridge becomes the root (if there are no bridges with higher priority on the net, that is 👑). Also we lower the priority of port eth0 so it's not used if there are other ports with higher priority to reach the same destination. At the end we lower the default forward delay and add a pre-up command to remove all addresses on eth0 since this interface had an address set up before (only needed on weird/broken setups, iykyk).

If there's a need to set up any of the interfaces participating in the bridge and not the bridge itself, then we have to add the commands to set up those settings in a "pre-up" or "up" statement. So like, if we have a wireless card we wanna add to a bridge and we wanna set it to master and pick the essid, instead of using the typical wireless_* commands we could add something like this to the bridge definition:

pre-up iwconfig wlan0 mode master essid myESSID

⚠️ Be aware though — using wireless cards as part of a bridge is not a good idea if the card belonging to the bridge is in managed mode. Trying to bridge packets coming out of your LAN through a wireless card that's set in managed mode (the card is a client of an AP) is bound to give problems, because the AP will probably refuse packets with source MAC addresses that aren't associated (this is the case of other machines going through the wireless card of the bridge into the AP). 😭

Multiple stanzas of a bridge definition are currently not supported, so if you want to add an ipv6 and an ipv4 to a bridge, do it all in one definition by using the "up" option. If you still wanna use multiple stanzas, or you'd like to read more on this bug, you can see it at http://bugs.debian.org/319832 🐛

---

✨ IFACE OPTIONS ✨

A little explanation on the new options that can be used on /etc/network/interfaces to set up the bridge, so you don't have to go and read the scripts yourself... you're welcome 💅

• bridge_ports interface specification — this option must exist for the scripts to set up the bridge. With it you specify the ports you wanna add to your bridge, either using "none" if you want a bridge without any interfaces or you want to add them later using brctl, or a list of the interfaces you want to add separated by spaces, for example:

bridge_ports eth0 eth4

You should not put any lines to configure the interfaces that will be used by the bridge, since this will be set up automatically by the scripts when bringing the bridge up.

If you need to specify the interfaces more flexibly, you can use the following syntax (most useful on a Xen dom0):

bridge_ports regex (eth|vif).*

This means to evaluate (as in egrep(1)) the expressions that follow after "regex" until either the end or a "noregex" statement is reached. The regular expressions are evaluated against all local interfaces, and those that match get added. 🧚

Specifying "all" is short for "regex eth.* em.* p[0-9].* noregex" and will get all the ethX and biosdevname-format (emX and pX) interfaces added to the bridge.

Carrying this to the extremes, the following is valid syntax:

bridge_ports all regex if.0 noregex ext0 regex vif.*

This will add all ethX interfaces, the ifX0 interfaces, the ext0 interface and all vifX interfaces. iconic 🌈

• bridge_ageing time — set ageing time, default is 300, can have a fractional part.
• bridge_bridgeprio priority — set bridge priority, priority is between 0 and 65535, default is 32768, affects bridge id, lowest priority bridge will be the root.
• bridge_fd time — set bridge forward delay to time seconds, default is 15, can have a fractional part.
• bridge_gcint time — set garbage collection interval to time seconds, default is 4, can have a fractional part. Available on Linux kernel versions < 2.6.0.
• bridge_hello time — set hello time to time seconds, default is 2, can have a fractional part.
• bridge_hw MAC_address|interface — set the Ethernet MAC address of the bridge to the specified one, or to the address of the specified interface. There were some concerns about how this was done in the past, but we're doing it a new way now — it's currently not only considered safe but also necessary or recommended in a lot of scenarios like IPv6, DHCP reservations, ... the usage of bridge_hw setting is the recommended way of doing this. 💖
• bridge_maxage time — set max message age to time seconds, default is 20, can have a fractional part.
• bridge_maxwait time — forces to time seconds the maximum time that the Debian bridge setup scripts will wait for the bridge ports to get to the forwarding status. Doesn't allow a fractional part. If it's equal to 0 then no waiting is done.
• bridge_pathcost port cost — set path cost for a port, from 1 to 65535, default is 100. port is the name of the interface to which this setting applies.
• bridge_portprio port priority — set port priority, from 0 (max) to 63 (min), default is 32, affects port id. port is the name of the interface to which this setting applies.
• bridge_stp state — turn spanning tree protocol on/off. state values are on or yes to turn stp on, and any other thing to set it off. The default has changed to off for security reasons in latest kernels, so you should specify whether you want stp on or off with this option, and not rely on your kernel's default behaviour. 🚨
• bridge_token token — set IPv6 tokenized interface identifier for the bridge to token, see ip-token(8) for more info on this.
• bridge_vlan_aware yes/no — specify if the bridge is vlan aware and thus needs vlan filtering to be activated or not.
• bridge_waitport time [ports] — wait for a max of time seconds for the specified ports to become available. If no ports are specified, then those specified on bridge_ports will be used here. Specifying no ports here should not be used if we're using regex or "all" on bridge_ports, since it wouldn't work. 🙈

---

🦋 FILES 🦋

• /etc/network/interfaces — definitions of network interfaces. See interfaces(5) for more information.

⭐ KNOWN BUGS/LIMITATIONS ⭐

The default values shown here are current values as of this writing, but since they're not related to this package but to the bridge code itself, they can change anytime. 💀

---

👑 AUTHOR 👑

This manpage was written by Santiago Garcia Mantinan <manty@debian.org> based on interfaces(5).

---

🌈 SEE ALSO 🌈

brctl(8), interfaces(5), ifup(8), ip-token(8), iwconfig(8), run-parts(8).

---

and that's the whole page bestie, no cap 🫶 this came from bridge-utils, dated January 13 2008 — go forth and bridge responsibly 💖✨🌸