Bridge netlink attributes¶

Pleasenote that the timer values in the following section are expectedin clock_t format, which is seconds multiplied by USER_HZ (generallydefined as 100).

IFLA_BR_FORWARD_DELAY

The bridge forwarding delay is the time spent in LISTENING state(before moving to LEARNING) and in LEARNING state (before movingto FORWARDING). Only relevant if STP is enabled.

The valid values are between (2 * USER_HZ) and (30 * USER_HZ).The default value is (15 * USER_HZ).

IFLA_BR_HELLO_TIME

The time between hello packets sent by the bridge, when it is a rootbridge or a designated bridge. Only relevant if STP is enabled.

The valid values are between (1 * USER_HZ) and (10 * USER_HZ).The default value is (2 * USER_HZ).

IFLA_BR_MAX_AGE

The hello packet timeout is the time until another bridge in thespanning tree is assumed to be dead, after reception of its last hellomessage. Only relevant if STP is enabled.

The valid values are between (6 * USER_HZ) and (40 * USER_HZ).The default value is (20 * USER_HZ).

IFLA_BR_AGEING_TIME

Configure the bridge’s FDB entries aging time. It is the time a MACaddress will be kept in the FDB after a packet has been received fromthat address. After this time has passed, entries are cleaned up.Allow values outside the 802.1 standard specification for special cases:

• 0 - entry never ages (all permanent)

• 1 - entry disappears (no persistence)

The default value is (300 * USER_HZ).

IFLA_BR_STP_STATE

Turn spanning tree protocol on (IFLA_BR_STP_STATE > 0) or off(IFLA_BR_STP_STATE == 0) for this bridge.

The default value is 0 (disabled).

IFLA_BR_PRIORITY

Set this bridge’s spanning tree priority, used during STP root bridgeelection.

The valid values are between 0 and 65535.

IFLA_BR_VLAN_FILTERING

Turn VLAN filtering on (IFLA_BR_VLAN_FILTERING > 0) or off(IFLA_BR_VLAN_FILTERING == 0). When disabled, the bridge will notconsider the VLAN tag when handling packets.

The default value is 0 (disabled).

IFLA_BR_VLAN_PROTOCOL

Set the protocol used for VLAN filtering.

The valid values are 0x8100(802.1Q) or 0x88A8(802.1AD). The default valueis 0x8100(802.1Q).

IFLA_BR_GROUP_FWD_MASK

The group forwarding mask. This is the bitmask that is applied todecide whether to forward incoming frames destined to link-localaddresses (of the form 01:80:C2:00:00:0X).

The default value is 0, which means the bridge does not forward anylink-local frames coming on this port.

IFLA_BR_ROOT_ID

The bridge root id, read only.

IFLA_BR_BRIDGE_ID

The bridge id, read only.

IFLA_BR_ROOT_PORT

The bridge root port, read only.

IFLA_BR_ROOT_PATH_COST

The bridge root path cost, read only.

IFLA_BR_TOPOLOGY_CHANGE

The bridge topology change, read only.

IFLA_BR_TOPOLOGY_CHANGE_DETECTED

The bridge topology change detected, read only.

IFLA_BR_HELLO_TIMER

The bridge hello timer, read only.

IFLA_BR_TCN_TIMER

The bridge tcn timer, read only.

IFLA_BR_TOPOLOGY_CHANGE_TIMER

The bridge topology change timer, read only.

IFLA_BR_GC_TIMER

The bridge gc timer, read only.

IFLA_BR_GROUP_ADDR

Set the MAC address of the multicast group this bridge uses for STP.The address must be a link-local address in standard Ethernet MAC addressformat. It is an address of the form 01:80:C2:00:00:0X, with X in [0, 4..f].

The default value is 0.

IFLA_BR_FDB_FLUSH

Flush bridge’s fdb dynamic entries.

IFLA_BR_MCAST_ROUTER

Set bridge’s multicast router if IGMP snooping is enabled.The valid values are:

• 0 - disabled.

• 1 - automatic (queried).

• 2 - permanently enabled.

The default value is 1.

IFLA_BR_MCAST_SNOOPING

