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 125.Nm 126configuration can also 127be done by writing any value to 128.Va net.link.ether.bridge.refresh . 129Interfaces that are in the list but cannot be used 130for bridging (because they are non-existing, or not Ethernet or VLAN) 131are not used and a warning message is generated. 132.El 133.Pp 134Bridging requires interfaces to be put in promiscuous mode, 135and transmit packets with Ethernet source addresses different 136than their own. 137Some interfaces (e.g.\& 138.Xr wi 4 ) 139do not support this functionality. 140Also, bridging is not compatible with interfaces which 141use hardware loopback, because there is no way to tell locally 142generated packets from externally generated ones. 143.Sh EXAMPLES 144A simple 145.Nm 146configuration with three interfaces in the same 147cluster can be set as follows. 148No cluster-ID is specified here, which 149will cause the interfaces to appear as part of cluster #1. 150.Pp 151.Dl "sysctl net.link.ether.bridge.config=dc0,dc1,fxp1" 152.Pp 153If you do not know what actual interfaces will be present on 154your system, you can just put all existing interfaces in the 155configuration, as follows: 156.Pp 157.Dl sysctl net.link.ether.bridge.config="`ifconfig -l`" 158.Pp 159This will result in a space-separated list of interfaces. 160Out of the list, only Ethernet and VLAN interfaces will be 161used for bridging, whereas for others the kernel will produce 162a warning message. 163.Pp 164More complex configurations can be used to create multiple 165clusters, e.g.\& 166.Pp 167.Dl "sysctl net.link.ether.bridge.config=dc0:3,dc1:3,fxp0:4,fxp1:4" 168.Pp 169will create two completely independent clusters. 170.Pp 171Finally, interesting configurations involve VLANs and parent interfaces. 172As an example, the following configuration will use interface 173.Li dc0 174as a 175.Dq trunk 176interface, and pass packets 177for 802.1q VLANs 10 and 20 to physical interfaces 178.Li dc1 179and 180.Li dc2 , 181respectively: 182.Bd -literal -offset indent 183sysctl net.link.ether.bridge.config=vlan0:34,dc1:34,vlan1:56,dc2:56 184ifconfig vlan0 vlan 10 vlandev dc0 185ifconfig vlan1 vlan 20 vlandev dc0 186.Ed 187.Pp 188Note how there is no relation between the 802.1q VLAN identifiers 189(10 and 20) and the cluster-ID's (34 and 56) used in 190the 191.Va bridge.config 192variable. 193.Pp 194Note also that the trunk interface 195does not even appear in the 196.Va bridge.config , 197as VLAN tag insertion/removal 198is performed by the 199.Xr vlan 4 200devices. 201When using VLAN devices, care must be taken by not creating loops 202between these devices and their parent interfaces. 203.Sh BUGS 204Care must be taken not to construct loops in the 205.Nm 206topology. 207The kernel supports only a primitive form of loop detection, by disabling 208some interfaces when a loop is detected. 209No support for a daemon running the 210spanning tree algorithm is currently provided. 211.Pp 212With bridging active, interfaces are in promiscuous mode, 213thus causing some load on the system to receive and filter 214out undesired traffic. 215.Pp 216When passing bridged packets to 217.Xr ipfw 8 , 218remember that only IP packets are passed to the firewall, while 219other packets are silently accepted. 220Also remember that bridged packets are accepted after the 221first pass through the firewall irrespective of the setting 222of the sysctl variable 223.Va net.inet.ip.fw.one_pass , 224and that some 225.Xr ipfw 8 226actions such as 227.Cm divert 228do not apply to bridged packets. 229It might be useful to have a rule of the form 230.Pp 231.Dl "skipto 20000 ip from any to any bridged" 232.Pp 233near the beginning of your ruleset to implement specific rulesets 234for bridged packets. 235.Sh FILES 236.Bl -tag -width ".Pa /boot/kernel/bridge.ko" -compact 237.It Pa /boot/kernel/bridge.ko 238.Nm 239loadable module. 240.El 241.Sh SEE ALSO 242.Xr ip 4 , 243.Xr ng_bridge 4 , 244.Xr vlan 4 , 245.Xr ipf 8 , 246.Xr ipfw 8 , 247.Xr sysctl 8 248.Sh HISTORY 249Bridging was introduced in 250.Fx 2.2.8 251by 252.An Luigi Rizzo Aq luigi@iet.unipi.it . 253