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