1 .\" Copyright (c) 2000 Whistle Communications, Inc.
2 .\" All rights reserved.
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.
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
33 .\" Author: Archie Cobbs <archie@FreeBSD.org>
42 .Nd Ethernet bridging netgraph node type
45 .In netgraph/ng_bridge.h
49 node type performs Ethernet bridging over one or more links.
50 Each link (represented by a connected hook) is used to transmit
51 and receive raw Ethernet frames.
52 As packets are received, the node learns which link each
54 Packets unicast to a known host are directed out the appropriate
55 link only, and other links are spared the traffic.
56 This behavior is in contrast to a hub, which always forwards
57 every received packet to every other link.
61 node incorporates a simple loop detection algorithm.
62 A loop is when two ports are connected to the same physical medium.
63 Loops are important to avoid because of packet storms, which severely
65 A packet storm results when the same packet is sent and received
67 If a host is detected on link A, and is then detected on link B
68 within a certain time period after first being detected on link A,
69 then link B is considered to be a looped back link.
70 The time period is called the minimum stable time.
72 A looped back link will be temporarily muted, i.e., all traffic
73 received on that link is ignored.
75 Processing of IP packets via the
77 mechanism on a per-link basis is not yet implemented.
79 This node type supports an unlimited number of hooks.
80 Each connected hook represents a bridged link.
85 Typically these hooks are connected to the
90 To connect the host machine to a bridged network, simply connect the
94 node to the bridge node.
96 Instead of naming a hook
98 the hook might be also named
100 The node does not learn MAC addresses on uplink hooks, which keeps
101 the internal address table small.
102 This way it is desirable to connect the
108 hook of the bridge, and ignore the complexity of the outside world.
109 Frames with unknown MACs are always sent out to
111 hooks, so no functionality is lost.
113 Frames with unknown destination MAC addresses are replicated to any
114 available hook, unless the first connected hook is an
117 In this case the node assumes, that all unknown MAC addresses are
120 hooks and only those hooks will be used to send out frames with
121 unknown destination MACs.
122 If the first connected hook is an
124 hook, the node will replicate such frames to all types of hooks,
127 hooks are connected later.
129 This node type supports the generic control messages, plus the
132 .It Dv NGM_BRIDGE_SET_CONFIG Pq Ar setconfig
133 Set the node configuration.
135 .Vt "struct ng_bridge_config"
137 .Bd -literal -offset 0n
138 /* Node configuration structure */
139 struct 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 */
149 field sets the debug level on the node.
150 At level of 2 or greater, detected loops are logged.
151 The default level is 1.
155 determines how long (in seconds) a looped link is muted.
156 The default is 60 seconds.
159 parameter determines how long a period of inactivity before
160 a host's entry is forgotten.
161 The default is 15 minutes.
164 determines how quickly a host must jump from one link to another
165 before we declare a loopback condition.
166 The default is one second.
167 .It Dv NGM_BRIDGE_GET_CONFIG Pq Ar getconfig
168 Returns the current configuration as a
169 .Vt "struct ng_bridge_config" .
170 .It Dv NGM_BRIDGE_RESET Pq Ar reset
171 Causes the node to forget all hosts and unmute all links.
172 The node configuration is not changed.
173 .It Dv NGM_BRIDGE_GET_STATS Pq Ar getstats
174 This command takes a four byte link number as an argument and
176 .Vt "struct ng_bridge_link_stats"
177 containing statistics for the corresponding
179 which must be currently connected:
180 .Bd -literal -offset 0n
181 /* Statistics structure (one for each link) */
182 struct 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 */
200 Negative numbers refer to the
203 So querying for -7 will get the statistics for hook
205 .It Dv NGM_BRIDGE_CLR_STATS Pq Ar clrstats
206 This command takes a four byte link number as an argument and
207 clears the statistics for that link.
208 .It Dv NGM_BRIDGE_GETCLR_STATS Pq Ar getclrstats
210 .Dv NGM_BRIDGE_GET_STATS ,
211 but also atomically clears the statistics as well.
212 .It Dv NGM_BRIDGE_GET_TABLE Pq Ar gettable
213 Returns 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
216 This command sets the persistent flag on the node, and takes no arguments.
217 .It Dv NGM_BRIDGE_MOVE_HOST Pq Ar movehost
219 .Vt "struct ng_bridge_move_host"
227 is the empty string, the incoming hook of the control message is
230 If necessary, the MAC is removed from the currently assigned hook and
231 moved to the new one.
232 If the MAC is moved faster than
234 the hook is considered as a loop and will block traffic for
237 .Bd -literal -offset 0n
238 struct ng_bridge_move_host {
239 u_char addr[ETHER_ADDR_LEN]; /* ethernet address */
240 char hook[NG_HOOKSIZ]; /* link where addr can be found */
245 This node shuts down upon receipt of a
247 control message, or when all hooks have been disconnected.
248 Setting the persistent flag via a
249 .Dv NGM_BRIDGE_SET_PERSISTENT
250 control message disables automatic node shutdown when the last hook gets
253 .Bl -tag -width XXXXXXXX -compact
254 .It Pa /usr/share/examples/netgraph/ether.bridge
255 Example script showing how to set up a bridging network
267 node type was implemented in
270 .An Archie Cobbs Aq Mt archie@FreeBSD.org