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.\" $FreeBSD$ 36.\" 37.Dd May 13, 2021 38.Dt NG_BRIDGE 4 39.Os 40.Sh NAME 41.Nm ng_bridge 42.Nd Ethernet bridging netgraph node type 43.Sh SYNOPSIS 44.In sys/types.h 45.In netgraph/ng_bridge.h 46.Sh DESCRIPTION 47The 48.Nm bridge 49node type performs Ethernet bridging over one or more links. 50Each link (represented by a connected hook) is used to transmit 51and receive raw Ethernet frames. 52As packets are received, the node learns which link each 53host resides on. 54Packets unicast to a known host are directed out the appropriate 55link only, and other links are spared the traffic. 56This behavior is in contrast to a hub, which always forwards 57every received packet to every other link. 58.Sh LOOP DETECTION 59The 60.Nm bridge 61node incorporates a simple loop detection algorithm. 62A loop is when two ports are connected to the same physical medium. 63Loops are important to avoid because of packet storms, which severely 64degrade performance. 65A packet storm results when the same packet is sent and received 66over and over again. 67If a host is detected on link A, and is then detected on link B 68within a certain time period after first being detected on link A, 69then link B is considered to be a looped back link. 70The time period is called the minimum stable time. 71.Pp 72A looped back link will be temporarily muted, i.e., all traffic 73received on that link is ignored. 74.Sh IPFW PROCESSING 75Processing of IP packets via the 76.Xr ipfirewall 4 77mechanism on a per-link basis is not yet implemented. 78.Sh HOOKS 79This node type supports an unlimited number of hooks. 80Each connected hook represents a bridged link. 81The hooks are named 82.Ar link0 , 83.Ar link1 , 84etc. 85Typically these hooks are connected to the 86.Ar lower 87hooks of one or more 88.Xr ng_ether 4 89nodes. 90To connect the host machine to a bridged network, simply connect the 91.Ar upper 92hook of an 93.Xr ng_ether 4 94node to the bridge node. 95.Pp 96Instead of naming a hook 97.Ar linkX 98the hook might be also named 99.Ar uplinkX . 100The node does not learn MAC addresses on uplink hooks, which keeps 101the internal address table small. 102This way it is desirable to connect the 103.Ar lower 104hook of an 105.Xr ng_ether 4 106node to an 107.Ar uplink 108hook of the bridge, and ignore the complexity of the outside world. 109Frames with unknown MACs are always sent out to 110.Ar uplink 111hooks, so no functionality is lost. 112.Pp 113Frames with unknown destination MAC addresses are replicated to any 114available hook, unless the first connected hook is an 115.Ar uplink 116hook. 117In this case the node assumes, that all unknown MAC addresses are 118located soley on the 119.Ar uplink 120hooks and only those hooks will be used to send out frames with 121unknown destination MACs. 122If the first connected hook is an 123.Ar link 124hook, the node will replicate such frames to all types of hooks, 125even if 126.Ar uplink 127hooks are connected later. 128.Sh CONTROL MESSAGES 129This node type supports the generic control messages, plus the 130following: 131.Bl -tag -width foo 132.It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig 133Set the node configuration. 134This command takes a 135.Vt "struct ng_bridge_config" 136as an argument: 137.Bd -literal -offset 0n 138/* Node configuration structure */ 139struct ng_bridge_config { 140 u_char debugLevel; /* debug level */ 141 uint32_t loopTimeout; /* link loopback mute time */ 142 uint32_t maxStaleness; /* max host age before nuking */ 143 uint32_t minStableAge; /* min time for a stable host */ 144}; 145.Ed 146.Pp 147The 148.Va debugLevel 149field sets the debug level on the node. 150At level of 2 or greater, detected loops are logged. 151The default level is 1. 152.Pp 153The 154.Va loopTimeout 155determines how long (in seconds) a looped link is muted. 156The default is 60 seconds. 157The 158.Va maxStaleness 159parameter determines how long a period of inactivity before 160a host's entry is forgotten. 161The default is 15 minutes. 162The 163.Va minStableAge 164determines how quickly a host must jump from one link to another 165before we declare a loopback condition. 166The default is one second. 167.It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig 168Returns the current configuration as a 169.Vt "struct ng_bridge_config" . 170.It Dv NGM_BRIDGE_RESET Pq Ar reset 171Causes the node to forget all hosts and unmute all links. 172The node configuration is not changed. 173.It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats 174This command takes a four byte link number as an argument and 175returns a 176.Vt "struct ng_bridge_link_stats" 177containing statistics for the corresponding 178.Ar link , 179which must be currently connected: 180.Bd -literal -offset 0n 181/* Statistics structure (one for each link) */ 182struct ng_bridge_link_stats { 183 uint64_t recvOctets; /* total octets rec'd on link */ 184 uint64_t recvPackets; /* total pkts rec'd on link */ 185 uint64_t recvMulticasts; /* multicast pkts rec'd on link */ 186 uint64_t recvBroadcasts; /* broadcast pkts rec'd on link */ 187 uint64_t recvUnknown; /* pkts rec'd with unknown dest addr */ 188 uint64_t recvRunts; /* pkts rec'd less than 14 bytes */ 189 uint64_t recvInvalid; /* pkts rec'd with bogus source addr */ 190 uint64_t xmitOctets; /* total octets xmit'd on link */ 191 uint64_t xmitPackets; /* total pkts xmit'd on link */ 192 uint64_t xmitMulticasts; /* multicast pkts xmit'd on link */ 193 uint64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ 194 uint64_t loopDrops; /* pkts dropped due to loopback */ 195 uint64_t loopDetects; /* number of loop detections */ 196 uint64_t memoryFailures; /* times couldn't get mem or mbuf */ 197}; 198.Ed 199.Pp 200Negative numbers refer to the 201.Ar uplink 202hooks. 203So querying for -7 will get the statistics for hook 204.Ar uplink7 . 205.It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats 206This command takes a four byte link number as an argument and 207clears the statistics for that link. 208.It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats 209Same as 210.Dv NGM_BRIDGE_GET_STATS , 211but also atomically clears the statistics as well. 212.It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable 213Returns the current host mapping table used to direct packets, in a 214.Vt "struct ng_bridge_host_ary" . 215.It Dv NGM_BRIDGE_SET_PERSISTENT Pq Ar setpersistent 216This command sets the persistent flag on the node, and takes no arguments. 217.It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost 218This command takes a 219.Vt "struct ng_bridge_move_host" 220as an argument. 221It assigns the MAC 222.Va addr 223to the 224.Va hook . 225If the 226.Va hook 227is the empty string, the incoming hook of the control message is 228used as fallback. 229.Pp 230If necessary, the MAC is removed from the currently assigned hook and 231moved to the new one. 232If the MAC is moved faster than 233.Va minStableAge , 234the hook is considered as a loop and will block traffic for 235.Va loopTimeout 236seconds. 237.Bd -literal -offset 0n 238struct ng_bridge_move_host { 239 u_char addr[ETHER_ADDR_LEN]; /* ethernet address */ 240 char hook[NG_HOOKSIZ]; /* link where addr can be found */ 241}; 242.Ed 243.El 244.Sh SHUTDOWN 245This node shuts down upon receipt of a 246.Dv NGM_SHUTDOWN 247control message, or when all hooks have been disconnected. 248Setting the persistent flag via a 249.Dv NGM_BRIDGE_SET_PERSISTENT 250control message disables automatic node shutdown when the last hook gets 251disconnected. 252.Sh FILES 253.Bl -tag -width XXXXXXXX -compact 254.It Pa /usr/share/examples/netgraph/ether.bridge 255Example script showing how to set up a bridging network 256.El 257.Sh SEE ALSO 258.Xr if_bridge 4 , 259.Xr netgraph 4 , 260.Xr ng_ether 4 , 261.Xr ng_hub 4 , 262.Xr ng_one2many 4 , 263.Xr ngctl 8 264.Sh HISTORY 265The 266.Nm 267node type was implemented in 268.Fx 4.2 . 269.Sh AUTHORS 270.An Archie Cobbs Aq Mt archie@FreeBSD.org 271