IF_BRIDGE(4)

📦
version 15.1 · 2 versions
, in freebsd 15.1

🌉 NAME

if_bridge(4) — network bridge device. Okay so bestie, this is the manual page for the network bridge device, and it is genuinely giving “switch, but make it kernel” energy 💅✨

✨ SYNOPSIS ✨

To compile this driver into the kernel, place the following line in your kernel configuration file:

device if_bridge

Alternatively, to load the driver as a module at boot time, place the following lines in loader.conf(5):

if_bridge_load="YES"
bridgestp_load="YES"

🌸 DESCRIPTION 🌸

The if_bridge driver creates a logical link between two or more IEEE 802 networks that use the same (or “similar enough”) framing format. For example, it is possible to bridge Ethernet and 802.11 networks together, but it is not possible to bridge Ethernet and Token Ring together. That is just not the vibe, apparently 😭

Each if_bridge interface is created at runtime using interface cloning. This is most easily done with the ifconfig(8) create command or using the cloned_interfaces variable in rc.conf(5). Very “build-a-bridge workshop” of you 🎀

When it is created, the if_bridge interface gets assigned a link (MAC) address in the range of universally administered addresses reserved for the FreeBSD Foundation by hashing the host UUID, jail name, and the interface name. If this fails, a random, locally administered address is generated instead. This address is guaranteed to be unique only across all if_bridge interfaces on the local machine. Thus you can theoretically have two bridges on different machines with the same link addresses. The address can be changed by assigning the desired link address using ifconfig(8). Lowkey iconic that it hashes all that together 🫶

If sysctl(8) node net.link.bridge.inherit_mac has a non-zero value, the newly created bridge will inherit the MAC address from its first member instead of choosing a random link-level address. This will provide more predictable bridge MAC addresses without any additional configuration, but currently this feature is known to break some L2 protocols, for example PPPoE that is provided by ng_pppoe(4) and ppp(8). Currently this feature is considered as experimental and is turned off by default.

🚨 experimental alert: net.link.bridge.inherit_mac is off by default, and it is known to break some L2 protocols. Do not just turn it on and act surprised, bestie.

A bridge can be used to provide several services, such as a simple 802.11-to-Ethernet bridge for wireless hosts, or traffic isolation. Versatile queen behavior 👑

A bridge works like a switch, forwarding traffic from one interface to another. Multicast and broadcast packets are always forwarded to all interfaces that are part of the bridge. For unicast traffic, the bridge learns which MAC addresses are associated with which interfaces and will forward the traffic selectively. It is literally studying the group chat and delivering messages only where they belong 💌

By default the bridge logs MAC address port flapping to syslog(3). This behavior can be disabled by setting the sysctl(8) variable net.link.bridge.log_mac_flap to 0.

All the bridged member interfaces need to be up in order to pass network traffic. These can be enabled using ifconfig(8) or ifconfig_⟨interface⟩="up" in rc.conf(5). No “up” energy, no traffic. Periodt.

The MTU of the first member interface to be added is used as the bridge MTU. All additional members will have their MTU changed to match. If the MTU of a bridge is changed after its creation, the MTU of all member interfaces is also changed to match. Matching outfits, but for MTU 🎀

The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the bridge are disabled if any of the interfaces do not support/enable them. The LRO capability is always disabled. All the capabilities are restored when the interface is removed from the bridge. Changing capabilities at run-time may cause NIC reinit and a link flap. So yeah, runtime glow-ups have consequences 😭

The bridge supports “monitor mode”, where the packets are discarded after bpf(4) processing, and are not processed or forwarded further. This can be used to multiplex the input of two or more interfaces into a single bpf(4) stream. This is useful for reconstructing the traffic for network taps that transmit the RX/TX signals out through two separate interfaces. It is giving packet paparazzi ✨

To allow the host to communicate with bridge members, IP addresses should be assigned to the if_bridge interface itself, not to the bridge's member interfaces. Attempting to assign an IP address to a bridge member interface, or add a member interface with an assigned IP address to a bridge, will return an EINVAL (“Invalid argument”) error. For compatibility with older releases where this was permitted, setting the sysctl(8) variable net.link.bridge.member_ifaddrs to 1 will permit this configuration. This sysctl variable will be removed in FreeBSD 16.0.

