1.\" Copyright (c) 2000 Whistle Communications, Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Whistle Communications; 7.\" provided, however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Whistle 11.\" Communications, Inc. trademarks, including the mark "WHISTLE 12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as 13.\" such appears in the above copyright notice or in the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.\" Author: Archie Cobbs <archie@FreeBSD.org> 34.\" 35.Dd April 8, 2024 36.Dt NG_BRIDGE 4 37.Os 38.Sh NAME 39.Nm ng_bridge 40.Nd Ethernet bridging netgraph node type 41.Sh SYNOPSIS 42.In sys/types.h 43.In netgraph/ng_bridge.h 44.Sh DESCRIPTION 45The 46.Nm bridge 47node type performs Ethernet bridging over one or more links. 48Each link (represented by a connected hook) is used to transmit 49and receive raw Ethernet frames. 50As packets are received, the node learns which link each 51host resides on. 52Packets unicast to a known host are directed out the appropriate 53link only, and other links are spared the traffic. 54This behavior is in contrast to a hub, which always forwards 55every received packet to every other link. 56.Sh LOOP DETECTION 57The 58.Nm bridge 59node incorporates a simple loop detection algorithm. 60A loop is when two ports are connected to the same physical medium. 61Loops are important to avoid because of packet storms, which severely 62degrade performance. 63A packet storm results when the same packet is sent and received 64over and over again. 65If a host is detected on link A, and is then detected on link B 66within a certain time period after first being detected on link A, 67then link B is considered to be a looped back link. 68The time period is called the minimum stable time. 69.Pp 70A looped back link will be temporarily muted, i.e., all traffic 71received on that link is ignored. 72.Sh IPFW PROCESSING 73Processing of IP packets via the 74.Xr ipfirewall 4 75mechanism on a per-link basis is not yet implemented. 76.Sh HOOKS 77This node type supports an unlimited number of hooks. 78Each connected hook represents a bridged link. 79The hooks are named 80.Ar link0 , 81.Ar link1 , 82etc. 83Typically these hooks are connected to the 84.Ar lower 85hooks of one or more 86.Xr ng_ether 4 87nodes. 88To connect the host machine to a bridged network, simply connect the 89.Ar upper 90hook of an 91.Xr ng_ether 4 92node to the bridge node. 93.Pp 94Instead of naming a hook 95.Ar linkX 96the hook might be also named 97.Ar uplinkX . 98The node does not learn MAC addresses on uplink hooks, which keeps 99the internal address table small. 100This way it is desirable to connect the 101.Ar lower 102hook of an 103.Xr ng_ether 4 104node to an 105.Ar uplink 106hook of the bridge, and ignore the complexity of the outside world. 107Frames with unknown MACs are always sent out to 108.Ar uplink 109hooks, so no functionality is lost. 110The 111.Ar uplink0 112hook is not allowed. 113.Pp 114The 115.Ar linkX 116and 117.Ar uplinkX 118hook numbers can be autoassigned. 119If a new hook name was specified as 120.Ar link 121or 122.Ar uplink 123the node will append lowest available valid number to the name of the new hook. 124.Pp 125Frames with unknown destination MAC addresses are replicated to any 126available hook, unless the first connected hook is an 127.Ar uplink 128hook. 129In this case the node assumes, that all unknown MAC addresses are 130located solely on the 131.Ar uplink 132hooks and only those hooks will be used to send out frames with 133unknown destination MACs. 134If the first connected hook is an 135.Ar link 136hook, the node will replicate such frames to all types of hooks, 137even if 138.Ar uplink 139hooks are connected later. 140.Sh CONTROL MESSAGES 141This node type supports the generic control messages, plus the 142following: 143.Bl -tag -width foo 144.It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig 145Set the node configuration. 146This command takes a 147.Vt "struct ng_bridge_config" 148as an argument: 149.Bd -literal -offset 0n 150/* Node configuration structure */ 151struct ng_bridge_config { 152 u_char debugLevel; /* debug level */ 153 uint32_t loopTimeout; /* link loopback mute time */ 154 uint32_t maxStaleness; /* max host age before nuking */ 155 uint32_t minStableAge; /* min time for a stable host */ 156}; 157.Ed 158.Pp 159The 160.Va debugLevel 161field sets the debug level on the node. 162At level of 2 or greater, detected loops are logged. 163The default level is 1. 164.Pp 165The 166.Va loopTimeout 167determines how long (in seconds) a looped link is muted. 168The default is 60 seconds. 169The 170.Va maxStaleness 171parameter determines how long a period of inactivity before 172a host's entry is forgotten. 173The default is 15 minutes. 174The 175.Va minStableAge 176determines how quickly a host must jump from one link to another 177before we declare a loopback condition. 178The default is one second. 179.It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig 180Returns the current configuration as a 181.Vt "struct ng_bridge_config" . 182.It Dv NGM_BRIDGE_RESET Pq Ar reset 183Causes the node to forget all hosts and unmute all links. 184The node configuration is not changed. 185.It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats 186This command takes a four byte link number as an argument and 187returns a 188.Vt "struct ng_bridge_link_stats" 189containing statistics for the corresponding 190.Ar link , 191which must be currently connected: 192.Bd -literal -offset 0n 193/* Statistics structure (one for each link) */ 194struct ng_bridge_link_stats { 195 uint64_t recvOctets; /* total octets rec'd on link */ 196 uint64_t recvPackets; /* total pkts rec'd on link */ 197 uint64_t recvMulticasts; /* multicast pkts rec'd on link */ 198 uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ 199 uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ 200 uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ 201 uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ 202 uint64_t xmitOctets; /* total octets xmit'd on link */ 203 uint64_t xmitPackets; /* total pkts xmit'd on link */ 204 uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ 205 uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ 206 uint64_t loopDrops; /* pkts dropped due to loopback */ 207 uint64_t loopDetects; /* number of loop detections */ 208 uint64_t memoryFailures; /* times couldn't get mem or mbuf */ 209}; 210.Ed 211.Pp 212Negative numbers refer to the 213.Ar uplink 214hooks. 215So querying for -7 will get the statistics for hook 216.Ar uplink7 . 217.It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats 218This command takes a four byte link number as an argument and 219clears the statistics for that link. 220.It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats 221Same as 222.Dv NGM_BRIDGE_GET_STATS , 223but also atomically clears the statistics as well. 224.It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable 225Returns the current host mapping table used to direct packets, in a 226.Vt "struct ng_bridge_host_ary" . 227.It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ar setpersistent 228This command sets the persistent flag on the node, and takes no arguments. 229.It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost 230This command takes a 231.Vt "struct ng_bridge_move_host" 232as an argument. 233It assigns the MAC 234.Va addr 235to the 236.Va hook . 237If the 238.Va hook 239is the empty string, the incoming hook of the control message is 240used as fallback. 241.Pp 242If necessary, the MAC is removed from the currently assigned hook and 243moved to the new one. 244If the MAC is moved faster than 245.Va minStableAge , 246the hook is considered as a loop and will block traffic for 247.Va loopTimeout 248seconds. 249.Bd -literal -offset 0n 250struct ng_bridge_move_host { 251 u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ 252 char hook[NG_HOOKSIZ]; /* link where addr can be found */ 253}; 254.Ed 255.El 256.Sh SHUTDOWN 257This node shuts down upon receipt of a 258.Dv NGM_SHUTDOWN 259control message, or when all hooks have been disconnected. 260Setting the persistent flag via a 261.Dv NGM_BRIDGE_SET_PERSISTENT 262control message disables automatic node shutdown when the last hook gets 263disconnected. 264.Sh FILES 265.Bl -tag -width XXXXXXXX -compact 266.It Pa /usr/share/examples/netgraph/ether.bridge 267Example script showing how to set up a bridging network 268.El 269.Sh SEE ALSO 270.Xr if_bridge 4 , 271.Xr netgraph 4 , 272.Xr ng_ether 4 , 273.Xr ng_hub 4 , 274.Xr ng_one2many 4 , 275.Xr ngctl 8 276.Sh HISTORY 277The 278.Nm 279node type was implemented in 280.Fx 4.2 . 281.Sh AUTHORS 282.An Archie Cobbs Aq Mt archie@FreeBSD.org 283.Sh BUGS 284The 285.Nm 286node refuses to create the 287.Ar uplink0 288hook to avoid later ambiguity with the 289.Dv NGM_BRIDGE_GET_STATS 290message. 291