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