| blob | 9eebe98354e071575fe1c5cb56b282df0488a929 |
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 17, 2007
39 .Dt IF_BRIDGE 4
40 .Os
41 .Sh NAME
42 .Nm if_bridge
43 .Nd network bridge device
44 .Sh SYNOPSIS
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"
50 .Ed
51 .Pp
52 Alternatively, to load the driver as a
53 module at boot time, place the following lines in
54 .Xr loader.conf 5 :
55 .Bd -literal -offset indent
56 if_bridge_load="YES"
57 bridgestp_load="YES"
58 .Ed
59 .Sh DESCRIPTION
60 The
61 .Nm
62 driver creates a logical link between two or more IEEE 802 networks
63 that use the same (or
64 .Dq "similar enough" )
65 framing format.
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.
68 .Pp
69 Each
70 .Nm
71 interface is created at runtime using interface cloning.
72 This is
73 most easily done with the
74 .Xr ifconfig 8
75 .Cm create
76 command or using the
77 .Va cloned_interfaces
78 variable in
79 .Xr rc.conf 5 .
80 .Pp
81 The
82 .Nm
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
86 .Em only
87 across all
88 .Nm
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
93 .Xr ifconfig 8 .
94 .Pp
95 If
96 .Xr sysctl 8
97 node
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
104 by
105 .Xr ng_pppoe 4
106 and
107 .Xr ppp 8 .
108 Now this feature is considered as experimental and is turned off
109 by-default.
110 .Pp
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.
113 .Pp
114 A bridge works like a hub, forwarding traffic from one interface
115 to another.
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.
120 .Pp
121 All the bridged member interfaces need to be up in order to pass network traffic.
122 These can be enabled using
123 .Xr ifconfig 8
124 or
125 .Va ifconfig_ Ns Ao Ar interface Ac Ns Li ="up"
126 in
127 .Xr rc.conf 5 .
128 .Pp
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.
131 .Pp
132 The TXCSUM capability is disabled for any interface added to the bridge, and it
133 is restored when the interface is removed again.
134 .Pp
135 The bridge supports
136 .Dq monitor mode ,
137 where the packets are discarded after
138 .Xr bpf 4
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
141 .Xr bpf 4
142 stream.
143 This is useful for reconstructing the traffic for network taps
144 that transmit the RX/TX signals out through two separate interfaces.
145 .Sh SPANNING TREE
146 The
147 .Nm
148 driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
149 backwards compatibility with the legacy Spanning Tree Protocol (STP).
150 Spanning Tree is used to detect and remove loops in a network topology.
151 .Pp
152 RSTP provides faster spanning tree convergence than legacy STP, the protocol
153 will exchange information with neighbouring switches to quickly transition to
154 forwarding without creating loops.
155 .Pp
156 The code will default to RSTP mode but will downgrade any port connected to a
157 legacy STP network so is fully backward compatible.
158 A bridge can be forced to operate in STP mode without rapid state transitions
159 via the
160 .Va proto
161 command in
162 .Xr ifconfig 8 .
163 .Pp
164 The bridge can log STP port changes to
165 .Xr syslog 3
166 by enabling the
167 .Va net.link.bridge.log_stp
168 variable using
169 .Xr sysctl 8 .
170 .Pp
171 .Sh PACKET FILTERING
172 Packet filtering can be used with any firewall package that hooks in via the
173 .Xr pfil 9
174 framework.
175 When filtering is enabled, bridged packets will pass through the filter
176 inbound on the originating interface, on the bridge interface and outbound on
177 the appropriate interfaces.
178 Either stage can be disabled.
179 The filtering behaviour can be controlled using
180 .Xr sysctl 8 :
181 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
182 .It Va net.link.bridge.pfil_onlyip
183 Controls the handling of non-IP packets which are not passed to
184 .Xr pfil 9 .
185 Set to
186 .Li 1
187 to only allow IP packets to pass (subject to firewall rules), set to
188 .Li 0
189 to unconditionally pass all non-IP Ethernet frames.
190 .It Va net.link.bridge.pfil_member
191 Set to
192 .Li 1
193 to enable filtering on the incoming and outgoing member interfaces, set
194 to
195 .Li 0
196 to disable it.
197 .It Va net.link.bridge.pfil_bridge
198 Set to
199 .Li 1
200 to enable filtering on the bridge interface, set
201 to
202 .Li 0
203 to disable it.
204 .It Va net.link.bridge.pfil_local_phys
205 Set to
206 .Li 1
207 to additionally filter on the physical interface for locally destined packets.
208 Set to
209 .Li 0
210 to disable this feature.
211 .It Va net.link.bridge.ipfw
212 Set to
213 .Li 1
214 to enable layer2 filtering with
215 .Xr ipfirewall 4 ,
216 set to
217 .Li 0
218 to disable it.
219 This needs to be enabled for
220 .Xr dummynet 4
221 support.
222 When
223 .Va ipfw
224 is enabled,
225 .Va pfil_bridge
226 and
227 .Va pfil_member
228 will be disabled so that IPFW
229 is not run twice; these can be re-enabled if desired.
230 .It Va net.link.bridge.ipfw_arp
231 Set to
232 .Li 1
233 to enable layer2 ARP filtering with
234 .Xr ipfirewall 4 ,
235 set to
236 .Li 0
237 to disable it.
238 Requires
239 .Va ipfw
240 to be enabled.
241 .El
242 .Pp
243 ARP and REVARP packets are forwarded without being filtered and others
244 that are not IP nor IPv6 packets are not forwarded when
245 .Va pfil_onlyip
246 is enabled.
247 IPFW can filter Ethernet types using
248 .Cm mac-type
249 so all packets are passed to
250 the filter for processing.
251 .Pp
252 The packets originating from the bridging host will be seen by
253 the filter on the interface that is looked up in the routing
254 table.
255 .Pp
256 The packets destined to the bridging host will be seen by the filter
257 on the interface with the MAC address equal to the packet's destination
258 MAC.
259 There are situations when some of the bridge members are sharing
260 the same MAC address (for example the
261 .Xr vlan 4
262 interfaces: they are currenly sharing the
263 MAC address of the parent physical interface).
264 It is not possible to distinguish between these interfaces using
265 their MAC address, excluding the case when the packet's destination
266 MAC address is equal to the MAC address of the interface on which
267 the packet was entered to the system.
268 In this case the filter will see the incoming packet on this
269 interface.
270 In all other cases the interface seen by the packet filter is chosen
271 from the list of bridge members with the same MAC address and the
272 result strongly depends on the member addition sequence and the
273 actual implementation of
274 .Nm .
275 It is not recommended to rely on the order chosen by the current
276 .Nm
277 implementation: it can be changed in the future.
278 .Pp
279 The previous paragraph is best illustrated with the following
280 pictures.
281 Let
282 .Bl -bullet
283 .It
284 the MAC address of the incoming packet's destination is
285 .Nm nn:nn:nn:nn:nn:nn ,
286 .It
287 the interface on which packet entered the system is
288 .Nm ifX ,
289 .It
290 .Nm ifX
291 MAC address is
292 .Nm xx:xx:xx:xx:xx:xx ,
293 .It
294 there are possibly other bridge members with the same MAC address
295 .Nm xx:xx:xx:xx:xx:xx ,
296 .It
297 the bridge has more than one interface that are sharing the
298 same MAC address
299 .Nm yy:yy:yy:yy:yy:yy ;
300 we will call them
301 .Nm vlanY1 ,
302 .Nm vlanY2 ,
303 etc.
304 .El
305 .Pp
306 Then if the MAC address
307 .Nm nn:nn:nn:nn:nn:nn
308 is equal to the
309 .Nm xx:xx:xx:xx:xx:xx
310 then the filter will see the packet on the interface
311 .Nm ifX
312 no matter if there are any other bridge members carrying the same
313 MAC address.
314 But if the MAC address
315 .Nm nn:nn:nn:nn:nn:nn
316 is equal to the
317 .Nm yy:yy:yy:yy:yy:yy
318 then the interface that will be seen by the filter is one of the
319 .Nm vlanYn .
320 It is not possible to predict the name of the actual interface
321 without the knowledge of the system state and the
322 .Nm
323 implementation details.
324 .Pp
325 This problem arises for any bridge members that are sharing the same
326 MAC address, not only to the
327 .Xr vlan 4
328 ones: they we taken just as the example of such situation.
329 So if one wants the filter the locally destined packets based on
330 their interface name, one should be aware of this implication.
331 The described situation will appear at least on the filtering bridges
332 that are doing IP-forwarding; in some of such cases it is better
333 to assign the IP address only to the
334 .Nm
335 interface and not to the bridge members.
336 Enabling
337 .Va net.link.bridge.pfil_local_phys
338 will let you do the additional filtering on the physical interface.
339 .Sh EXAMPLES
340 The following when placed in the file
341 .Pa /etc/rc.conf
342 will cause a bridge called
343 .Dq Li bridge0
344 to be created, and will add the interfaces
345 .Dq Li ath0
346 and
347 .Dq Li fxp0
348 to the bridge, and then enable packet forwarding.
349 Such a configuration could be used to implement a simple
350 802.11-to-Ethernet bridge (assuming the 802.11 interface is
351 in ad-hoc mode).
352 .Bd -literal -offset indent
353 cloned_interfaces="bridge0"
354 ifconfig_bridge0="addm ath0 addm fxp0 up"
355 .Ed
356 .Pp
357 For the bridge to forward packets all member interfaces and the bridge need
358 to be up.
359 The above example would also require:
360 .Bd -literal -offset indent
361 ifconfig_ath0="up ssid my_ap mode 11g mediaopt hostap"
362 ifconfig_fxp0="up"
363 .Ed
364 .Pp
365 Consider a system with two 4-port Ethernet boards.
366 The following will cause a bridge consisting of all 8 ports with Rapid Spanning
367 Tree enabled to be created:
368 .Bd -literal -offset indent
369 ifconfig bridge0 create
370 ifconfig bridge0 \e
371 addm fxp0 stp fxp0 \e
372 addm fxp1 stp fxp1 \e
373 addm fxp2 stp fxp2 \e
374 addm fxp3 stp fxp3 \e
375 addm fxp4 stp fxp4 \e
376 addm fxp5 stp fxp5 \e
377 addm fxp6 stp fxp6 \e
378 addm fxp7 stp fxp7 \e
379 up
380 .Ed
381 .Pp
382 The bridge can be used as a regular host interface at the same time as bridging
383 between its member ports.
384 In this example, the bridge connects em0 and em1, and will receive its IP
385 address through DHCP:
386 .Bd -literal -offset indent
387 cloned_interfaces="bridge0"
388 ifconfig_bridge0="addm em0 addm em1 DHCP"
389 ifconfig_em0="up"
390 ifconfig_em1="up"
391 .Ed
392 .Pp
393 The bridge can tunnel Ethernet across an IP internet using the EtherIP
394 protocol.
395 This can be combined with
396 .Xr ipsec 4
397 to provide an encrypted connection.
398 Create a
399 .Xr gif 4
400 interface and set the local and remote IP addresses for the
401 tunnel, these are reversed on the remote bridge.
402 .Bd -literal -offset indent
403 ifconfig gif0 create
404 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
405 ifconfig bridge0 create
406 ifconfig bridge0 addm fxp0 addm gif0 up
407 .Ed
408 .Sh SEE ALSO
409 .Xr gif 4 ,
410 .Xr ipf 4 ,
411 .Xr ipfw 4 ,
412 .Xr pf 4 ,
413 .Xr ifconfig 8
414 .Sh HISTORY
415 The
416 .Nm
417 driver first appeared in
418 .Fx 6.0 .
419 .Sh AUTHORS
420 .An -nosplit
421 The
422 .Nm bridge
423 driver was originally written by
424 .An Jason L. Wright
425 .Aq jason@thought.net
426 as part of an undergraduate independent study at the University of
427 North Carolina at Greensboro.
428 .Pp
429 This version of the
430 .Nm
431 driver has been heavily modified from the original version by
432 .An Jason R. Thorpe
433 .Aq thorpej@wasabisystems.com .
434 .Pp
435 Rapid Spanning Tree Protocol (RSTP) support was added by
436 .An Andrew Thompson
437 .Aq thompsa@FreeBSD.org .
438 .Sh BUGS
439 The
440 .Nm
441 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
442 network devices, with exactly the same interface MTU size as the bridge device.