Turn multicast snooping on (IFLA_BR_MCAST_SNOOPING > 0) or off(IFLA_BR_MCAST_SNOOPING == 0).

The default value is 1.

IFLA_BR_MCAST_QUERY_USE_IFADDR

If enabled use the bridge’s own IP address as source address for IGMPqueries (IFLA_BR_MCAST_QUERY_USE_IFADDR > 0) or the default of 0.0.0.0(IFLA_BR_MCAST_QUERY_USE_IFADDR == 0).

The default value is 0 (disabled).

IFLA_BR_MCAST_QUERIER

Enable (IFLA_BR_MULTICAST_QUERIER > 0) or disable(IFLA_BR_MULTICAST_QUERIER == 0) IGMP querier, ie sending of multicastqueries by the bridge.

The default value is 0 (disabled).

IFLA_BR_MCAST_HASH_ELASTICITY

Set multicast database hash elasticity, It is the maximum chain length inthe multicast hash table. This attribute isdeprecated and the valueis always 16.

IFLA_BR_MCAST_HASH_MAX

Set maximum size of the multicast hash table

The default value is 4096, the value must be a power of 2.

IFLA_BR_MCAST_LAST_MEMBER_CNT

The Last Member Query Count is the number of Group-Specific Queriessent before the router assumes there are no local members. The LastMember Query Count is also the number of Group-and-Source-SpecificQueries sent before the router assumes there are no listeners for aparticular source.

The default value is 2.

IFLA_BR_MCAST_STARTUP_QUERY_CNT

The Startup Query Count is the number of Queries sent out on startup,separated by the Startup Query Interval.

The default value is 2.

IFLA_BR_MCAST_LAST_MEMBER_INTVL

The Last Member Query Interval is the Max Response Time inserted intoGroup-Specific Queries sent in response to Leave Group messages, andis also the amount of time between Group-Specific Query messages.

The default value is (1 * USER_HZ).

IFLA_BR_MCAST_MEMBERSHIP_INTVL

The interval after which the bridge will leave a group, if no membershipreports for this group are received.

The default value is (260 * USER_HZ).

IFLA_BR_MCAST_QUERIER_INTVL

The interval between queries sent by other routers. if no queries areseen after this delay has passed, the bridge will start to send its ownqueries (as ifIFLA_BR_MCAST_QUERIER_INTVL was enabled).

The default value is (255 * USER_HZ).

IFLA_BR_MCAST_QUERY_INTVL

The Query Interval is the interval between General Queries sent bythe Querier.

The default value is (125 * USER_HZ). The minimum value is (1 * USER_HZ).

IFLA_BR_MCAST_QUERY_RESPONSE_INTVL

The Max Response Time used to calculate the Max Resp Code insertedinto the periodic General Queries.

The default value is (10 * USER_HZ).

IFLA_BR_MCAST_STARTUP_QUERY_INTVL

The interval between queries in the startup phase.

The default value is (125 * USER_HZ) / 4. The minimum value is (1 * USER_HZ).

IFLA_BR_NF_CALL_IPTABLES

Enable (NF_CALL_IPTABLES > 0) or disable (NF_CALL_IPTABLES == 0)iptables hooks on the bridge.

The default value is 0 (disabled).

IFLA_BR_NF_CALL_IP6TABLES

Enable (NF_CALL_IP6TABLES > 0) or disable (NF_CALL_IP6TABLES == 0)ip6tables hooks on the bridge.

The default value is 0 (disabled).

IFLA_BR_NF_CALL_ARPTABLES

Enable (NF_CALL_ARPTABLES > 0) or disable (NF_CALL_ARPTABLES == 0)arptables hooks on the bridge.

The default value is 0 (disabled).

IFLA_BR_VLAN_DEFAULT_PVID

VLAN ID applied to untagged and priority-tagged incoming packets.

The default value is 1. Setting to the special value 0 makes all ports ofthis bridge not have a PVID by default, which means that they willnot accept VLAN-untagged traffic.

IFLA_BR_PAD

Bridge attribute padding type for netlink message.

IFLA_BR_VLAN_STATS_ENABLED

Enable (IFLA_BR_VLAN_STATS_ENABLED == 1) or disable(IFLA_BR_VLAN_STATS_ENABLED == 0) per-VLAN stats accounting.