🫠 net.link.bridge.member_ifaddrs is compatibility-mode stuff, and it will be removed in FreeBSD 16.0. Do not get too attached.

🦋 IPV6 SUPPORT 🦋

if_bridge supports the AF_INET6 address family on bridge interfaces. The following rc.conf(5) variable configures an IPv6 link-local address on bridge0 interface:

ifconfig_bridge0_ipv6="inet6 auto_linklocal"

However, the AF_INET6 address family has a concept of scope zone. Bridging multiple interfaces changes the zone configuration because multiple links are merged to each other and form a new single link while the member interfaces still work individually. This means each member interface still has a separate link-local scope zone and the if_bridge interface has another single, aggregated link-local scope zone at the same time. This situation is clearly against the description "zones of the same scope cannot overlap" in Section 5, RFC 4007. Although it works in most cases, it can cause some counterintuitive or undesirable behavior in some edge cases when both, the if_bridge interface and one of the member interfaces, have an IPv6 address and applications use both of them. It is giving “zones said do not overlap” and then everyone overlapped anyway 💀

To prevent this situation, if_bridge checks whether a link-local scoped IPv6 address is configured on a member interface to be added and the if_bridge interface. When the if_bridge interface has IPv6 addresses, IPv6 addresses on the member interface will be automatically removed before the interface is added.

This behavior can be disabled by setting sysctl(8) variable net.link.bridge.allow_llz_overlap to 1.

Note that ACCEPT_RTADV and AUTO_LINKLOCAL interface flags are not enabled by default on if_bridge interfaces even when net.inet6.ip6.accept_rtadv and/or net.inet6.ip6.auto_linklocal is set to 1. So do not assume those flags just show up. They are not doing charity work 🙈

🌈 SPANNING TREE 🌈

The if_bridge driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with backwards compatibility with the legacy Spanning Tree Protocol (STP). Spanning Tree is used to detect and remove loops in a network topology. Loop prevention is the main character here, fr fr 🔥

RSTP provides faster spanning tree convergence than legacy STP, the protocol will exchange information with neighbouring switches to quickly transition to forwarding without creating loops.

The code will default to RSTP mode but will downgrade any port connected to a legacy STP network so is fully backward compatible. A bridge can be forced to operate in STP mode without rapid state transitions via the proto command in ifconfig(8).

The bridge can log STP port changes to syslog(3) by setting the net.link.bridge.log_stp node using sysctl(8).

💜 VLAN SUPPORT 💜

The if_bridge driver has full support for virtual LANs (VLANs). The bridge implements independent VLAN learning, i.e. MAC addresses are learned on a per-VLAN basis, and the same MAC address may be learned on multiple interfaces on different VLANs. Incoming frames with an 802.1Q tag will be assigned to the appropriate VLAN. Per-VLAN learning is such a slay little detail 💅

Traffic sent to or from the host is not assigned to a VLAN by default. To allow the host to communicate on a VLAN, configure a vlan(4) interface on the bridge and (if necessary) assign IP addresses there.

By default no access control is enabled, so any interface may participate in any VLAN. Very “everyone is welcome” until you turn on filtering 🎀

VLAN filtering may be enabled on a bridge using the ifconfig(8) vlanfilter option. When VLAN filtering is enabled, an interface may only send and receive frames based on its configured VLAN access list.

The interface's untagged VLAN ID may be configured using the ifconfig(8) untagged option. If an untagged VLAN ID is configured, incoming frames will be assigned to that VLAN, and the interface may receive outgoing untagged frames in that VLAN.

The tagged VLAN access list may be configured using the tagged, +tagged and -tagged options to ifconfig(8). An interface may send and receive tagged frames for any VLAN in its access list.

