share/man/man4/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 January 9, 2010
  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 switch, 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 .Sh PACKET FILTERING
 171 Packet filtering can be used with any firewall package that hooks in via the
 172 .Xr pfil 9
 173 framework.
 174 When filtering is enabled, bridged packets will pass through the filter
 175 inbound on the originating interface, on the bridge interface and outbound on
 176 the appropriate interfaces.
 177 Either stage can be disabled.
 178 The filtering behaviour can be controlled using
 179 .Xr sysctl 8 :
 180 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
 181 .It Va net.link.bridge.pfil_onlyip
 182 Controls the handling of non-IP packets which are not passed to
 183 .Xr pfil 9 .
 184 Set to
 185 .Li 1
 186 to only allow IP packets to pass (subject to firewall rules), set to
 187 .Li 0
 188 to unconditionally pass all non-IP Ethernet frames.
 189 .It Va net.link.bridge.pfil_member
 190 Set to
 191 .Li 1
 192 to enable filtering on the incoming and outgoing member interfaces, set
 193 to
 194 .Li 0
 195 to disable it.
 196 .It Va net.link.bridge.pfil_bridge
 197 Set to
 198 .Li 1
 199 to enable filtering on the bridge interface, set
 200 to
 201 .Li 0
 202 to disable it.
 203 .It Va net.link.bridge.pfil_local_phys
 204 Set to
 205 .Li 1
 206 to additionally filter on the physical interface for locally destined packets.
 207 Set to
 208 .Li 0
 209 to disable this feature.
 210 .It Va net.link.bridge.ipfw
 211 Set to
 212 .Li 1
 213 to enable layer2 filtering with
 214 .Xr ipfirewall 4 ,
 215 set to
 216 .Li 0
 217 to disable it.
 218 This needs to be enabled for
 219 .Xr dummynet 4
 220 support.
 221 When
 222 .Va ipfw
 223 is enabled,
 224 .Va pfil_bridge
 225 and
 226 .Va pfil_member
 227 will be disabled so that IPFW
 228 is not run twice; these can be re-enabled if desired.
 229 .It Va net.link.bridge.ipfw_arp
 230 Set to
 231 .Li 1
 232 to enable layer2 ARP filtering with
 233 .Xr ipfirewall 4 ,
 234 set to
 235 .Li 0
 236 to disable it.
 237 Requires
 238 .Va ipfw
 239 to be enabled.
 240 .El
 241 .Pp
 242 ARP and REVARP packets are forwarded without being filtered and others
 243 that are not IP nor IPv6 packets are not forwarded when
 244 .Va pfil_onlyip
 245 is enabled.
 246 IPFW can filter Ethernet types using
 247 .Cm mac-type
 248 so all packets are passed to
 249 the filter for processing.
 250 .Pp
 251 The packets originating from the bridging host will be seen by
 252 the filter on the interface that is looked up in the routing
 253 table.
 254 .Pp
 255 The packets destined to the bridging host will be seen by the filter
 256 on the interface with the MAC address equal to the packet's destination
 257 MAC.
 258 There are situations when some of the bridge members are sharing
 259 the same MAC address (for example the
 260 .Xr vlan 4
 261 interfaces: they are currently sharing the
 262 MAC address of the parent physical interface).
 263 It is not possible to distinguish between these interfaces using
 264 their MAC address, excluding the case when the packet's destination
 265 MAC address is equal to the MAC address of the interface on which
 266 the packet was entered to the system.
 267 In this case the filter will see the incoming packet on this
 268 interface.
 269 In all other cases the interface seen by the packet filter is chosen
 270 from the list of bridge members with the same MAC address and the
 271 result strongly depends on the member addition sequence and the
 272 actual implementation of
 273 .Nm .
 274 It is not recommended to rely on the order chosen by the current
 275 .Nm
 276 implementation: it can be changed in the future.
 277 .Pp
 278 The previous paragraph is best illustrated with the following
 279 pictures.
 280 Let
 281 .Bl -bullet
 282 .It
 283 the MAC address of the incoming packet's destination is
 284 .Nm nn:nn:nn:nn:nn:nn ,
 285 .It
 286 the interface on which packet entered the system is
 287 .Nm ifX ,
 288 .It
 289 .Nm ifX
 290 MAC address is
 291 .Nm xx:xx:xx:xx:xx:xx ,
 292 .It
 293 there are possibly other bridge members with the same MAC address
 294 .Nm xx:xx:xx:xx:xx:xx ,
 295 .It
 296 the bridge has more than one interface that are sharing the
 297 same MAC address
 298 .Nm yy:yy:yy:yy:yy:yy ;
 299 we will call them
 300 .Nm vlanY1 ,
 301 .Nm vlanY2 ,
 302 etc.
 303 .El
 304 .Pp
 305 Then if the MAC address
 306 .Nm nn:nn:nn:nn:nn:nn
 307 is equal to the
 308 .Nm xx:xx:xx:xx:xx:xx
 309 then the filter will see the packet on the interface
 310 .Nm ifX
 311 no matter if there are any other bridge members carrying the same
 312 MAC address.
 313 But if the MAC address
 314 .Nm nn:nn:nn:nn:nn:nn
 315 is equal to the
 316 .Nm yy:yy:yy:yy:yy:yy
 317 then the interface that will be seen by the filter is one of the
 318 .Nm vlanYn .
 319 It is not possible to predict the name of the actual interface
 320 without the knowledge of the system state and the
 321 .Nm
 322 implementation details.
 323 .Pp
 324 This problem arises for any bridge members that are sharing the same
 325 MAC address, not only to the
 326 .Xr vlan 4
 327 ones: they we taken just as the example of such situation.
 328 So if one wants the filter the locally destined packets based on
 329 their interface name, one should be aware of this implication.
 330 The described situation will appear at least on the filtering bridges
 331 that are doing IP-forwarding; in some of such cases it is better
 332 to assign the IP address only to the
 333 .Nm
 334 interface and not to the bridge members.
 335 Enabling
 336 .Va net.link.bridge.pfil_local_phys
 337 will let you do the additional filtering on the physical interface.
 338 .Sh EXAMPLES
 339 The following when placed in the file
 340 .Pa /etc/rc.conf
 341 will cause a bridge called
 342 .Dq Li bridge0
 343 to be created, and will add the interfaces
 344 .Dq Li wlan0
 345 and
 346 .Dq Li fxp0
 347 to the bridge, and then enable packet forwarding.
 348 Such a configuration could be used to implement a simple
 349 802.11-to-Ethernet bridge (assuming the 802.11 interface is
 350 in ad-hoc mode).
 351 .Bd -literal -offset indent
 352 cloned_interfaces="bridge0"
 353 ifconfig_bridge0="addm wlan0 addm fxp0 up"
 354 .Ed
 355 .Pp
 356 For the bridge to forward packets all member interfaces and the bridge need
 357 to be up.
 358 The above example would also require:
 359 .Bd -literal -offset indent
 360 create_args_wlan0="wlanmode hostap"
 361 ifconfig_wlan0="up ssid my_ap mode 11g"
 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 .Pp
 409 Note that
 410 .Fx
 411 6.1, 6.2, 6.3, 7.0, 7.1, and 7.2 have a bug in the EtherIP protocol.
 412 For more details and workaround, see
 413 .Xr gif 4
 414 manual page.
 415 .Sh SEE ALSO
 416 .Xr gif 4 ,
 417 .Xr ipf 4 ,
 418 .Xr ipfw 4 ,
 419 .Xr pf 4 ,
 420 .Xr ifconfig 8
 421 .Sh HISTORY
 422 The
 423 .Nm
 424 driver first appeared in
 425 .Fx 6.0 .
 426 .Sh AUTHORS
 427 .An -nosplit
 428 The
 429 .Nm bridge
 430 driver was originally written by
 431 .An Jason L. Wright
 432 .Aq jason@thought.net
 433 as part of an undergraduate independent study at the University of
 434 North Carolina at Greensboro.
 435 .Pp
 436 This version of the
 437 .Nm
 438 driver has been heavily modified from the original version by
 439 .An Jason R. Thorpe
 440 .Aq thorpej@wasabisystems.com .
 441 .Pp
 442 Rapid Spanning Tree Protocol (RSTP) support was added by
 443 .An Andrew Thompson
 444 .Aq thompsa@FreeBSD.org .
 445 .Sh BUGS
 446 The
 447 .Nm
 448 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
 449 network devices, with exactly the same interface MTU size as the bridge device.