The default value is 0 (disabled).

IFLA_BR_MCAST_STATS_ENABLED

Enable (IFLA_BR_MCAST_STATS_ENABLED > 0) or disable(IFLA_BR_MCAST_STATS_ENABLED == 0) multicast (IGMP/MLD) statsaccounting.

The default value is 0 (disabled).

IFLA_BR_MCAST_IGMP_VERSION

Set the IGMP version.

The valid values are 2 and 3. The default value is 2.

IFLA_BR_MCAST_MLD_VERSION

Set the MLD version.

The valid values are 1 and 2. The default value is 1.

IFLA_BR_VLAN_STATS_PER_PORT

Enable (IFLA_BR_VLAN_STATS_PER_PORT == 1) or disable(IFLA_BR_VLAN_STATS_PER_PORT == 0) per-VLAN per-port stats accounting.Can be changed only when there are no port VLANs configured.

The default value is 0 (disabled).

IFLA_BR_MULTI_BOOLOPT

The multi_boolopt is used to control new boolean options to avoid addingnew netlink attributes. You can look atenumbr_boolopt_id for thoseoptions.

IFLA_BR_MCAST_QUERIER_STATE

Bridge mcast querier states, read only.

IFLA_BR_FDB_N_LEARNED

The number of dynamically learned FDB entries for the current bridge,read only.

IFLA_BR_FDB_MAX_LEARNED

Set the number of max dynamically learned FDB entries for the currentbridge.

Bridge port netlink attributes¶

IFLA_BRPORT_STATE

The operation state of the port. Here are the valid values.

• 0 - port is in STPDISABLED state. Make this port completelyinactive for STP. This is also called BPDU filter and could be usedto disable STP on an untrusted port, like a leaf virtual device.The traffic forwarding is also stopped on this port.

• 1 - port is in STPLISTENING state. Only valid if STP is enabledon the bridge. In this state the port listens for STP BPDUs anddrops all other traffic frames.

• 2 - port is in STPLEARNING state. Only valid if STP is enabled onthe bridge. In this state the port will accept traffic only for thepurpose of updating MAC address tables.

• 3 - port is in STPFORWARDING state. Port is fully active.

• 4 - port is in STPBLOCKING state. Only valid if STP is enabled onthe bridge. This state is used during the STP election process.In this state, port will only process STP BPDUs.

IFLA_BRPORT_PRIORITY

The STP port priority. The valid values are between 0 and 255.

IFLA_BRPORT_COST

The STP path cost of the port. The valid values are between 1 and 65535.

IFLA_BRPORT_MODE

Set the bridge port mode. SeeBRIDGE_MODE_HAIRPIN for more details.

IFLA_BRPORT_GUARD

Controls whether STP BPDUs will be processed by the bridge port. Bydefault, the flag is turned off to allow BPDU processing. Turning thisflag on will disable the bridge port if a STP BPDU packet is received.

If the bridge has Spanning Tree enabled, hostile devices on the networkmay send BPDU on a port and cause network failure. Settingguard onwill detect and stop this by disabling the port. The port will berestarted if the link is brought down, or removed and reattached.

IFLA_BRPORT_PROTECT

Controls whether a given port is allowed to become a root port or not.Only used when STP is enabled on the bridge. By default the flag is off.

This feature is also called root port guard. If BPDU is received from aleaf (edge) port, it should not be elected as root port. This couldbe used if using STP on a bridge and the downstream bridges are not fullytrusted; this prevents a hostile guest from rerouting traffic.

IFLA_BRPORT_FAST_LEAVE

This flag allows the bridge to immediately stop multicast trafficforwarding on a port that receives an IGMP Leave message. It is only usedwhen IGMP snooping is enabled on the bridge. By default the flag is off.

IFLA_BRPORT_LEARNING

Controls whether a given port will learnsource MAC addresses fromreceived traffic or not. Also controls whether dynamic FDB entries(which can also be added by software) will be refreshed by incomingtraffic. By default this flag is on.

IFLA_BRPORT_UNICAST_FLOOD

Controls whether unicast traffic for which there is no FDB entry willbe flooded towards this port. By default this flag is on.

