6/share/man/man4/if_bridge.4

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