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 the 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 non-zero value, newly created bridge will inherit MAC address
100 from its first member instead of choosing random link-level address.
101 This will provide more predictable bridge MAC without any
102 additional configuration, but currently this feature is known
103 to break some L2 protocols, for example PPPoE that is provided
108 Now 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, and 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 All the bridged member interfaces need to be up in order to pass network traffic.
122 These can be enabled using
125 .Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up"
129 The MTU of the first member interface to be added is used as the bridge MTU.
130 All additional members are required to have exactly the same value.
132 The TXCSUM capability is disabled for any interface added to the bridge, and it
133 is restored when the interface is removed again.
137 where the packets are discarded after
139 processing, and are not processed or forwarded further.
140 This can be used to multiplex the input of two or more interfaces into a single
143 This is useful for reconstructing the traffic for network taps
144 that transmit the RX/TX signals out through two separate interfaces.
149 address family on bridge interfaces.
152 variable configures an IPv6 link-local address on
155 .Bd -literal -offset indent
156 ifconfig_bridge0_ipv6="up"
159 or in a more explicit manner:
160 .Bd -literal -offset indent
161 ifconfig_bridge0_ipv6="inet6 auto_linklocal"
166 address family has a concept of scope zone.
167 Bridging multiple interfaces change the zone configuration because
168 multiple links are merged to each other and form a new single link
169 while the member interfaces still work individually.
170 This means each member interface still has a separate link-local scope
173 interface has another single,
174 aggregated link-local scope zone at the same time.
175 This situation is clearly against the description
176 .Qq zones of the same scope cannot overlap
179 Although it works in most cases,
180 it can cause some conterintuitive or undesirable behavior in some
181 edge cases when both of the
183 interface and one of the member interface have an IPv6 address
184 and applications use both of them.
186 To prevent this situation,
188 checks whether an link-local scoped IPv6 address is configured on
189 a member interface to be added and the
194 interface has IPv6 addresses,
195 IPv6 addresses on the member interface will be automatically removed
196 before the interface is added.
199 interface and the existing member interfaces do not have one,
200 adding an interface with IPv6 addresses as a new member interface is allowed.
201 These means only one interface in the link-local scope zone where the
203 interface forms can have link-local scoped IPv6 addresses.
209 interface flag are not enabled by default on
212 .Va net.inet6.ip6.accept_rtadv
214 .Va net.inet6.ip6.auto_linklocal
221 driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
222 backwards compatibility with the legacy Spanning Tree Protocol (STP).
223 Spanning Tree is used to detect and remove loops in a network topology.
225 RSTP provides faster spanning tree convergence than legacy STP, the protocol
226 will exchange information with neighbouring switches to quickly transition to
227 forwarding without creating loops.
229 The code will default to RSTP mode but will downgrade any port connected to a
230 legacy STP network so is fully backward compatible.
231 A bridge can be forced to operate in STP mode without rapid state transitions
237 The bridge can log STP port changes to
240 .Va net.link.bridge.log_stp
245 Packet filtering can be used with any firewall package that hooks in via the
248 When filtering is enabled, bridged packets will pass through the filter
249 inbound on the originating interface, on the bridge interface and outbound on
250 the appropriate interfaces.
251 Either stage can be disabled.
252 The filtering behaviour can be controlled using
254 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
255 .It Va net.link.bridge.pfil_onlyip
256 Controls the handling of non-IP packets which are not passed to
260 to only allow IP packets to pass (subject to firewall rules), set to
262 to unconditionally pass all non-IP Ethernet frames.
263 .It Va net.link.bridge.pfil_member
266 to enable filtering on the incoming and outgoing member interfaces, set
270 .It Va net.link.bridge.pfil_bridge
273 to enable filtering on the bridge interface, set
277 .It Va net.link.bridge.pfil_local_phys
280 to additionally filter on the physical interface for locally destined packets.
283 to disable this feature.
284 .It Va net.link.bridge.ipfw
287 to enable layer2 filtering with
292 This needs to be enabled for
301 will be disabled so that IPFW
302 is not run twice; these can be re-enabled if desired.
303 .It Va net.link.bridge.ipfw_arp
306 to enable layer2 ARP filtering with
316 ARP and REVARP packets are forwarded without being filtered and others
317 that are not IP nor IPv6 packets are not forwarded when
320 IPFW can filter Ethernet types using
322 so all packets are passed to
323 the filter for processing.
325 The packets originating from the bridging host will be seen by
326 the filter on the interface that is looked up in the routing
329 The packets destined to the bridging host will be seen by the filter
330 on the interface with the MAC address equal to the packet's destination
332 There are situations when some of the bridge members are sharing
333 the same MAC address (for example the
335 interfaces: they are currently sharing the
336 MAC address of the parent physical interface).
337 It is not possible to distinguish between these interfaces using
338 their MAC address, excluding the case when the packet's destination
339 MAC address is equal to the MAC address of the interface on which
340 the packet was entered to the system.
341 In this case the filter will see the incoming packet on this
343 In all other cases the interface seen by the packet filter is chosen
344 from the list of bridge members with the same MAC address and the
345 result strongly depends on the member addition sequence and the
346 actual implementation of
348 It is not recommended to rely on the order chosen by the current
350 implementation: it can be changed in the future.
352 The previous paragraph is best illustrated with the following
357 the MAC address of the incoming packet's destination is
358 .Nm nn:nn:nn:nn:nn:nn ,
360 the interface on which packet entered the system is
365 .Nm xx:xx:xx:xx:xx:xx ,
367 there are possibly other bridge members with the same MAC address
368 .Nm xx:xx:xx:xx:xx:xx ,
370 the bridge has more than one interface that are sharing the
372 .Nm yy:yy:yy:yy:yy:yy ;
379 Then if the MAC address
380 .Nm nn:nn:nn:nn:nn:nn
382 .Nm xx:xx:xx:xx:xx:xx
383 then the filter will see the packet on the interface
385 no matter if there are any other bridge members carrying the same
387 But if the MAC address
388 .Nm nn:nn:nn:nn:nn:nn
390 .Nm yy:yy:yy:yy:yy:yy
391 then the interface that will be seen by the filter is one of the
393 It is not possible to predict the name of the actual interface
394 without the knowledge of the system state and the
396 implementation details.
398 This problem arises for any bridge members that are sharing the same
399 MAC address, not only to the
401 ones: they we taken just as the example of such situation.
402 So if one wants the filter the locally destined packets based on
403 their interface name, one should be aware of this implication.
404 The described situation will appear at least on the filtering bridges
405 that are doing IP-forwarding; in some of such cases it is better
406 to assign the IP address only to the
408 interface and not to the bridge members.
410 .Va net.link.bridge.pfil_local_phys
411 will let you do the additional filtering on the physical interface.
413 The following when placed in the file
415 will cause a bridge called
417 to be created, and will add the interfaces
421 to the bridge, and then enable packet forwarding.
422 Such a configuration could be used to implement a simple
423 802.11-to-Ethernet bridge (assuming the 802.11 interface is
425 .Bd -literal -offset indent
426 cloned_interfaces="bridge0"
427 ifconfig_bridge0="addm wlan0 addm fxp0 up"
430 For the bridge to forward packets all member interfaces and the bridge need
432 The above example would also require:
433 .Bd -literal -offset indent
434 create_args_wlan0="wlanmode hostap"
435 ifconfig_wlan0="up ssid my_ap mode 11g"
439 Consider a system with two 4-port Ethernet boards.
440 The following will cause a bridge consisting of all 8 ports with Rapid Spanning
441 Tree enabled to be created:
442 .Bd -literal -offset indent
443 ifconfig bridge0 create
445 addm fxp0 stp fxp0 \e
446 addm fxp1 stp fxp1 \e
447 addm fxp2 stp fxp2 \e
448 addm fxp3 stp fxp3 \e
449 addm fxp4 stp fxp4 \e
450 addm fxp5 stp fxp5 \e
451 addm fxp6 stp fxp6 \e
452 addm fxp7 stp fxp7 \e
456 The bridge can be used as a regular host interface at the same time as bridging
457 between its member ports.
458 In this example, the bridge connects em0 and em1, and will receive its IP
459 address through DHCP:
460 .Bd -literal -offset indent
461 cloned_interfaces="bridge0"
462 ifconfig_bridge0="addm em0 addm em1 DHCP"
467 The bridge can tunnel Ethernet across an IP internet using the EtherIP
469 This can be combined with
471 to provide an encrypted connection.
474 interface and set the local and remote IP addresses for the
475 tunnel, these are reversed on the remote bridge.
476 .Bd -literal -offset indent
478 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
479 ifconfig bridge0 create
480 ifconfig bridge0 addm fxp0 addm gif0 up
485 6.1, 6.2, 6.3, 7.0, 7.1, and 7.2 have a bug in the EtherIP protocol.
486 For more details and workaround, see
498 driver first appeared in
504 driver was originally written by
506 .Aq jason@thought.net
507 as part of an undergraduate independent study at the University of
508 North Carolina at Greensboro.
512 driver has been heavily modified from the original version by
514 .Aq thorpej@wasabisystems.com .
516 Rapid Spanning Tree Protocol (RSTP) support was added by
518 .Aq thompsa@FreeBSD.org .
522 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
523 network devices, with exactly the same interface MTU size as the bridge device.