NG_BRIDGE(4)

💖 NG_BRIDGE(4) 💖

okay bestie, so this is ng_bridge, and it lives in the Kernel Interfaces Manual section of your friendly neighborhood man pages. it's a netgraph node type, and it is literally the Ethernet bridging one. buckle up. 🦋

---

✨ NAME ✨

ng_bridge — Ethernet bridging netgraph node type

---

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <netgraph/ng_bridge.h>

---

🎀 DESCRIPTION 🎀

okay so the bridge node type does Ethernet bridging over one or more links. every single link — and a link is represented by a connected hook, iykyk — is used to transmit and receive raw Ethernet frames. 💅

the way it works is: as packets come in, the node learns which link each host is chillin' on. then packets unicast to a known host get directed out the appropriate link only, and all the other links are spared the traffic. iconic. no unnecessary drama. 👑

this behavior is in contrast to a hub, which always forwards every received packet to every other link. a hub is giving "reply all" energy fr fr. 😭

---

🦋 LOOP DETECTION 🦋

the bridge node has a simple loop detection algorithm built in. a loop is when two ports are connected to the same physical medium. and bestie, loops are important to avoid because of packet storms, which severely degrade performance. a packet storm happens when the same packet gets sent and received over and over and over again. it's giving infinite group chat notifications. 💀

so here's the rule: if a host is detected on link A, and then it's 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. that time period is called the minimum stable time.

a looped back link gets temporarily muted, which means all traffic received on that link is ignored. not me silencing the chaos. 🙈

---

🧚 IPFW PROCESSING 🧚

processing of IP packets via the ipfirewall(4) mechanism on a per-link basis is not yet implemented. that's it. that's the whole section. moving on. ✨

---

🌈 HOOKS 🌈

this node type supports an unlimited number of hooks. each connected hook represents a bridged link. the hooks are named link0, link1, etc. (the way that it just keeps counting forever… main character energy.) 👑

typically these hooks are connected to the lower hooks of one or more ng_ether(4) nodes. and to connect the host machine to a bridged network, simply connect the upper hook of an ng_ether(4) node to the bridge node. easy. slay. 💅

---

💜 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 a 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 1 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. it's giving selective memory loss. 🫶

🌟 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 */
};

🌟 NGM_BRIDGE_CLR_STATS (clrstats)

this command takes a four byte link number as an argument and clears the statistics for that link. fresh start bestie. ✨

🌟 NGM_BRIDGE_GETCLR_STATS (getclrstats)

same as NGM_BRIDGE_GET_STATS, but also atomically clears the statistics as well. two birds, one iconic move. 🐦

🌟 NGM_BRIDGE_GET_TABLE (gettable)

returns the current host mapping table used to direct packets, in a struct ng_bridge_host_ary. it's the receipts. 🧾

🌟 NGM_BRIDGE_SET_PERSISTENT (setpersistent)

this command sets the persistent flag on the node, and takes no arguments.

---

🔥 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. so it just… stays. living rent free. 💀

---

🍓 FILES 🍓

• /usr/share/examples/netgraph/ether.bridge — example script showing how to set up a bridging network

---

⭐ SEE ALSO ⭐

if_bridge(4), netgraph(4), ng_ether(4), ng_hub(4), ng_one2many(4), ngctl(8)

---

💫 HISTORY 💫

the ng_bridge node type was implemented in FreeBSD 4.2.

---

👑 AUTHORS 👑

Archie Cobbs <archie@FreeBSD.org>

---

and that's the whole page, bestie!! this version is coming to you from the Debian crowd, dated October 2, 2019 — go forth and bridge responsibly, mwah 💖🎀🦋