1.\" 2.\" $FreeBSD$ 3.\" 4.Dd September 20, 2003 5.Dt BRIDGE 4 6.Os 7.Sh NAME 8.Nm bridge 9.Nd bridging support 10.Sh SYNOPSIS 11.Cd "options BRIDGE" 12.Sh DESCRIPTION 13.Fx 14supports bridging on Ethernet-type interfaces, including VLANs. 15Bridging support can be either compiled into the kernel, or loaded 16at runtime as a kernel module. 17.Pp 18A single 19.Fx 20host can do bridging on independent sets of interfaces, 21which are called 22.Dq clusters . 23Each cluster connects a set of interfaces, and is 24identified by a 25.Dq cluster-ID 26which is a number in the range 1..65535. 27A cluster in fact is very similar to what commercial switches call 28a 29.Dq VLAN . 30Note however that there is no relation whatsoever 31between the cluster-ID and the IEEE 802.1q VLAN-ID which appears 32in the header of packets transmitted on the wire. 33In fact, in most cases there is no relation between the 34so-called 35.Dq "VLAN identifier" 36used in most commercial switches, and 37the IEEE 802.1q VLAN-ID. 38.Pp 39By putting both physical and logical 40.Pq Xr vlan 4 41interfaces in the same cluster, a 42.Fx 43box can also implement what in commercial terms is called a 44.Dq trunk 45interface. 46This means that packets 47coming from one of the interfaces in a cluster 48will appear on the wire of the 49.Dq parent 50interface of any VLAN interface in a cluster, 51with the proper VLAN tag. 52Similarly, packets 53coming from a parent interface of any VLAN interface in a cluster 54will have the VLAN tag stripped, 55and will be forwarded to other interfaces in a cluster. 56See the 57.Sx EXAMPLES 58section for more details. 59.Pp 60Runtime operation of the 61.Nm 62is controlled by several 63.Xr sysctl 8 64variables, as follows. 65.Bl -tag -width indent 66.It Va net.link.ether.bridge.enable 67Set to 68.Li 1 69to enable bridging, set to 70.Li 0 71to disable it. 72.It Va net.link.ether.bridge.ipfw 73Set to 74.Li 1 75to enable 76.Xr ipfw 8 77processing of bridged packets. 78Note that 79.Xr ipfw 8 80rules only apply 81to IP packets. 82Non-IP packets are accepted by default. 83See the 84.Sx BUGS 85section and the 86.Xr ipfw 8 87manpage for more details on the interaction of bridging 88and the firewall. 89.It Va net.link.ether.bridge.ipf 90Set to 91.Li 1 92to enable 93.Xr ipf 8 94processing of bridged packets. 95Note that 96.Xr ipf 8 97rules only apply 98to IP packets. 99Non-IP packets are accepted by default. 100.It Va net.link.ether.bridge.config 101Set to the list of interfaces to bridge. 102Interfaces are separated by spaces, commas or tabs. 103Each interface 104can be optionally followed by a colon and an integer indicating the 105cluster it belongs to (defaults to 1 if the cluster-ID is missing), e.g.\& 106.Dq Li "dc0:1,dc1,vlan0:3 dc2:3" 107will put 108.Li dc0 109and 110.Li dc1 111in cluster number 1, and 112.Li vlan0 113and 114.Li dc2 115in cluster 116number 3. 117See the 118.Sx EXAMPLES 119section for more examples. 120.Pp 121The list of interfaces is rescanned every time the list is 122modified, bridging is enabled, or new interfaces are created or 123destroyed. 124An explicit request to refresh the bridge configuration can also 125be done by writing any value to 126.Va net.link.ether.bridge.refresh . 127Interfaces that are in the list but cannot be used 128for bridging (because they are non-existing, or not Ethernet or VLAN) 129are not used and a warning message is generated. 130.El 131.Pp 132Bridging requires interfaces to be put in promiscuous mode, 133and transmit packets with Ethernet source addresses different 134than their own. 135Some interfaces (e.g.\& 136.Xr wi 4 ) 137do not support this functionality. 138Also, bridging is not compatible with interfaces which 139use hardware loopback, because there is no way to tell locally 140generated packets from externally generated ones. 141.Sh EXAMPLES 142A simple bridge configuration with three interfaces in the same 143cluster can be set as follows. 144No cluster-ID is specified here, which 145will cause the interfaces to appear as part of cluster #1. 146.Pp 147.Dl "sysctl net.link.ether.bridge.config=dc0,dc1,fxp1" 148.Pp 149If you do not know what actual interfaces will be present on 150your system, you can just put all existing interfaces in the 151configuration, as follows: 152.Pp 153.Dl sysctl net.link.ether.bridge.config="`ifconfig -l`" 154.Pp 155This will result in a space-separated list of interfaces. 156Out of the list, only Ethernet and VLAN interfaces will be 157used for bridging, whereas for others the kernel will produce 158a warning message. 159.Pp 160More complex configurations can be used to create multiple 161clusters, e.g.\& 162.Pp 163.Dl "sysctl net.link.ether.bridge.config=dc0:3,dc1:3,fxp0:4,fxp1:4" 164.Pp 165will create two completely independent clusters. 166.Pp 167Finally, interesting configurations involve VLANs and parent interfaces. 168As an example, the following configuration will use interface 169.Li dc0 170as a 171.Dq trunk 172interface, and pass packets 173for 802.1q VLANs 10 and 20 to physical interfaces 174.Li dc1 175and 176.Li dc2 , 177respectively: 178.Bd -literal -offset indent 179sysctl net.link.ether.bridge.config=vlan0:34,dc1:34,vlan1:56,dc2:56 180ifconfig vlan0 vlan 10 vlandev dc0 181ifconfig vlan1 vlan 20 vlandev dc0 182.Ed 183.Pp 184Note how there is no relation between the 802.1q VLAN identifiers 185(10 and 20) and the cluster-ID's (34 and 56) used in 186the 187.Va bridge.config 188variable. 189.Pp 190Note also that the trunk interface 191does not even appear in the 192.Va bridge.config , 193as VLAN tag insertion/removal 194is performed by the 195.Xr vlan 4 196devices. 197When using VLAN devices, care must be taken by not creating loops 198between these devices and their parent interfaces. 199.Sh BUGS 200Care must be taken not to construct loops in the 201.Nm 202topology. 203The kernel supports only a primitive form of loop detection, by disabling 204some interfaces when a loop is detected. 205No support for a daemon running the 206spanning tree algorithm is currently provided. 207.Pp 208With bridging active, interfaces are in promiscuous mode, 209thus causing some load on the system to receive and filter 210out undesired traffic. 211.Pp 212When passing bridged packets to 213.Xr ipfw 8 , 214remember that only IP packets are passed to the firewall, while 215other packets are silently accepted. 216Also remember that bridged packets are accepted after the 217first pass through the firewall irrespective of the setting 218of the sysctl variable 219.Va net.inet.ip.fw.one_pass , 220and that some 221.Xr ipfw 8 222actions such as 223.Cm divert 224do not apply to bridged packets. 225It might be useful to have a rule of the form 226.Pp 227.Dl "skipto 20000 ip from any to any bridged" 228.Pp 229near the beginning of your ruleset to implement specific rulesets 230for bridged packets. 231.Sh FILES 232.Bl -tag -width ".Pa /boot/kernel/bridge.ko" -compact 233.It Pa /boot/kernel/bridge.ko 234.Nm 235loadable module. 236.El 237.Sh SEE ALSO 238.Xr ip 4 , 239.Xr ng_bridge 4 , 240.Xr vlan 4 , 241.Xr ipf 8 , 242.Xr ipfw 8 , 243.Xr sysctl 8 244.Sh HISTORY 245Bridging was introduced in 246.Fx 2.2.8 247by 248.An Luigi Rizzo Aq luigi@iet.unipi.it . 249