The bridge will automatically insert or remove 802.1q tags as needed, based on the interface configuration, when forwarding frames between interfaces. This tag processing is only done for interfaces with VLAN filtering enabled. Tag drama handled automatically — iconic behavior, no cap ✨

🛡️ PACKET FILTERING 🛡️

Okay so packet filtering works with literally any firewall package that hooks in via the pfil(9) framework — it's giving equal opportunity firewall energy 💅. When filtering is on, bridged packets pass through the filter inbound on the originating interface, on the bridge interface, and outbound on the appropriate interfaces. Any of those stages can be turned off. And the whole behavior is controlled through sysctl(8), bestie:

  • net.link.bridge.pfil_onlyip — controls what happens to non-IP packets that don't get passed to pfil(9). Set it to 1 and only IP packets are allowed through (subject to your firewall rules, obviously); set it to 0 and all non-IP Ethernet frames get passed unconditionally, no questions asked.
  • net.link.bridge.pfil_member — set to 1 to enable filtering on the incoming and outgoing member interfaces, 0 to disable it.
  • net.link.bridge.pfil_bridge — set to 1 to enable filtering on the bridge interface itself, 0 to disable it.
  • net.link.bridge.pfil_local_phys — set to 1 to additionally filter on the physical interface for locally destined packets. 0 turns that feature off.
  • net.link.bridge.ipfw — set to 1 to enable layer2 filtering with ipfirewall(4), 0 to disable. Heads up: this one needs to be enabled for dummynet(4) support. And when ipfw is enabled, pfil_bridge and pfil_member get disabled so IPFW doesn't run twice — you can re-enable them if you want, though.
  • net.link.bridge.ipfw_arp — set to 1 to enable layer2 ARP filtering with ipfirewall(4), 0 to disable. This one requires ipfw to be enabled first, no cap.

So like, ARP and REVARP packets get forwarded without being filtered at all, and anything that's neither IP nor IPv6 doesn't get forwarded when pfil_onlyip is enabled. But IPFW can filter Ethernet types using mac-type, which means all packets get passed to the filter for processing 🫶.

Packets originating from the bridging host itself get seen by the filter on the interface that gets looked up in the routing table. Easy.

Packets destined to the bridging host get seen by the filter on the interface whose MAC address equals the packet's destination MAC. Now here's where it gets messy 😭 — sometimes multiple bridge members share the same MAC address (classic example: vlan(4) interfaces, which currently share the MAC address of the parent physical interface). You literally cannot distinguish between those interfaces using their MAC address alone, except in the case where the packet's destination MAC address equals the MAC address of the interface the packet entered the system on — in that case the filter sees the incoming packet on that interface. In every other case, the interface the packet filter sees is chosen from the list of bridge members that share the same MAC address, and the result strongly depends on the order members were added and on the actual implementation of if_bridge. So do not rely on the order the current if_bridge implementation picks, because it may change in the future. Like, fr fr, don't.

The previous paragraph is genuinely best explained with pictures, so picture this. Let:

  • the MAC address of the incoming packet's destination be nn:nn:nn:nn:nn:nn,
  • the interface the packet entered the system on be ifX,
  • the ifX MAC address be xx:xx:xx:xx:xx:xx,
  • there be possibly other bridge members with that same MAC address xx:xx:xx:xx:xx:xx,
  • and the bridge have more than one interface sharing the same MAC address yy:yy:yy:yy:yy:yy — we're calling those vlanY1, vlanY2, etc.

If the MAC address nn:nn:nn:nn:nn:nn equals xx:xx:xx:xx:xx:xx, the filter sees the packet on interface ifX, periodt — doesn't matter if other bridge members carry the same MAC address. But if nn:nn:nn:nn:nn:nn equals yy:yy:yy:yy:yy:yy, then the interface seen by the filter is one of the vlanYn. And you literally cannot predict the name of the actual interface without knowing the system state and the if_bridge implementation details. It's giving chaos 🌀.

