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