IFLA_BRPORT_PROXYARP

Enable proxy ARP on this port.

IFLA_BRPORT_LEARNING_SYNC

Controls whether a given port will sync MAC addresses learned on deviceport to bridge FDB.

IFLA_BRPORT_PROXYARP_WIFI

Enable proxy ARP on this port which meets extended requirements byIEEE 802.11 and Hotspot 2.0 specifications.

IFLA_BRPORT_ROOT_ID

IFLA_BRPORT_BRIDGE_ID

IFLA_BRPORT_DESIGNATED_PORT

IFLA_BRPORT_DESIGNATED_COST

IFLA_BRPORT_ID

IFLA_BRPORT_NO

IFLA_BRPORT_TOPOLOGY_CHANGE_ACK

IFLA_BRPORT_CONFIG_PENDING

IFLA_BRPORT_MESSAGE_AGE_TIMER

IFLA_BRPORT_FORWARD_DELAY_TIMER

IFLA_BRPORT_HOLD_TIMER

IFLA_BRPORT_FLUSH

Flush bridge ports’ fdb dynamic entries.

IFLA_BRPORT_MULTICAST_ROUTER

Configure the port’s multicast router presence. A port witha multicast router will receive all multicast traffic.The valid values are:

• 0 disable multicast routers on this port

• 1 let the system detect the presence of routers (default)

• 2 permanently enable multicast traffic forwarding on this port

• 3 enable multicast routers temporarily on this port, not depending

  on incoming queries.

IFLA_BRPORT_PAD

IFLA_BRPORT_MCAST_FLOOD

Controls whether a given port will flood multicast traffic for whichthere is no MDB entry. By default this flag is on.

IFLA_BRPORT_MCAST_TO_UCAST

Controls whether a given port will replicate packets using unicastinstead of multicast. By default this flag is off.

This is done by copying the packet per host and changing the multicastdestination MAC to a unicast one accordingly.

mcast_to_unicast works on top of the multicast snooping feature of thebridge. Which means unicast copies are only delivered to hosts whichare interested in unicast and signaled this via IGMP/MLD reports previously.

This feature is intended for interface types which have a more reliableand/or efficient way to deliver unicast packets than broadcast ones(e.g. WiFi).

However, it should only be enabled on interfaces where no IGMPv2/MLDv1report suppression takes place. IGMP/MLD report suppression issue isusually overcome by the network daemon (supplicant) enabling AP isolationand by that separating all STAs.

Delivery of STA-to-STA IP multicast is made possible again by enablingand utilizing the bridge hairpin mode, which considers the incoming portas a potential outgoing port, too (seeBRIDGE_MODE_HAIRPIN option).Hairpin mode is performed after multicast snooping, therefore leadingto only deliver reports to STAs running a multicast router.

IFLA_BRPORT_VLAN_TUNNEL

Controls whether vlan to tunnel mapping is enabled on the port.By default this flag is off.

IFLA_BRPORT_BCAST_FLOOD

Controls flooding of broadcast traffic on the given port. By defaultthis flag is on.

IFLA_BRPORT_GROUP_FWD_MASK

Set the group forward mask. This is a bitmask that is applied todecide whether to forward incoming frames destined to link-localaddresses. The addresses of the form are 01:80:C2:00:00:0X (defaultsto 0, which means the bridge does not forward any link-local framescoming on this port).

IFLA_BRPORT_NEIGH_SUPPRESS

Controls whether neighbor discovery (arp and nd) proxy and suppressionis enabled on the port. By default this flag is off.

IFLA_BRPORT_ISOLATED

Controls whether a given port will be isolated, which means it will beable to communicate with non-isolated ports only. By default thisflag is off.

IFLA_BRPORT_BACKUP_PORT

Set a backup port. If the port loses carrier all traffic will beredirected to the configured backup port. Set the value to 0 to disableit.

IFLA_BRPORT_MRP_RING_OPEN

IFLA_BRPORT_MRP_IN_OPEN

IFLA_BRPORT_MCAST_EHT_HOSTS_LIMIT

The number of per-port EHT hosts limit. The default value is 512.Setting to 0 is not allowed.

