1 .\" $NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $
3 .\" Copyright 2001 Wasabi Systems, Inc.
4 .\" All rights reserved.
6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed for the NetBSD Project by
19 .\" Wasabi Systems, Inc.
20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
21 .\" or promote products derived from this software without specific prior
22 .\" written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC
28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
43 .Nd network bridge device
45 To compile this driver into the kernel,
46 place the following line in your
47 kernel configuration file:
48 .Bd -ragged -offset indent
49 .Cd "device if_bridge"
52 Alternatively, to load the driver as a
53 module at boot time, place the following lines in
55 .Bd -literal -offset indent
62 driver creates a logical link between two or more IEEE 802 networks
64 .Dq "similar enough" )
66 For example, it is possible to bridge Ethernet and 802.11 networks together,
67 but it is not possible to bridge Ethernet and Token Ring together.
71 interface is created at runtime using interface cloning.
73 most easily done with the
83 interface randomly chooses a link (MAC) address in the range reserved for
84 locally administered addresses when it is created.
85 This address is guaranteed to be unique
89 interfaces on the local machine.
90 Thus you can theoretically have two bridges on different machines with
91 the same link addresses.
92 The address can be changed by assigning the desired link address using
98 .Va net.link.bridge.inherit_mac
99 has a non-zero value, the newly created bridge will inherit the MAC
100 address from its first member instead of choosing a random link-level
102 This will provide more predictable bridge MAC addresses without any
103 additional configuration, but currently this feature is known to break
104 some L2 protocols, for example PPPoE that is provided by
108 Currently this feature is considered as experimental and is turned off
111 A bridge can be used to provide several services, such as a simple
112 802.11-to-Ethernet bridge for wireless hosts, or traffic isolation.
114 A bridge works like a switch, forwarding traffic from one interface
116 Multicast and broadcast packets are always forwarded to all
117 interfaces that are part of the bridge.
118 For unicast traffic, the bridge learns which MAC addresses are associated
119 with which interfaces and will forward the traffic selectively.
121 By default the bridge logs MAC address port flapping to
123 This behavior can be disabled by setting the
126 .Va net.link.bridge.log_mac_flap
130 All the bridged member interfaces need to be up in order to pass network traffic.
131 These can be enabled using
134 .Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up"
138 The MTU of the first member interface to be added is used as the bridge MTU.
139 All additional members will have their MTU changed to match.
140 If the MTU of a bridge is changed after its creation, the MTU of all member
141 interfaces is also changed to match.
143 The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the
144 bridge are disabled if any of the interfaces do not support/enable them.
145 The LRO capability is always disabled.
146 All the capabilities are restored when the interface is removed from the bridge.
147 Changing capabilities at run-time may cause NIC reinit and a link flap.
151 where the packets are discarded after
153 processing, and are not processed or forwarded further.
154 This can be used to multiplex the input of two or more interfaces into a single
157 This is useful for reconstructing the traffic for network taps
158 that transmit the RX/TX signals out through two separate interfaces.
163 address family on bridge interfaces.
166 variable configures an IPv6 link-local address on
169 .Bd -literal -offset indent
170 ifconfig_bridge0_ipv6="up"
173 or in a more explicit manner:
174 .Bd -literal -offset indent
175 ifconfig_bridge0_ipv6="inet6 auto_linklocal"
180 address family has a concept of scope zone.
181 Bridging multiple interfaces changes the zone configuration because
182 multiple links are merged to each other and form a new single link
183 while the member interfaces still work individually.
184 This means each member interface still has a separate link-local scope
187 interface has another single,
188 aggregated link-local scope zone at the same time.
189 This situation is clearly against the description
190 .Qq zones of the same scope cannot overlap
193 Although it works in most cases,
194 it can cause some counterintuitive or undesirable behavior in some
195 edge cases when both, the
197 interface and one of the member interfaces, have an IPv6 address
198 and applications use both of them.
200 To prevent this situation,
202 checks whether a link-local scoped IPv6 address is configured on
203 a member interface to be added and the
208 interface has IPv6 addresses,
209 IPv6 addresses on the member interface will be automatically removed
210 before the interface is added.
212 This behavior can be disabled by setting
215 .Va net.link.bridge.allow_llz_overlap
223 interface flags are not enabled by default on
226 .Va net.inet6.ip6.accept_rtadv
228 .Va net.inet6.ip6.auto_linklocal
234 driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
235 backwards compatibility with the legacy Spanning Tree Protocol (STP).
236 Spanning Tree is used to detect and remove loops in a network topology.
238 RSTP provides faster spanning tree convergence than legacy STP, the protocol
239 will exchange information with neighbouring switches to quickly transition to
240 forwarding without creating loops.
242 The code will default to RSTP mode but will downgrade any port connected to a
243 legacy STP network so is fully backward compatible.
244 A bridge can be forced to operate in STP mode without rapid state transitions
250 The bridge can log STP port changes to
253 .Va net.link.bridge.log_stp
257 Packet filtering can be used with any firewall package that hooks in via the
260 When filtering is enabled, bridged packets will pass through the filter
261 inbound on the originating interface, on the bridge interface and outbound on
262 the appropriate interfaces.
263 Either stage can be disabled.
264 The filtering behavior can be controlled using
266 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
267 .It Va net.link.bridge.pfil_onlyip
268 Controls the handling of non-IP packets which are not passed to
272 to only allow IP packets to pass (subject to firewall rules), set to
274 to unconditionally pass all non-IP Ethernet frames.
275 .It Va net.link.bridge.pfil_member
278 to enable filtering on the incoming and outgoing member interfaces, set
282 .It Va net.link.bridge.pfil_bridge
285 to enable filtering on the bridge interface, set
289 .It Va net.link.bridge.pfil_local_phys
292 to additionally filter on the physical interface for locally destined packets.
295 to disable this feature.
296 .It Va net.link.bridge.ipfw
299 to enable layer2 filtering with
304 This needs to be enabled for
313 will be disabled so that IPFW
314 is not run twice; these can be re-enabled if desired.
315 .It Va net.link.bridge.ipfw_arp
318 to enable layer2 ARP filtering with
328 ARP and REVARP packets are forwarded without being filtered and others
329 that are not IP nor IPv6 packets are not forwarded when
332 IPFW can filter Ethernet types using
334 so all packets are passed to
335 the filter for processing.
337 The packets originating from the bridging host will be seen by
338 the filter on the interface that is looked up in the routing
341 The packets destined to the bridging host will be seen by the filter
342 on the interface with the MAC address equal to the packet's destination
344 There are situations when some of the bridge members are sharing
345 the same MAC address (for example the
347 interfaces: they are currently sharing the
348 MAC address of the parent physical interface).
349 It is not possible to distinguish between these interfaces using
350 their MAC address, excluding the case when the packet's destination
351 MAC address is equal to the MAC address of the interface on which
352 the packet was entered to the system.
353 In this case the filter will see the incoming packet on this
355 In all other cases the interface seen by the packet filter is chosen
356 from the list of bridge members with the same MAC address and the
357 result strongly depends on the member addition sequence and the
358 actual implementation of
360 It is not recommended to rely on the order chosen by the current
362 implementation since it may change in the future.
364 The previous paragraph is best illustrated with the following
369 the MAC address of the incoming packet's destination is
370 .Nm nn:nn:nn:nn:nn:nn ,
372 the interface on which packet entered the system is
377 .Nm xx:xx:xx:xx:xx:xx ,
379 there are possibly other bridge members with the same MAC address
380 .Nm xx:xx:xx:xx:xx:xx ,
382 the bridge has more than one interface that are sharing the
384 .Nm yy:yy:yy:yy:yy:yy ;
392 .Nm nn:nn:nn:nn:nn:nn
394 .Nm xx:xx:xx:xx:xx:xx
395 the filter will see the packet on interface
397 no matter if there are any other bridge members carrying the same
399 But if the MAC address
400 .Nm nn:nn:nn:nn:nn:nn
402 .Nm yy:yy:yy:yy:yy:yy
403 then the interface that will be seen by the filter is one of the
405 It is not possible to predict the name of the actual interface
406 without the knowledge of the system state and the
408 implementation details.
410 This problem arises for any bridge members that are sharing the same
411 MAC address, not only to the
413 ones: they were taken just as an example of such a situation.
414 So if one wants to filter the locally destined packets based on
415 their interface name, one should be aware of this implication.
416 The described situation will appear at least on the filtering bridges
417 that are doing IP-forwarding; in some of such cases it is better
418 to assign the IP address only to the
420 interface and not to the bridge members.
422 .Va net.link.bridge.pfil_local_phys
423 will let you do the additional filtering on the physical interface.
426 applications may open a bridge interface in emulated mode.
427 The netmap application will receive all packets which arrive from member
429 In particular, packets which would otherwise be forwarded to another
430 member interface will be received by the netmap application.
434 application transmits a packet to the host stack via the bridge interface,
436 receive it and attempts to determine its
438 interface by looking up the source MAC address in the interface's learning
440 Packets for which no matching source interface is found are dropped and the
441 input error counter is incremented.
442 If a matching source interface is found,
444 treats the packet as though it was received from the corresponding interface
445 and handles it normally without passing the packet back to
448 The following when placed in the file
450 will cause a bridge called
452 to be created, and will add the interfaces
456 to the bridge, and then enable packet forwarding.
457 Such a configuration could be used to implement a simple
458 802.11-to-Ethernet bridge (assuming the 802.11 interface is
460 .Bd -literal -offset indent
461 cloned_interfaces="bridge0"
462 ifconfig_bridge0="addm wlan0 addm fxp0 up"
465 For the bridge to forward packets,
466 all member interfaces and the bridge need to be up.
467 The above example would also require:
468 .Bd -literal -offset indent
469 create_args_wlan0="wlanmode hostap"
470 ifconfig_wlan0="up ssid my_ap mode 11g"
474 Consider a system with two 4-port Ethernet boards.
475 The following will cause a bridge consisting of all 8 ports with Rapid Spanning
476 Tree enabled to be created:
477 .Bd -literal -offset indent
478 ifconfig bridge0 create
480 addm fxp0 stp fxp0 \e
481 addm fxp1 stp fxp1 \e
482 addm fxp2 stp fxp2 \e
483 addm fxp3 stp fxp3 \e
484 addm fxp4 stp fxp4 \e
485 addm fxp5 stp fxp5 \e
486 addm fxp6 stp fxp6 \e
487 addm fxp7 stp fxp7 \e
491 The bridge can be used as a regular host interface at the same time as bridging
492 between its member ports.
493 In this example, the bridge connects em0 and em1, and will receive its IP
494 address through DHCP:
495 .Bd -literal -offset indent
496 cloned_interfaces="bridge0"
497 ifconfig_bridge0="addm em0 addm em1 DHCP"
502 The bridge can tunnel Ethernet across an IP internet using the EtherIP
504 This can be combined with
506 to provide an encrypted connection.
509 interface and set the local and remote IP addresses for the
510 tunnel, these are reversed on the remote bridge.
511 .Bd -literal -offset indent
513 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
514 ifconfig bridge0 create
515 ifconfig bridge0 addm fxp0 addm gif0 up
527 driver first appeared in
533 driver was originally written by
534 .An Jason L. Wright Aq Mt jason@thought.net
535 as part of an undergraduate independent study at the University of
536 North Carolina at Greensboro.
540 driver has been heavily modified from the original version by
541 .An Jason R. Thorpe Aq Mt thorpej@wasabisystems.com .
543 Rapid Spanning Tree Protocol (RSTP) support was added by
544 .An Andrew Thompson Aq Mt thompsa@FreeBSD.org .
548 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
549 network devices, which can be configured with the same MTU size as the bridge