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 October 16, 2017
  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 TOE, TSO, TXCSUM and TXCSUM6 capabilities on all interfaces added to the
 133 bridge are disabled if any of the interfaces doesn't support/enable them.
 134 The LRO capability is always disabled.
 135 All the capabilities are restored when the interface is removed from bridge.
 136 Changing capabilities in run time may cause NIC reinit and the link flap.
 137 .Pp
 138 The bridge supports
 139 .Dq monitor mode ,
 140 where the packets are discarded after
 141 .Xr bpf 4
 142 processing, and are not processed or forwarded further.
 143 This can be used to multiplex the input of two or more interfaces into a single
 144 .Xr bpf 4
 145 stream.
 146 This is useful for reconstructing the traffic for network taps
 147 that transmit the RX/TX signals out through two separate interfaces.
 148 .Sh IPV6 SUPPORT
 149 .Nm
 150 supports the
 151 .Li AF_INET6
 152 address family on bridge interfaces.
 153 The following
 154 .Xr rc.conf 5
 155 variable configures an IPv6 link-local address on
 156 .Li bridge0
 157 interface:
 158 .Bd -literal -offset indent
 159 ifconfig_bridge0_ipv6="up"
 160 .Ed
 161 .Pp
 162 or in a more explicit manner:
 163 .Bd -literal -offset indent
 164 ifconfig_bridge0_ipv6="inet6 auto_linklocal"
 165 .Ed
 166 .Pp
 167 However, the
 168 .Li AF_INET6
 169 address family has a concept of scope zone.
 170 Bridging multiple interfaces change the zone configuration because
 171 multiple links are merged to each other and form a new single link
 172 while the member interfaces still work individually.
 173 This means each member interface still has a separate link-local scope
 174 zone and the
 175 .Nm
 176 interface has another single,
 177 aggregated link-local scope zone at the same time.
 178 This situation is clearly against the description
 179 .Qq zones of the same scope cannot overlap
 180 in Section 5,
 181 RFC 4007.
 182 Although it works in most cases,
 183 it can cause some conterintuitive or undesirable behavior in some
 184 edge cases when both of the
 185 .Nm
 186 interface and one of the member interface have an IPv6 address
 187 and applications use both of them.
 188 .Pp
 189 To prevent this situation,
 190 .Nm
 191 checks whether a link-local scoped IPv6 address is configured on
 192 a member interface to be added and the
 193 .Nm
 194 interface.
 195 When the
 196 .Nm
 197 interface has IPv6 addresses,
 198 IPv6 addresses on the member interface will be automatically removed
 199 before the interface is added.
 200 .Pp
 201 This behavior can be disabled by setting
 202 .Xr sysctl 8
 203 variable
 204 .Va net.link.bridge.allow_llz_overlap
 205 to
 206 .Li 1 .
 207 .Pp
 208 Note that
 209 .Li ACCEPT_RTADV
 210 and
 211 .Li AUTO_LINKLOCAL
 212 interface flag are not enabled by default on
 213 .Nm
 214 interface even when
 215 .Va net.inet6.ip6.accept_rtadv
 216 and/or
 217 .Va net.inet6.ip6.auto_linklocal
 218 is set to
 219 .Li 1 .
 220 .Sh SPANNING TREE
 221 The
 222 .Nm
 223 driver implements the Rapid Spanning Tree Protocol (RSTP or 802.1w) with
 224 backwards compatibility with the legacy Spanning Tree Protocol (STP).
 225 Spanning Tree is used to detect and remove loops in a network topology.
 226 .Pp
 227 RSTP provides faster spanning tree convergence than legacy STP, the protocol
 228 will exchange information with neighbouring switches to quickly transition to
 229 forwarding without creating loops.
 230 .Pp
 231 The code will default to RSTP mode but will downgrade any port connected to a
 232 legacy STP network so is fully backward compatible.
 233 A bridge can be forced to operate in STP mode without rapid state transitions
 234 via the
 235 .Va proto
 236 command in
 237 .Xr ifconfig 8 .
 238 .Pp
 239 The bridge can log STP port changes to
 240 .Xr syslog 3
 241 by enabling the
 242 .Va net.link.bridge.log_stp
 243 variable using
 244 .Xr sysctl 8 .
 245 .Sh PACKET FILTERING
 246 Packet filtering can be used with any firewall package that hooks in via the
 247 .Xr pfil 9
 248 framework.
 249 When filtering is enabled, bridged packets will pass through the filter
 250 inbound on the originating interface, on the bridge interface and outbound on
 251 the appropriate interfaces.
 252 Either stage can be disabled.
 253 The filtering behaviour can be controlled using
 254 .Xr sysctl 8 :
 255 .Bl -tag -width ".Va net.link.bridge.pfil_onlyip"
 256 .It Va net.link.bridge.pfil_onlyip
 257 Controls the handling of non-IP packets which are not passed to
 258 .Xr pfil 9 .
 259 Set to
 260 .Li 1
 261 to only allow IP packets to pass (subject to firewall rules), set to
 262 .Li 0
 263 to unconditionally pass all non-IP Ethernet frames.
 264 .It Va net.link.bridge.pfil_member
 265 Set to
 266 .Li 1
 267 to enable filtering on the incoming and outgoing member interfaces, set
 268 to
 269 .Li 0
 270 to disable it.
 271 .It Va net.link.bridge.pfil_bridge
 272 Set to
 273 .Li 1
 274 to enable filtering on the bridge interface, set
 275 to
 276 .Li 0
 277 to disable it.
 278 .It Va net.link.bridge.pfil_local_phys
 279 Set to
 280 .Li 1
 281 to additionally filter on the physical interface for locally destined packets.
 282 Set to
 283 .Li 0
 284 to disable this feature.
 285 .It Va net.link.bridge.ipfw
 286 Set to
 287 .Li 1
 288 to enable layer2 filtering with
 289 .Xr ipfirewall 4 ,
 290 set to
 291 .Li 0
 292 to disable it.
 293 This needs to be enabled for
 294 .Xr dummynet 4
 295 support.
 296 When
 297 .Va ipfw
 298 is enabled,
 299 .Va pfil_bridge
 300 and
 301 .Va pfil_member
 302 will be disabled so that IPFW
 303 is not run twice; these can be re-enabled if desired.
 304 .It Va net.link.bridge.ipfw_arp
 305 Set to
 306 .Li 1
 307 to enable layer2 ARP filtering with
 308 .Xr ipfirewall 4 ,
 309 set to
 310 .Li 0
 311 to disable it.
 312 Requires
 313 .Va ipfw
 314 to be enabled.
 315 .El
 316 .Pp
 317 ARP and REVARP packets are forwarded without being filtered and others
 318 that are not IP nor IPv6 packets are not forwarded when
 319 .Va pfil_onlyip
 320 is enabled.
 321 IPFW can filter Ethernet types using
 322 .Cm mac-type
 323 so all packets are passed to
 324 the filter for processing.
 325 .Pp
 326 The packets originating from the bridging host will be seen by
 327 the filter on the interface that is looked up in the routing
 328 table.
 329 .Pp
 330 The packets destined to the bridging host will be seen by the filter
 331 on the interface with the MAC address equal to the packet's destination
 332 MAC.
 333 There are situations when some of the bridge members are sharing
 334 the same MAC address (for example the
 335 .Xr vlan 4
 336 interfaces: they are currently sharing the
 337 MAC address of the parent physical interface).
 338 It is not possible to distinguish between these interfaces using
 339 their MAC address, excluding the case when the packet's destination
 340 MAC address is equal to the MAC address of the interface on which
 341 the packet was entered to the system.
 342 In this case the filter will see the incoming packet on this
 343 interface.
 344 In all other cases the interface seen by the packet filter is chosen
 345 from the list of bridge members with the same MAC address and the
 346 result strongly depends on the member addition sequence and the
 347 actual implementation of
 348 .Nm .
 349 It is not recommended to rely on the order chosen by the current
 350 .Nm
 351 implementation: it can be changed in the future.
 352 .Pp
 353 The previous paragraph is best illustrated with the following
 354 pictures.
 355 Let
 356 .Bl -bullet
 357 .It
 358 the MAC address of the incoming packet's destination is
 359 .Nm nn:nn:nn:nn:nn:nn ,
 360 .It
 361 the interface on which packet entered the system is
 362 .Nm ifX ,
 363 .It
 364 .Nm ifX
 365 MAC address is
 366 .Nm xx:xx:xx:xx:xx:xx ,
 367 .It
 368 there are possibly other bridge members with the same MAC address
 369 .Nm xx:xx:xx:xx:xx:xx ,
 370 .It
 371 the bridge has more than one interface that are sharing the
 372 same MAC address
 373 .Nm yy:yy:yy:yy:yy:yy ;
 374 we will call them
 375 .Nm vlanY1 ,
 376 .Nm vlanY2 ,
 377 etc.
 378 .El
 379 .Pp
 380 Then if the MAC address
 381 .Nm nn:nn:nn:nn:nn:nn
 382 is equal to the
 383 .Nm xx:xx:xx:xx:xx:xx
 384 then the filter will see the packet on the interface
 385 .Nm ifX
 386 no matter if there are any other bridge members carrying the same
 387 MAC address.
 388 But if the MAC address
 389 .Nm nn:nn:nn:nn:nn:nn
 390 is equal to the
 391 .Nm yy:yy:yy:yy:yy:yy
 392 then the interface that will be seen by the filter is one of the
 393 .Nm vlanYn .
 394 It is not possible to predict the name of the actual interface
 395 without the knowledge of the system state and the
 396 .Nm
 397 implementation details.
 398 .Pp
 399 This problem arises for any bridge members that are sharing the same
 400 MAC address, not only to the
 401 .Xr vlan 4
 402 ones: they we taken just as the example of such situation.
 403 So if one wants the filter the locally destined packets based on
 404 their interface name, one should be aware of this implication.
 405 The described situation will appear at least on the filtering bridges
 406 that are doing IP-forwarding; in some of such cases it is better
 407 to assign the IP address only to the
 408 .Nm
 409 interface and not to the bridge members.
 410 Enabling
 411 .Va net.link.bridge.pfil_local_phys
 412 will let you do the additional filtering on the physical interface.
 413 .Sh EXAMPLES
 414 The following when placed in the file
 415 .Pa /etc/rc.conf
 416 will cause a bridge called
 417 .Dq Li bridge0
 418 to be created, and will add the interfaces
 419 .Dq Li wlan0
 420 and
 421 .Dq Li fxp0
 422 to the bridge, and then enable packet forwarding.
 423 Such a configuration could be used to implement a simple
 424 802.11-to-Ethernet bridge (assuming the 802.11 interface is
 425 in ad-hoc mode).
 426 .Bd -literal -offset indent
 427 cloned_interfaces="bridge0"
 428 ifconfig_bridge0="addm wlan0 addm fxp0 up"
 429 .Ed
 430 .Pp
 431 For the bridge to forward packets,
 432 all member interfaces and the bridge need to be up.
 433 The above example would also require:
 434 .Bd -literal -offset indent
 435 create_args_wlan0="wlanmode hostap"
 436 ifconfig_wlan0="up ssid my_ap mode 11g"
 437 ifconfig_fxp0="up"
 438 .Ed
 439 .Pp
 440 Consider a system with two 4-port Ethernet boards.
 441 The following will cause a bridge consisting of all 8 ports with Rapid Spanning
 442 Tree enabled to be created:
 443 .Bd -literal -offset indent
 444 ifconfig bridge0 create
 445 ifconfig bridge0 \e
 446     addm fxp0 stp fxp0 \e
 447     addm fxp1 stp fxp1 \e
 448     addm fxp2 stp fxp2 \e
 449     addm fxp3 stp fxp3 \e
 450     addm fxp4 stp fxp4 \e
 451     addm fxp5 stp fxp5 \e
 452     addm fxp6 stp fxp6 \e
 453     addm fxp7 stp fxp7 \e
 454     up
 455 .Ed
 456 .Pp
 457 The bridge can be used as a regular host interface at the same time as bridging
 458 between its member ports.
 459 In this example, the bridge connects em0 and em1, and will receive its IP
 460 address through DHCP:
 461 .Bd -literal -offset indent
 462 cloned_interfaces="bridge0"
 463 ifconfig_bridge0="addm em0 addm em1 DHCP"
 464 ifconfig_em0="up"
 465 ifconfig_em1="up"
 466 .Ed
 467 .Pp
 468 The bridge can tunnel Ethernet across an IP internet using the EtherIP
 469 protocol.
 470 This can be combined with
 471 .Xr ipsec 4
 472 to provide an encrypted connection.
 473 Create a
 474 .Xr gif 4
 475 interface and set the local and remote IP addresses for the
 476 tunnel, these are reversed on the remote bridge.
 477 .Bd -literal -offset indent
 478 ifconfig gif0 create
 479 ifconfig gif0 tunnel 1.2.3.4 5.6.7.8 up
 480 ifconfig bridge0 create
 481 ifconfig bridge0 addm fxp0 addm gif0 up
 482 .Ed
 483 .Pp
 484 Note that
 485 .Fx
 486 6.1, 6.2, 6.3, 7.0, 7.1, and 7.2 have a bug in the EtherIP protocol.
 487 For more details and workaround, see
 488 .Xr gif 4
 489 manual page.
 490 .Sh SEE ALSO
 491 .Xr gif 4 ,
 492 .Xr ipf 4 ,
 493 .Xr ipfw 4 ,
 494 .Xr pf 4 ,
 495 .Xr ifconfig 8
 496 .Sh HISTORY
 497 The
 498 .Nm
 499 driver first appeared in
 500 .Fx 6.0 .
 501 .Sh AUTHORS
 502 .An -nosplit
 503 The
 504 .Nm bridge
 505 driver was originally written by
 506 .An Jason L. Wright Aq Mt jason@thought.net
 507 as part of an undergraduate independent study at the University of
 508 North Carolina at Greensboro.
 509 .Pp
 510 This version of the
 511 .Nm
 512 driver has been heavily modified from the original version by
 513 .An Jason R. Thorpe Aq Mt thorpej@wasabisystems.com .
 514 .Pp
 515 Rapid Spanning Tree Protocol (RSTP) support was added by
 516 .An Andrew Thompson Aq Mt thompsa@FreeBSD.org .
 517 .Sh BUGS
 518 The
 519 .Nm
 520 driver currently supports only Ethernet and Ethernet-like (e.g., 802.11)
 521 network devices, with exactly the same interface MTU size as the bridge device.