--- name: "ng_bridge" section: "4" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/ng_bridge" --- # ng\_bridge(4) Ethernet bridging netgraph node ## NAME **ng\_bridge** – Ethernet bridging netgraph node ## SYNOPSIS **#include \** **#include \** ## DESCRIPTION The **bridge** node type performs Ethernet bridging over one or more links. Each link (represented by a connected hook) is used to transmit and receive raw Ethernet frames. As packets are received, the node learns which link each host resides on. Packets unicast to a known host are directed out the appropriate link only, and other links are spared the traffic. This behavior is in contrast to a hub, which always forwards every received packet to every other link. ## LOOP DETECTION The **bridge** node incorporates a simple loop detection algorithm. A loop is when two ports are connected to the same physical medium. Loops are important to avoid because of packet storms, which severely degrade performance. A packet storm results when the same packet is sent and received over and over again. If a host is detected on link A, and is then detected on link B within a certain time period after first being detected on link A, then link B is considered to be a looped back link. The time period is called the minimum stable time. A looped back link will be temporarily muted, i.e., all traffic received on that link is ignored. ## IPFW PROCESSING Processing of IP packets via the [ipfirewall(4)](/ipfirewall/4.md) mechanism on a per-link basis is not yet implemented. ## HOOKS This node type supports an unlimited number of hooks. Each connected hook represents a bridged link. The hooks are named *link0*, *link1*, etc. Typically these hooks are connected to the *lower* hooks of one or more [ng\_ether(4)](/ng_ether/4.md) nodes. To connect the host machine to a bridged network, simply connect the *upper* hook of an [ng\_ether(4)](/ng_ether/4.md) node to the bridge node. The prefix “uplink” is special: a hook named *uplinkX* is marked as an uplink hook and behaves differently from *linkX*. The node does not learn MAC addresses on uplink hooks, which keeps the internal address table small. A host already known on a *linkX* hook is not moved when a packet with that source address arrives on an uplink hook; use NGM\_BRIDGE\_MOVE\_HOST to place a host on an uplink hook explicitly. This way it is desirable to connect the *lower* hook of an [ng\_ether(4)](/ng_ether/4.md) node to an *uplink* hook of the bridge, and ignore the complexity of the outside world. Frames with unknown MACs are always sent out to *uplink* hooks, so no functionality is lost. The *uplink0* hook is not allowed. The *linkX* and *uplinkX* hook numbers can be autoassigned. If a new hook name was specified as *link* or *uplink* the node will append lowest available valid number to the name of the new hook. Frames with unknown destination MAC addresses are replicated to any available hook, unless the first connected hook is an *uplink* hook. In this case the node assumes, that all unknown MAC addresses are located solely on the *uplink* hooks and only those hooks will be used to send out frames with unknown destination MACs. If the first connected hook is an *link* hook, the node will replicate such frames to all types of hooks, even if *uplink* hooks are connected later. ## CONTROL MESSAGES This node type supports the generic control messages, plus the following: - NGM\_BRIDGE\_SET\_CONFIG (*setconfig*) Set the node configuration. This command takes a *struct ng\_bridge\_config* as an argument: ``` /* Node configuration structure */ struct ng_bridge_config { u_char debugLevel; /* debug level */ uint32_t loopTimeout; /* link loopback mute time */ uint32_t maxStaleness; /* max host age before nuking */ uint32_t minStableAge; /* min time for a stable host */ }; ``` The *debugLevel* field sets the debug level on the node. At level of 2 or greater, detected loops are logged. The default level is 1. The *loopTimeout* determines how long (in seconds) a looped link is muted. The default is 60 seconds. The *maxStaleness* parameter determines how long a period of inactivity before a host's entry is forgotten. The default is 15 minutes. The *minStableAge* determines how quickly a host must jump from one link to another before we declare a loopback condition. The default is one second. - NGM\_BRIDGE\_GET\_CONFIG (*getconfig*) Returns the current configuration as a *struct ng\_bridge\_config*. - NGM\_BRIDGE\_RESET (*reset*) Causes the node to forget all hosts and unmute all links. The node configuration is not changed. - NGM\_BRIDGE\_GET\_STATS (*getstats*) This command takes a four byte link number as an argument and returns a *struct ng\_bridge\_link\_stats* containing statistics for the corresponding *link*, which must be currently connected: ``` /* Statistics structure (one for each link) */ struct ng_bridge_link_stats { uint64_t recvOctets; /* total octets rec'd on link */ uint64_t recvPackets; /* total pkts rec'd on link */ uint64_t recvMulticasts; /* multicast pkts rec'd on link */ uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ uint64_t xmitOctets; /* total octets xmit'd on link */ uint64_t xmitPackets; /* total pkts xmit'd on link */ uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ uint64_t loopDrops; /* pkts dropped due to loopback */ uint64_t loopDetects; /* number of loop detections */ uint64_t memoryFailures; /* times couldn't get mem or mbuf */ }; ``` Negative numbers refer to the *uplink* hooks. So querying for -7 will get the statistics for hook *uplink7*. - NGM\_BRIDGE\_CLR\_STATS (*clrstats*) This command takes a four byte link number as an argument and clears the statistics for that link. - NGM\_BRIDGE\_GETCLR\_STATS (*getclrstats*) Same as NGM\_BRIDGE\_GET\_STATS, but also atomically clears the statistics as well. - NGM\_BRIDGE\_GET\_TABLE (*gettable*) Returns the current host mapping table used to direct packets, in a *struct ng\_bridge\_host\_ary*. - NGM\_BRIDGE\_SET\_PERSISTENT (*setpersistent*) This command sets the persistent flag on the node, and takes no arguments. - NGM\_BRIDGE\_MOVE\_HOST (*movehost*) This command takes a *struct ng\_bridge\_move\_host* as an argument. It assigns the MAC *addr* to the *hook*. If the *hook* is the empty string, the incoming hook of the control message is used as fallback. If necessary, the MAC is removed from the currently assigned hook and moved to the new one. If the MAC is moved faster than *minStableAge*, the hook is considered as a loop and will block traffic for *loopTimeout* seconds. ``` struct ng_bridge_move_host { u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ char hook[NG_HOOKSIZ]; /* link where addr can be found */ }; ``` ## SHUTDOWN This node shuts down upon receipt of a NGM\_SHUTDOWN control message, or when all hooks have been disconnected. Setting the persistent flag via a NGM\_BRIDGE\_SET\_PERSISTENT control message disables automatic node shutdown when the last hook gets disconnected. ## FILES - */usr/share/examples/netgraph/ether.bridge* Example script showing how to set up a bridging network ## SEE ALSO [if\_bridge(4)](/if_bridge/4.md), [netgraph(4)](/netgraph/4.md), [ng\_ether(4)](/ng_ether/4.md), [ng\_hub(4)](/ng_hub/4.md), [ng\_one2many(4)](/ng_one2many/4.md), [ngctl(8)](/ngctl/8.md) ## HISTORY The **ng\_bridge** node type was implemented in FreeBSD 4.2. ## AUTHORS Archie Cobbs ⟨*archie@FreeBSD.org*⟩ ## BUGS The **ng\_bridge** node refuses to create the *uplink0* hook to avoid later ambiguity with the NGM\_BRIDGE\_GET\_STATS message.