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