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 August 31, 2000 38.Dt NG_BRIDGE 4 39.Os FreeBSD 40.Sh NAME 41.Nm ng_bridge 42.Nd Ethernet bridging netgraph node type 43.Sh SYNOPSIS 44.Fd #include <netgraph/ng_bridge.h> 45.Sh DESCRIPTION 46The 47.Nm bridge 48node type performs Ethernet bridging over one or more links. 49Each link (represented by a connected hook) is used to transmit 50and receive raw Ethernet frames. 51As packets are received, the node learns which link each 52host resides on. 53Packets unicast to a known host are directed out the appropriate 54link only, and other links are spared the traffic. 55This behavior is in contrast to a hub, which always forwards 56every received packet to every other link. 57.Sh LOOP DETECTION 58The 59.Nm bridge 60node incorporates a simple loop detection algorithm. 61A loop is when two ports are connected to the same physical medium. 62Loops are important to avoid because of packet storms, which severely 63degrade performance. 64A packet storm results when the same packet is sent and received 65over and over again. 66If a host is detected on link A, and is then detected on link B 67within a certain time period after first being detected on link A, 68then link B is considered to be a looped back link. 69The time period is called the minimum stable time. 70.Pp 71A looped back link will be temporarily muted, i.e., all traffic 72received on that link is ignored. 73.Sh IPFW PROCESSING 74Processing of IP packets via the 75.Xr ipfirewall 4 76mechanism on a per-link basis is not yet implemented. 77.Sh HOOKS 78This node type supports up to 79.Dv NG_BRIDGE_MAX_LINKS 80hooks. 81Each connected hook represents a bridged link. 82The hooks are named 83.Dv link0 , 84.Dv link1 , 85etc. 86Typically these hooks are connected to the 87.Dv lower 88hooks of one or more 89.Xr ng_ether 90nodes. 91To connect the host machine to a bridged network, simply connect the 92.Dv upper 93hook of an 94.Xr ng_ether 95node to the bridge node. 96.Sh CONTROL MESSAGES 97This node type supports the generic control messages, plus the 98following: 99.Bl -tag -width foo 100.It Dv NGM_BRIDGE_SET_CONFIG 101Set the node configuration. 102This command takes a 103.Dv "struct ng_bridge_config" 104as an argument: 105.Bd -literal -offset 0 106/* Node configuration structure */ 107struct ng_bridge_config { 108 u_char ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */ 109 u_char debugLevel; /* debug level */ 110 u_int32_t loopTimeout; /* link loopback mute time */ 111 u_int32_t maxStaleness; /* max host age before nuking */ 112 u_int32_t minStableAge; /* min time for a stable host */ 113}; 114.Ed 115.Pp 116The 117.Dv ipfw 118array enables 119.Xr ipfirewall 4 120processing of IP packets received on the corresponding links. 121The 122.Dv debugLevel 123field sets the debug level on the node. 124At level of 2 or greater, detected loops are logged. 125The default level is 1. 126.Pp 127The 128.Dv loopTimeout 129determines how long (in seconds) a looped link is muted. 130The default is 60 seconds. 131The 132.Dv maxStaleness 133parameter determines how long a period of inactivity before 134a host's entry is forgotten. 135The default is 15 minutes. 136The 137.Dv minStableAge 138determines how quickly a host must jump from one link to another 139before we declare a loopback condition. 140The default is one second. 141.Pp 142.It Dv NGM_BRIDGE_GET_CONFIG 143Returns the current configuration as a 144.Dv "struct ng_bridge_config" . 145.It Dv NGM_BRIDGE_RESET 146Causes the node to forget all hosts and unmute all links. 147The node configuration is not changed. 148.It Dv NGM_BRIDGE_GET_STATS 149This command takes a four byte link number as an argument and 150returns a 151.Dv "struct ng_bridge_link_stats" 152containing statistics for the corresponding link, which must be 153currently connected: 154.Bd -literal -offset 0 155/* Statistics structure (one for each link) */ 156struct ng_bridge_link_stats { 157 u_int64_t recvOctets; /* total octets rec'd on link */ 158 u_int64_t recvPackets; /* total pkts rec'd on link */ 159 u_int64_t recvMulticasts; /* multicast pkts rec'd on link */ 160 u_int64_t recvBroadcasts; /* broadcast pkts rec'd on link */ 161 u_int64_t recvUnknown; /* pkts rec'd with unknown dest addr */ 162 u_int64_t recvRunts; /* pkts rec'd less than 14 bytes */ 163 u_int64_t recvInvalid; /* pkts rec'd with bogus source addr */ 164 u_int64_t xmitOctets; /* total octets xmit'd on link */ 165 u_int64_t xmitPackets; /* total pkts xmit'd on link */ 166 u_int64_t xmitMulticasts; /* multicast pkts xmit'd on link */ 167 u_int64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ 168 u_int64_t loopDrops; /* pkts dropped due to loopback */ 169 u_int64_t loopDetects; /* number of loop detections */ 170 u_int64_t memoryFailures; /* times couldn't get mem or mbuf */ 171}; 172.Ed 173.It Dv NGM_BRIDGE_CLR_STATS 174This command takes a four byte link number as an argument and 175clears the statistics for that link. 176.It Dv NGM_BRIDGE_GETCLR_STATS 177Same as 178.Dv NGM_BRIDGE_GET_STATS , 179but also atomically clears the statistics as well. 180.It Dv NGM_BRIDGE_GET_TABLE 181Returns the current host mapping table used to direct packets, in a 182.Dv "struct ng_bridge_host_ary" . 183.El 184.Sh SHUTDOWN 185This node shuts down upon receipt of a 186.Dv NGM_SHUTDOWN 187control message, or when all hooks have been disconnected. 188.Sh FILES 189.Bl -tag -width XXXXXXXX -compact 190.It Pa /usr/share/examples/netgraph/ether.bridge 191Example script showing how to set up a bridging network 192.El 193.Sh SEE ALSO 194.Xr bridge 4 , 195.Xr netgraph 4 , 196.Xr ng_ether 4 , 197.Xr ngctl 8 198.Sh HISTORY 199The 200.Nm 201node type was implemented in 202.Fx 4.2 . 203.Sh AUTHORS 204.An Archie Cobbs Aq archie@FreeBSD.org 205