interfaces-bridge(5)

📦
version 0.13.0 · 7 versions
, in alpine 3.24

🌉 NAME

interfaces-bridge(5) — bridge extensions for the interfaces(5) file format. This is the glow-up page for all the bridge-y bits, bestie 💖.

✨ DESCRIPTION

Okay so Linux has support for Ethernet bridging interfaces, and those act like an Ethernet switch inside the Linux Kernel — literally switch energy in the kernel 🧚. The following options let you set up Ethernet bridges and add configured interfaces to bridges.

See ip-link(8) for more details about the options listed below. 👑

  • bridge-ports list of interfaces — a space-separated list of interfaces that should be configured as member interfaces of this bridge. This option must be set for the bridge to be configured. Set it to none to create a bridge with no ports.
  • bridge-hw MAC address — the MAC address the bridge should use. 💅
  • bridge-ageing seconds — the time in seconds after which a MAC address gets removed from the Forwarding DataBase (FDB) after not having seen a frame with this source address.
  • bridge-vlan-aware bool — whether or not the bridge should be aware of 802.1q VLANs. bool can be given as yes/no or 0/1. The default is no. See the related options for configuring vlan-aware bridges, below. 🦋
  • bridge-stp state — activates or deactivates IEEE 802.1d Spanning Tree Protocol (STP) support of the bridge. Valid values are on/off.
  • bridge-bridgeprio priority — sets the bridge's priority to priority. The priority value is a number between 0 and 65535. Lower priority values are better. The bridge with the lowest priority will be elected root bridge. 👑
  • bridge-fd seconds — the bridge forward delay in seconds. Valid values are between 2 and 30.
  • bridge-hello seconds — the bridge hello time in seconds. Valid values are between 1 and 10.
  • bridge-maxage seconds — the seconds until another bridge is considered dead after reception of its last STP hello message. Valid values are between 6 and 40.

🦋 OPTIONS FOR VLAN-AWARE-BRIDGES

The following options only have an effect on vlan-aware bridges and their ports.

Unless otherwise noted, all settings can be applied on the bridge interface itself and all member port iface stanzas. If applied on the bridge interface they take effect for the bridge interface itself and might be inherited to bridge-ports depending on the compatibility settings configured in ifupdown-ng.conf(5).

Configuring VLAN options on the bridge interface might be required for setting up a VLAN interface to one of the VLANs carried within the bridge. See the EXAMPLES section for an example for this scenario.

See ifupdown-ng.conf(5) for more information about compatibility settings mentioned below. 🫶

  • bridge-access vlan ID — configure the given vlan ID for untagged ingress and egress on this interface. The common description for this kind of configuration is called "access port".
  • bridge-pvid vlan ID — the vlan ID to be considered a PVID at ingress. Any untagged frames received on this interface will be assigned to this vlan ID. The default PVID is 1.

If compatibility to ifupdown2 bridge port inheritance is active, a bridge-pvid set on the bridge will be inherited to any interface configured in bridge-ports without a bridge-pvid set.

  • bridge-vids list of vlan IDs — the space-separated list of VLANs to be allowed tagged ingress/egress on this interface.

If compatibility to ifupdown2 bridge port inheritance is active, a bridge-vids set on the bridge will be inherited to any interface configured in bridge-ports without bridge-vids set.

  • bridge-allow-untagged bool — whether or not the bridge should allow untagged frames on ingress as well as egress. If set to no, untagged frames will be dropped on ingress and none will be sent. bool can be given as yes/no or 0/1. The default is yes.
  • bridge-default-pvid vlan ID — the vlan ID that should be the default PVID for all ports on this interface. This sets the vlan_default_pvid option on the bridge and thus also applies to ports configured outside of ifupdown-ng. Set to 0 to disable.

This option can only be used on the bridge itself, not on its ports. The default is 1.

🎀 EXAMPLES

Okay bestie, the configs are the moment — here's exactly what they look like:

A simple layer 2 only bridge:

auto br0
iface br0
     bridge-ports eth0 veth-vm1 tap0
     bridge-fd 0
     bridge-stp off

A bridge with layer 3 configuration:

auto br0
iface br0
     bridge-ports eth0 veth-vm1 tap0
     bridge-fd 0
     bridge-stp off
     #
     address 192.0.2.42/24
     address 2001:db8::42/64

A layer 2 only vlan-aware bridge:

auto bond0
iface bond0
     bond-members eth0 eth1
     bridge-vids 23 42 84 1337

auto br0
iface br0
     bridge-ports bond0

A vlan-aware bridge with a VLAN interface on top:

auto eth0
iface eth0
     bridge-vids 23 42 84 1337

auto br0
iface br0
     bridge-ports eth0
     bridge-vlan-aware yes
     bridge-vids 42

auto vlan42
iface vlan42
     vlan-raw-device br0
     #
     address 192.0.2.42/24
     address 2001:db8::42/64

🔥 SEE ALSO

interfaces(5) ifupdown-ng.conf(5) ip-link(8) bridge(8) — go read these, iykyk 💜.

👑 AUTHORS

Maximilian Wilhelm <max@sdn.clinic> — iconic, honestly.

Byeee bestie 💖 — footer sign-off deets: this manual is interfaces-bridge(5), dated 2026-05-10. Stay bridged and slay 🌈✨

📦 where this page comes from