IFLA_BRPORT_MCAST_EHT_HOSTS_CNT

The current number of tracked hosts, read only.

IFLA_BRPORT_LOCKED

Controls whether a port will be locked, meaning that hosts behind theport will not be able to communicate through the port unless an FDBentry with the unit’s MAC address is in the FDB. The common use case isthat hosts are allowed access through authentication with the IEEE 802.1Xprotocol or based on whitelists. By default this flag is off.

Please note that secure 802.1X deployments should always use theBR_BOOLOPT_NO_LL_LEARN flag, to not permit the bridge to populate itsFDB based on link-local (EAPOL) traffic received on the port.

IFLA_BRPORT_MAB

Controls whether a port will use MAC Authentication Bypass (MAB), atechnique through which select MAC addresses may be allowed on a lockedport, without using 802.1X authentication. Packets with an unknown sourceMAC address generates a “locked” FDB entry on the incoming bridge port.The common use case is for user space to react to these bridge FDBnotifications and optionally replace the locked FDB entry with a normalone, allowing traffic to pass for whitelisted MAC addresses.

Setting this flag also requiresIFLA_BRPORT_LOCKED andIFLA_BRPORT_LEARNING.IFLA_BRPORT_LOCKED ensures that unauthorizeddata packets are dropped, andIFLA_BRPORT_LEARNING allows the dynamicFDB entries installed by user space (as replacements for the locked FDBentries) to be refreshed and/or aged out.

IFLA_BRPORT_MCAST_N_GROUPS

IFLA_BRPORT_MCAST_MAX_GROUPS

Sets the maximum number of MDB entries that can be registered for agiven port. Attempts to register more MDB entries at the port than thislimit allows will be rejected, whether they are done through netlink(e.g. the bridge tool), or IGMP or MLD membership reports. Setting alimit of 0 disables the limit. The default value is 0.

IFLA_BRPORT_NEIGH_VLAN_SUPPRESS

Controls whether neighbor discovery (arp and nd) proxy and suppression isenabled for a given port. By default this flag is off.

Note that this option only takes effect whenIFLA_BRPORT_NEIGH_SUPPRESSis enabled for a given port.

IFLA_BRPORT_BACKUP_NHID

The FDB nexthop object ID to attach to packets being redirected to abackup port that has VLAN tunnel mapping enabled (via theIFLA_BRPORT_VLAN_TUNNEL option). Setting a value of 0 (default) hasthe effect of not attaching any ID.

Bridge sysfs¶

The sysfs interface is deprecated and should not be extended if newoptions are added.

Bridge Ports and STP States¶

In the context of STP, bridge ports can be in one of the following states:

• Blocking: The port is disabled for data traffic and only listens forBPDUs (Bridge Protocol Data Units) from other devices to determine thenetwork topology.

• Listening: The port begins to participate in the STP process and listensfor BPDUs.

• Learning: The port continues to listen for BPDUs and begins to learn MACaddresses from incoming frames but does not forward data frames.

• Forwarding: The port is fully operational and forwards both BPDUs anddata frames.

• Disabled: The port is administratively disabled and does not participatein the STP process. The data frames forwarding are also disabled.

Root Bridge and Convergence¶

In the context of networking and Ethernet bridging in Linux, the root bridgeis a designated switch in a bridged network that serves as a reference pointfor the spanning tree algorithm to create a loop-free topology.

Here’s how the STP works and root bridge is chosen:

1. Bridge Priority: Each bridge running a spanning tree protocol, has aconfigurable Bridge Priority value. The lower the value, the higher thepriority. By default, the Bridge Priority is set to a standard value(e.g., 32768).

2. Bridge ID: The Bridge ID is composed of two components: Bridge Priorityand the MAC address of the bridge. It uniquely identifies each bridgein the network. The Bridge ID is used to compare the priorities ofdifferent bridges.

3. Bridge Election: When the network starts, all bridges initially assumethat they are the root bridge. They start advertising Bridge ProtocolData Units (BPDU) to their neighbors, containing their Bridge ID andother information.

4. BPDU Comparison: Bridges exchange BPDUs to determine the root bridge.Each bridge examines the received BPDUs, including the Bridge Priorityand Bridge ID, to determine if it should adjust its own priorities.The bridge with the lowest Bridge ID will become the root bridge.

