xref: /freebsd/share/man/man4/bridge.4 (revision 058ac3e8063366dafa634d9107642e12b038bf09)
1.\"	$NetBSD: bridge.4,v 1.5 2004/01/31 20:14:11 jdc Exp $
2.\"
3.\" Copyright 2001 Wasabi Systems, Inc.
4.\" All rights reserved.
5.\"
6.\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.
23.\"
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.
35.\"
36.\" $FreeBSD$
37.\"
38.Dd September 7, 2022
39.Dt IF_BRIDGE 4
40.Os
41.Sh NAME
42.Nm if_bridge
43.Nd network bridge device
44.Sh SYNOPSIS
45To compile this driver into the kernel,
46place the following line in your
47kernel configuration file:
48.Bd -ragged -offset indent
49.Cd "device if_bridge"
50.Ed
51.Pp
52Alternatively, to load the driver as a
53module at boot time, place the following lines in
54.Xr loader.conf 5 :
55.Bd -literal -offset indent
56if_bridge_load="YES"
57bridgestp_load="YES"
58.Ed
59.Sh DESCRIPTION
60The
61.Nm
62driver creates a logical link between two or more IEEE 802 networks
63that use the same (or
64.Dq "similar enough" )
65framing format.
66For example, it is possible to bridge Ethernet and 802.11 networks together,
67but it is not possible to bridge Ethernet and Token Ring together.
68.Pp
69Each
70.Nm
71interface is created at runtime using interface cloning.
72This is
73most easily done with the
74.Xr ifconfig 8
75.Cm create
76command or using the
77.Va cloned_interfaces
78variable in
79.Xr rc.conf 5 .
80.Pp
81The
82.Nm
83interface randomly chooses a link (MAC) address in the range reserved for
84locally administered addresses when it is created.
85This address is guaranteed to be unique
86.Em only
87across all
88.Nm
89interfaces on the local machine.
90Thus you can theoretically have two bridges on different machines with
91the same link addresses.
92The address can be changed by assigning the desired link address using
93.Xr ifconfig 8 .
94.Pp
95If
96.Xr sysctl 8
97node
98.Va net.link.bridge.inherit_mac
99has a non-zero value, the newly created bridge will inherit the MAC
100address from its first member instead of choosing a random link-level
101address.
102This will provide more predictable bridge MAC addresses without any
103additional configuration, but currently this feature is known to break
104some L2 protocols, for example PPPoE that is provided by
105.Xr ng_pppoe 4
106and
107.Xr ppp 8 .
108Currently this feature is considered as experimental and is turned off
109by default.
110.Pp
111A bridge can be used to provide several services, such as a simple
112802.11-to-Ethernet bridge for wireless hosts, or traffic isolation.
113.Pp
114A bridge works like a switch, forwarding traffic from one interface
115to another.
116Multicast and broadcast packets are always forwarded to all
117interfaces that are part of the bridge.
118For unicast traffic, the bridge learns which MAC addresses are associated
119with which interfaces and will forward the traffic selectively.
120.Pp
121All the bridged member interfaces need to be up in order to pass network traffic.
122These can be enabled using
123.Xr ifconfig 8
124or
125.Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up"
126in
127.Xr rc.conf 5 .
128.Pp
129The MTU of the first member interface to be added is used as the bridge MTU.
130All additional members will have their MTU changed to match.
131If the MTU of a bridge is changed after its creation, the MTU of all member
132interfaces is also changed to match.
133.Pp
134The TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the
135bridge are disabled if any of the interfaces do not support/enable them.
136The LRO capability is always disabled.
137All the capabilities are restored when the interface is removed from the bridge.
138Changing capabilities at run-time may cause NIC reinit and a link flap.
139.Pp
140The bridge supports
141.Dq monitor mode ,
142where the packets are discarded after
143.Xr bpf 4
144processing, and are not processed or forwarded further.
145This can be used to multiplex the input of two or more interfaces into a single
146.Xr bpf 4
147stream.
148This is useful for reconstructing the traffic for network taps
149that transmit the RX/TX signals out through two separate interfaces.
150.Sh IPV6 SUPPORT
151.Nm
152supports the
153.Li AF_INET6
154address family on bridge interfaces.
155The following
156.Xr rc.conf 5
157variable configures an IPv6 link-local address on
158.Li bridge0
159interface:
160.Bd -literal -offset indent
161ifconfig_bridge0_ipv6="up"
162.Ed
163.Pp
164or in a more explicit manner:
165.Bd -literal -offset indent
166ifconfig_bridge0_ipv6="inet6 auto_linklocal"
167.Ed
168.Pp
169However, the
170.Li AF_INET6
171address family has a concept of scope zone.
172Bridging multiple interfaces changes the zone configuration because
173multiple links are merged to each other and form a new single link
174while the member interfaces still work individually.
175This means each member interface still has a separate link-local scope
176zone and the
177.Nm
178interface has another single,
179aggregated link-local scope zone at the same time.
180This situation is clearly against the description
181.Qq zones of the same scope cannot overlap
182in Section 5,
183RFC 4007.
184Although it works in most cases,
185it can cause some counterintuitive or undesirable behavior in some
186edge cases when both, the
187.Nm
188interface and one of the member interfaces, have an IPv6 address
189and applications use both of them.
190.Pp
191To prevent this situation,
192.Nm
193checks whether a link-local scoped IPv6 address is configured on
194a member interface to be added and the
195.Nm
196interface.
197When the
198.Nm
199interface has IPv6 addresses,
200IPv6 addresses on the member interface will be automatically removed
201before the interface is added.
202.Pp
203This behavior can be disabled by setting
204.Xr sysctl 8
205variable
206.Va net.link.bridge.allow_llz_overlap
207to
208.Li 1 .
209.Pp
210Note that
211.Li ACCEPT_RTADV
212and
213.Li AUTO_LINKLOCAL
214interface flags are not enabled by default on
215.Nm
216interfaces even when
217.Va net.inet6.ip6.accept_rtadv
218and/or
219.Va net.inet6.ip6.auto_linklocal
220is set to
221.Li 1 .
222.Sh SPANNING TREE
223The
224.Nm
225driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
226backwards compatibility with the legacy Spanning Tree Protocol (STP).
227Spanning Tree is used to detect and remove loops in a network topology.
228.Pp
229RSTP provides faster spanning tree convergence than legacy STP, the protocol
230will exchange information with neighbouring switches to quickly transition to
231forwarding without creating loops.
232.Pp
233The code will default to RSTP mode but will downgrade any port connected to a
234legacy STP network so is fully backward compatible.
235A bridge can be forced to operate in STP mode without rapid state transitions
236via the
237.Va proto
238command in
239.Xr ifconfig 8 .
240.Pp
241The bridge can log STP port changes to
242.Xr syslog 3
243by setting the
244.Va net.link.bridge.log_stp
245node using
246.Xr sysctl 8 .
247.Sh PACKET FILTERING
248Packet filtering can be used with any firewall package that hooks in via the
249.Xr pfil 9
250framework.
251When filtering is enabled, bridged packets will pass through the filter
252inbound on the originating interface, on the bridge interface and outbound on
253the appropriate interfaces.
254Either stage can be disabled.
255The filtering behavior can be controlled using
256.Xr sysctl 8 :
257.Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
258.It Va net.link.bridge.pfil_onlyip
259Controls the handling of non-IP packets which are not passed to
260.Xr pfil 9 .
261Set to
262.Li 1
263to only allow IP packets to pass (subject to firewall rules), set to
264.Li 0
265to unconditionally pass all non-IP Ethernet frames.
266.It Va net.link.bridge.pfil_member
267Set to
268.Li 1
269to enable filtering on the incoming and outgoing member interfaces, set
270to
271.Li 0
272to disable it.
273.It Va net.link.bridge.pfil_bridge
274Set to
275.Li 1
276to enable filtering on the bridge interface, set
277to
278.Li 0
279to disable it.
280.It Va net.link.bridge.pfil_local_phys
281Set to
282.Li 1
283to additionally filter on the physical interface for locally destined packets.
284Set to
285.Li 0
286to disable this feature.
287.It Va net.link.bridge.ipfw
288Set to
289.Li 1
290to enable layer2 filtering with
291.Xr ipfirewall 4 ,
292set to
293.Li 0
294to disable it.
295This needs to be enabled for
296.Xr dummynet 4
297support.
298When
299.Va ipfw
300is enabled,
301.Va pfil_bridge
302and
303.Va pfil_member
304will be disabled so that IPFW
305is not run twice; these can be re-enabled if desired.
306.It Va net.link.bridge.ipfw_arp
307Set to
308.Li 1
309to enable layer2 ARP filtering with
310.Xr ipfirewall 4 ,
311set to
312.Li 0
313to disable it.
314Requires
315.Va ipfw
316to be enabled.
317.El
318.Pp
319ARP and REVARP packets are forwarded without being filtered and others
320that are not IP nor IPv6 packets are not forwarded when
321.Va pfil_onlyip
322is enabled.
323IPFW can filter Ethernet types using
324.Cm mac-type
325so all packets are passed to
326the filter for processing.
327.Pp
328The packets originating from the bridging host will be seen by
329the filter on the interface that is looked up in the routing
330table.
331.Pp
332The packets destined to the bridging host will be seen by the filter
333on the interface with the MAC address equal to the packet's destination
334MAC.
335There are situations when some of the bridge members are sharing
336the same MAC address (for example the
337.Xr vlan 4
338interfaces: they are currently sharing the
339MAC address of the parent physical interface).
340It is not possible to distinguish between these interfaces using
341their MAC address, excluding the case when the packet's destination
342MAC address is equal to the MAC address of the interface on which
343the packet was entered to the system.
344In this case the filter will see the incoming packet on this
345interface.
346In all other cases the interface seen by the packet filter is chosen
347from the list of bridge members with the same MAC address and the
348result strongly depends on the member addition sequence and the
349actual implementation of
350.Nm .
351It is not recommended to rely on the order chosen by the current
352.Nm
353implementation since it may change in the future.
354.Pp
355The previous paragraph is best illustrated with the following
356pictures.
357Let
358.Bl -bullet
359.It
360the MAC address of the incoming packet's destination is
361.Nm nn:nn:nn:nn:nn:nn ,
362.It
363the interface on which packet entered the system is
364.Nm ifX ,
365.It
366.Nm ifX
367MAC address is
368.Nm xx:xx:xx:xx:xx:xx ,
369.It
370there are possibly other bridge members with the same MAC address
371.Nm xx:xx:xx:xx:xx:xx ,
372.It
373the bridge has more than one interface that are sharing the
374same MAC address
375.Nm yy:yy:yy:yy:yy:yy ;
376we will call them
377.Nm vlanY1 ,
378.Nm vlanY2 ,
379etc.
380.El
381.Pp
382If the MAC address
383.Nm nn:nn:nn:nn:nn:nn
384is equal to
385.Nm xx:xx:xx:xx:xx:xx
386the filter will see the packet on interface
387.Nm ifX
388no matter if there are any other bridge members carrying the same
389MAC address.
390But if the MAC address
391.Nm nn:nn:nn:nn:nn:nn
392is equal to
393.Nm yy:yy:yy:yy:yy:yy
394then the interface that will be seen by the filter is one of the
395.Nm vlanYn .
396It is not possible to predict the name of the actual interface
397without the knowledge of the system state and the
398.Nm
399implementation details.
400.Pp
401This problem arises for any bridge members that are sharing the same
402MAC address, not only to the
403.Xr vlan 4
404ones: they were taken just as an example of such a situation.
405So if one wants to filter the locally destined packets based on
406their interface name, one should be aware of this implication.
407The described situation will appear at least on the filtering bridges
408that are doing IP-forwarding; in some of such cases it is better
409to assign the IP address only to the
410.Nm
411interface and not to the bridge members.
412Enabling
413.Va net.link.bridge.pfil_local_phys
414will let you do the additional filtering on the physical interface.
415.Sh EXAMPLES
416The following when placed in the file
417.Pa /etc/rc.conf
418will cause a bridge called
419.Dq Li bridge0
420to be created, and will add the interfaces
421.Dq Li wlan0
422and
423.Dq Li fxp0
424to the bridge, and then enable packet forwarding.
425Such a configuration could be used to implement a simple
426802.11-to-Ethernet bridge (assuming the 802.11 interface is
427in ad-hoc mode).
428.Bd -literal -offset indent
429cloned_interfaces="bridge0"
430ifconfig_bridge0="addm wlan0 addm fxp0 up"
431.Ed
432.Pp
433For the bridge to forward packets,
434all member interfaces and the bridge need to be up.
435The above example would also require:
436.Bd -literal -offset indent
437create_args_wlan0="wlanmode hostap"
438ifconfig_wlan0="up ssid my_ap mode 11g"
439ifconfig_fxp0="up"
440.Ed
441.Pp
442Consider a system with two 4-port Ethernet boards.
443The following will cause a bridge consisting of all 8 ports with Rapid Spanning
444Tree enabled to be created:
445.Bd -literal -offset indent
446ifconfig bridge0 create
447ifconfig bridge0 \e
448    addm fxp0 stp fxp0 \e
449    addm fxp1 stp fxp1 \e
450    addm fxp2 stp fxp2 \e
451    addm fxp3 stp fxp3 \e
452    addm fxp4 stp fxp4 \e
453    addm fxp5 stp fxp5 \e
454    addm fxp6 stp fxp6 \e
455    addm fxp7 stp fxp7 \e
456    up
457.Ed
458.Pp
459The bridge can be used as a regular host interface at the same time as bridging
460between its member ports.
461In this example, the bridge connects em0 and em1, and will receive its IP
462address through DHCP:
463.Bd -literal -offset indent
464cloned_interfaces="bridge0"
465ifconfig_bridge0="addm em0 addm em1 DHCP"
466ifconfig_em0="up"
467ifconfig_em1="up"
468.Ed
469.Pp
470The bridge can tunnel Ethernet across an IP internet using the EtherIP
471protocol.
472This can be combined with
473.Xr ipsec 4
474to provide an encrypted connection.
475Create a
476.Xr gif 4
477interface and set the local and remote IP addresses for the
478tunnel, these are reversed on the remote bridge.
479.Bd -literal -offset indent
480ifconfig gif0 create
481ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
482ifconfig bridge0 create
483ifconfig bridge0 addm fxp0 addm gif0 up
484.Ed
485.Sh SEE ALSO
486.Xr gif 4 ,
487.Xr ipf 4 ,
488.Xr ipfw 4 ,
489.Xr pf 4 ,
490.Xr ifconfig 8
491.Sh HISTORY
492The
493.Nm
494driver first appeared in
495.Fx 6.0 .
496.Sh AUTHORS
497.An -nosplit
498The
499.Nm bridge
500driver was originally written by
501.An Jason L. Wright Aq Mt jason@thought.net
502as part of an undergraduate independent study at the University of
503North Carolina at Greensboro.
504.Pp
505This version of the
506.Nm
507driver has been heavily modified from the original version by
508.An Jason R. Thorpe Aq Mt thorpej@wasabisystems.com .
509.Pp
510Rapid Spanning Tree Protocol (RSTP) support was added by
511.An Andrew Thompson Aq Mt thompsa@FreeBSD.org .
512.Sh BUGS
513The
514.Nm
515driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
516network devices, which can be configured with the same MTU size as the bridge
517device.
518