This problem arises for any bridge members sharing the same MAC address, not just the vlan(4) ones — those were just the example we used. So if you wanna filter locally destined packets based on their interface name, you gotta be aware of this implication, bestie. The described situation will appear at least on filtering bridges doing IP-forwarding; in some of those cases it's better to assign the IP address only to the if_bridge interface and not to the bridge members. And enabling net.link.bridge.pfil_local_phys lets you do the additional filtering on the physical interface 💖.

🌊 NETMAP 🌊

netmap(4) applications may open a bridge interface in emulated mode. The netmap application receives all packets arriving from member interfaces — in particular, packets that would otherwise be forwarded to another member interface get received by the netmap application instead. Iconic behavior, honestly.

When the netmap(4) application transmits a packet to the host stack via the bridge interface, if_bridge receives it and tries to figure out its ‘source’ interface by looking up the source MAC address in the interface's learning tables. Packets where no matching source interface is found get dropped, and the input error counter gets incremented 💀. If a matching source interface is found, if_bridge treats the packet as though it was received from the corresponding interface and handles it normally, without passing the packet back to netmap(4).

✨ EXAMPLES ✨

Drop the following in /etc/rc.conf and it'll cause a bridge called bridge0 to be created, add the interfaces wlan0 and fxp0 to the bridge, and then enable packet forwarding. This kind of config could be used to implement a simple 802.11-to-Ethernet bridge (assuming the 802.11 interface is in ad-hoc mode, ofc):

cloned_interfaces="bridge0"
ifconfig_bridge0="addm wlan0 addm fxp0 up"

For the bridge to forward packets, all member interfaces and the bridge need to be up. The above example would also need:

create_args_wlan0="wlanmode hostap"
ifconfig_wlan0="up ssid my_ap mode 11g"
ifconfig_fxp0="up"

Now imagine a system with two 4-port Ethernet boards. This next one creates a bridge consisting of all 8 ports with Rapid Spanning Tree enabled — look at all those stp flags, we love to see it 👑

ifconfig bridge0 create
ifconfig bridge0 \
    addm fxp0 stp fxp0 \
    addm fxp1 stp fxp1 \
    addm fxp2 stp fxp2 \
    addm fxp3 stp fxp3 \
    addm fxp4 stp fxp4 \
    addm fxp5 stp fxp5 \
    addm fxp6 stp fxp6 \
    addm fxp7 stp fxp7 \
    up

The bridge can be used as a regular host interface at the same time as it bridges between its member ports — multitasking queen 💅. In this example the bridge connects em0 and em1, and receives its IP address through DHCP:

cloned_interfaces="bridge0"
ifconfig_bridge0="addm em0 addm em1 DHCP"
ifconfig_em0="up"
ifconfig_em1="up"

And the bridge can tunnel Ethernet across an IP internet using the EtherIP protocol 🌈 — combine it with ipsec(4) for an encrypted connection. Create a gif(4) interface and set the local and remote IP addresses for the tunnel (these get reversed on the remote bridge, fyi):

ifconfig gif0 create
ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
ifconfig bridge0 create
ifconfig bridge0 addm fxp0 addm gif0 up

👀 SEE ALSO 👀

🕰️ HISTORY 🕰️

The if_bridge driver first appeared in FreeBSD 6.0. Vintage, but make it serve 💜.

👑 AUTHORS 👑

The bridge driver was originally written by Jason L. Wright <jason@thought.net> as part of an undergraduate independent study at the University of North Carolina at Greensboro. Academic icon behavior, honestly 🎓.

This version of the if_bridge driver has been heavily modified from the original version by Jason R. Thorpe <thorpej@wasabisystems.com>.

Rapid Spanning Tree Protocol (RSTP) support was added by Andrew Thompson <thompsa@FreeBSD.org>.

💀 BUGS 💀

The if_bridge driver currently supports only Ethernet and Ethernet-like (e.g., 802.11) network devices, which can be configured with the same MTU size as the bridge device. That's the limit, bestie — no cap, that's just how it is 😭.

and that's the whole page, you're officially a bridge expert now 🫶 This little beauty comes from the Debian source, dated July 28, 2025, and it's page IF_BRIDGE(4) — go forth and bridge responsibly, mwah 💅💖

📦 where this page comes from