5. Root Bridge Announcement: Once the root bridge is determined, it sendsBPDUs with information about the root bridge to all other bridges in thenetwork. This information is used by other bridges to calculate theshortest path to the root bridge and, in doing so, create a loop-freetopology.

6. Forwarding Ports: After the root bridge is selected and the spanning treetopology is established, each bridge determines which of its ports shouldbe in the forwarding state (used for data traffic) and which should be inthe blocking state (used to prevent loops). The root bridge’s ports areall in the forwarding state. while other bridges have some ports in theblocking state to avoid loops.

7. Root Ports: After the root bridge is selected and the spanning treetopology is established, each non-root bridge processes incomingBPDUs and determines which of its ports provides the shortest path to theroot bridge based on the information in the received BPDUs. This port isdesignated as the root port. And it is in the Forwarding state, allowingit to actively forward network traffic.

8. Designated ports: A designated port is the port through which the non-rootbridge will forward traffic towards the designated segment. Designated portsare placed in the Forwarding state. All other ports on the non-rootbridge that are not designated for specific segments are placed in theBlocking state to prevent network loops.

STP ensures network convergence by calculating the shortest path and disablingredundant links. When network topology changes occur (e.g., a link failure),STP recalculates the network topology to restore connectivity while avoiding loops.

Proper configuration of STP parameters, such as the bridge priority, caninfluence network performance, path selection and which bridge becomes theRoot Bridge.

User space STP helper¶

The user space STP helperbridge-stp is a program to control whether to useuser mode spanning tree. The/sbin/bridge-stp<bridge><start|stop> iscalled by the kernel when STP is enabled/disabled on a bridge(viabrctlstp<bridge><on|off> oriplinkset<bridge>typebridgestp_state<0|1>). The kernel enables user_stp mode if that command returns0, or enables kernel_stp mode if that command returns any other value.

Multicast snooping¶

Multicast snooping is a networking technology that allows network switchesto intelligently manage multicast traffic within a local area network (LAN).

The switch maintains a multicast group table, which records the associationbetween multicast group addresses and the ports where hosts have joined thesegroups. The group table is dynamically updated based on the IGMP/MLD messagesreceived. With the multicast group information gathered through snooping, theswitch optimizes the forwarding of multicast traffic. Instead of blindlybroadcasting the multicast traffic to all ports, it sends the multicasttraffic based on the destination MAC address only to ports which havesubscribed the respective destination multicast group.

When created, the Linux bridge devices have multicast snooping enabled bydefault. It maintains a Multicast forwarding database (MDB) which keeps trackof port and group relationships.

IGMPv3/MLDv2 EHT support¶

The Linux bridge supports IGMPv3/MLDv2 EHT (Explicit Host Tracking), whichwas added by474ddb37fa3a (“net: bridge: multicast: add EHT allow/block handling”)

The explicit host tracking enables the device to keep track of eachindividual host that is joined to a particular group or channel. The mainbenefit of the explicit host tracking in IGMP is to allow minimal leavelatencies when a host leaves a multicast group or channel.

The length of time between a host wanting to leave and a device stoppingtraffic forwarding is called the IGMP leave latency. A device configuredwith IGMPv3 or MLDv2 and explicit tracking can immediately stop forwardingtraffic if the last host to request to receive traffic from the deviceindicates that it no longer wants to receive traffic. The leave latencyis thus bound only by the packet transmission latencies in the multiaccessnetwork and the processing time in the device.

Other multicast features¶

The Linux bridge also supportsper-VLAN multicast snooping,which is disabled by default but can be enabled. AndMulticast Router Discovery,which help identify the location of multicast routers.

What does a bridge do?¶

A bridge transparently forwards traffic between multiple network interfaces.In plain English this means that a bridge connects two or more physicalEthernet networks, to form one larger (logical) Ethernet network.

Is it L3 protocol independent?¶

Yes. The bridge sees all frames, but ituses only L2 headers/information.As such, the bridging functionality is protocol independent, and there shouldbe no trouble forwarding IPX, NetBEUI, IP, IPv6, etc.