.\" Copyright (c) 2000 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd August 31, 2000 .Dt NG_BRIDGE 4 .Os FreeBSD .Sh NAME .Nm ng_bridge .Nd Ethernet bridging netgraph node type .Sh SYNOPSIS .Fd #include .Fd #include .Sh DESCRIPTION The .Nm 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. .Sh LOOP DETECTION The .Nm 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. .Pp A looped back link will be temporarily muted, i.e., all traffic received on that link is ignored. .Sh IPFW PROCESSING Processing of IP packets via the .Xr ipfirewall 4 mechanism on a per-link basis is not yet implemented. .Sh HOOKS This node type supports up to .Dv NG_BRIDGE_MAX_LINKS hooks. Each connected hook represents a bridged link. The hooks are named .Dv link0 , .Dv link1 , etc. Typically these hooks are connected to the .Dv lower hooks of one or more .Xr ng_ether nodes. To connect the host machine to a bridged network, simply connect the .Dv upper hook of an .Xr ng_ether node to the bridge node. .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_BRIDGE_SET_CONFIG Set the node configuration. This command takes a .Dv "struct ng_bridge_config" as an argument: .Bd -literal -offset 0 /* Node configuration structure */ struct ng_bridge_config { u_char ipfw[NG_BRIDGE_MAX_LINKS]; /* enable ipfw */ u_char debugLevel; /* debug level */ u_int32_t loopTimeout; /* link loopback mute time */ u_int32_t maxStaleness; /* max host age before nuking */ u_int32_t minStableAge; /* min time for a stable host */ }; .Ed .Pp The .Dv ipfw array enables .Xr ipfirewall 4 processing of IP packets received on the corresponding links. The .Dv debugLevel field sets the debug level on the node. At level of 2 or greater, detected loops are logged. The default level is 1. .Pp The .Dv loopTimeout determines how long (in seconds) a looped link is muted. The default is 60 seconds. The .Dv maxStaleness parameter determines how long a period of inactivity before a host's entry is forgotten. The default is 15 minutes. The .Dv minStableAge determines how quickly a host must jump from one link to another before we declare a loopback condition. The default is one second. .Pp .It Dv NGM_BRIDGE_GET_CONFIG Returns the current configuration as a .Dv "struct ng_bridge_config" . .It Dv NGM_BRIDGE_RESET Causes the node to forget all hosts and unmute all links. The node configuration is not changed. .It Dv NGM_BRIDGE_GET_STATS This command takes a four byte link number as an argument and returns a .Dv "struct ng_bridge_link_stats" containing statistics for the corresponding link, which must be currently connected: .Bd -literal -offset 0 /* Statistics structure (one for each link) */ struct ng_bridge_link_stats { u_int64_t recvOctets; /* total octets rec'd on link */ u_int64_t recvPackets; /* total pkts rec'd on link */ u_int64_t recvMulticasts; /* multicast pkts rec'd on link */ u_int64_t recvBroadcasts; /* broadcast pkts rec'd on link */ u_int64_t recvUnknown; /* pkts rec'd with unknown dest addr */ u_int64_t recvRunts; /* pkts rec'd less than 14 bytes */ u_int64_t recvInvalid; /* pkts rec'd with bogus source addr */ u_int64_t xmitOctets; /* total octets xmit'd on link */ u_int64_t xmitPackets; /* total pkts xmit'd on link */ u_int64_t xmitMulticasts; /* multicast pkts xmit'd on link */ u_int64_t xmitBroadcasts; /* broadcast pkts xmit'd on link */ u_int64_t loopDrops; /* pkts dropped due to loopback */ u_int64_t loopDetects; /* number of loop detections */ u_int64_t memoryFailures; /* times couldn't get mem or mbuf */ }; .Ed .It Dv NGM_BRIDGE_CLR_STATS This command takes a four byte link number as an argument and clears the statistics for that link. .It Dv NGM_BRIDGE_GETCLR_STATS Same as .Dv NGM_BRIDGE_GET_STATS , but also atomically clears the statistics as well. .It Dv NGM_BRIDGE_GET_TABLE Returns the current host mapping table used to direct packets, in a .Dv "struct ng_bridge_host_ary" . .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh FILES .Bl -tag -width XXXXXXXX -compact .It Pa /usr/share/examples/netgraph/ether.bridge Example script showing how to set up a bridging network .El .Sh SEE ALSO .Xr bridge 4 , .Xr netgraph 4 , .Xr ng_ether 4 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 4.2 . .Sh AUTHORS .An Archie Cobbs Aq archie@FreeBSD.org