From 646766ec9d03930ff54a225559af7efe86c84232 Mon Sep 17 00:00:00 2001 From: luigi Date: Mon, 18 Feb 2002 01:57:56 +0000 Subject: Manpage update: comment existing functionalities and give more detailed examples on how to use them. Undocument deprecated functionalities which are going to be removed soon. --- share/man/man4/bridge.4 | 206 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 146 insertions(+), 60 deletions(-) (limited to 'share') diff --git a/share/man/man4/bridge.4 b/share/man/man4/bridge.4 index e33f4f8..61426e9 100644 --- a/share/man/man4/bridge.4 +++ b/share/man/man4/bridge.4 @@ -1,7 +1,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 28, 1998 +.Dd February 15, 2002 .Dt BRIDGE 4 .Os .Sh NAME @@ -9,26 +9,58 @@ .Nd bridging support .Sh SYNOPSIS .Cd "options BRIDGE" +.Cd kldload /modules/bridge.ko .Sh DESCRIPTION .Fx -supports bridging on Ethernet-type interfaces. +supports bridging on Ethernet-type interfaces, including VLANs. +Bridging support can be either compiled into the kernel, or loaded +at runtime as a kernel module. +.Pp +A single +.Fx +host can do bridging on independent sets of interfaces, +which are called +.Ar clusters . +Each cluster connects a set of interfaces, and is +identified by a "cluster-id" which is a number in the range 1..65535. +A cluster in fact is very similar to what commercial switches call +a "VLAN". Note however that there is no relation whatsoever +between the cluster-id and the IEEE 802.1q VLAN-id which appears +in the header of packets transmitted on the wire. +In fact, in most cases there is no relation between the +so-called "VLAN identifier" used in most commercial switches, and +the IEEE 802.1q VLAN-id. +.Pp +By putting both physical and logical (vlanX) interfaces +in the same cluster, a FreeBSD box can also implement what in +commercial terms is called a "trunk" interface. This means packets +coming from one of the interfaces in the cluster, +will appear +on the wire on the "parent" interfaces of any vlan +interface belonging to the cluster, with the +proper VLAN tag. Similarly, packets coming from a +parent interface, will have the VLAN tag stripped and +will be forwarded to other interfaces on the same cluster. +See the +.Sx EXAMPLES +section for more details. .Pp Runtime operation of the .Nm is controlled by several .Xr sysctl 8 -variables. -The -.Va net.link.ether.bridge -variable can be set to +variables, as follows. +.Pp +.Bl -tag -width indent +.It Va net.link.ether.bridge +set to .Li 1 -to enable bridging, or set to +to enable bridging, set to .Li 0 to disable it. .Pp -The -.Va net.link.ether.bridge_ipfw -variable can be set to +.It Va net.link.ether.bridge_ipfw +set to .Li 1 to enable .Xr ipfw 8 @@ -37,51 +69,91 @@ Note that .Xr ipfw 8 rules only apply to IP packets. -Non-IP packets are subject to the default +Non-IP packets are accepted by default. +See the +.Sx BUGS +section and the .Xr ipfw 8 -rule -(number 65535) -which must be an -.Cm allow -rule if ARP and other non-IP packets need to flow through the -.Nm . -.Pp -The -.Nm -configuration is controlled by the -.Va net.link.ether.bridge_cfg -variable. -It consists of a comma-separated list of -.Ar interface : Ns Ar cluster -pairs, where all interfaces with the same -.Ar cluster -number will -be bridged together. -.Pp -Another -variable reinitializes the -.Nm ; -this is required if bridged -configurations include loadable interfaces. -After loading new interface drivers, setting the -.Va net.link.ether.bridge_refresh -variable to -.Li 1 -will cause the -.Nm -to reinitialize itself. +manpage for more details on the interaction of bridging +and the firewall. +.Pp +.It Va net.link.ether.bridge_cfg +contains a list of interfaces on which bridging is to be performed. +Interfaces are separated by spaces, commas or tabs. Each interface +can be optionally followed by a colon and an integer indicating the +cluster it belongs to (defaults to 1 if the cluster-id is missing), e.g. +.Pp +.Ar dc0:1,dc1,vlan0:3 dc2:3 +.Pp +will put dc0 and dc1 in cluster number 1, and vlan0 and dc2 in cluster +number 3. +See the +.Sx EXAMPLES +section for more examples. +.Pp +The list of interfaces is rescanned every time the list is +modified, bridging is enabled, or new interfaces are created or +destroyed. Interfaces that are in the list but cannot be used +for bridging (because they are non-existing, or not Ethernet or VLAN) +are not used and a warning message is generated. +.Pp +.El +.Pp +Bridging requires interfaces to be put in promiscuous mode, +and transmit packets with Ethernet source addresses. +Some interfaces (e.g. +.Xr wi 4 ) +do not support this functionality. +Also, bridging is not compatible with interfaces which +use hardware loopback, because there is no way to tell locally +generated packets from externally generated ones. +.Pp .Sh EXAMPLES -The following command will cause the -.Li ep0 -and -.Li fxp0 -interfaces to be bridged together, and the -.Li fxp1 -and -.Li de0 -interfaces to be bridged together: -.Pp -.Dl "sysctl net.link.ether.bridge_cfg=ep0:0,fxp0:0,fxp1:1,de0:1" +A simple bridge configuration with three interfaces in the same +cluster can be set as follows. No cluster-id is specified here, which +will cause the interfaces to appear as part of cluster #1. +.Pp +.Dl sysctl net.link.ether.bridge_cfg=dc0,dc1,fxp1 +.Pp +If you do not know what actual interfaces will be present on +your system, you can just put all existing interfaces in the +configuration, as follows: +.Pp +.Dl sysctl net.link.ether.bridge_cfg="`ifconfig -l`" +.Pp +This will result in a space-separated list of interfaces. +Out of the list, only Ethernet or VLAN interfaces will be +used for bridging, whereas for others the kernel will produce +a warning message. +.Pp +More complex configurations can be used to create multiple +clusters, e.g. +.Pp +.Dl sysctl net.link.ether.bridge_cfg=dc0:3,dc1:3,fxp0:4,fxp1:4 +.Pp +will create two completely independent clusters. +.Pp +Finally, interesting configurations involve vlans and parent interfaces. +As an example, the following configuration will use interface dc0 +as a "trunk" interface, and pass packets +for 802.1q vlans 10 and 20 to physical interfaces dc1 and dc2: +.Pp +.Dl sysctl net.link.ether.bridge_cfg=vlan0:34,dc1:34,vlan1:56,dc2:56 +.Dl ifconfig vlan0 vlan 10 vlandev dc0 +.Dl ifconfig vlan1 vlan 20 vlandev dc0 +.Pp +Note how there is no relation between the 802.1q vlan identifiers +(10 and 20) and the cluster-id's (34 and 56) used in +the bridge_cfg variable. +.Pp +Note also that the trunk interface +does not even appear in the bridge_cfg, as vlan tag insertion/removal +is performed by the +.Xr vlan 4 +devices. +When using vlan devices, care must be taken by not creating loops +between these devices and their parent interfaces. +.Pp .Sh BUGS Care must be taken not to construct loops in the .Nm @@ -95,20 +167,34 @@ With bridging active, interfaces are in promiscuous mode, thus causing some load on the system to receive and filter out undesired traffic. .Pp -Extended functionality to enable bridging selectively on clusters -of interfaces is still in the works. +When passing bridged packets to +.Xr ipfw 8 , +remember that only IP packets are passed to the firewall, while +other packets are silently accepted. +Also remember that bridged packets are accepted after the +first pass through the firewall irrespective of the setting +of the sysctl variable +.Nm net.inet.ip.fw.one_pass , +and that some +.Nm ipfw +actions such as +.Nm divert +do not apply to bridged packets. +It might be useful to have a rule of the form +.Pp +.Dl skipto 20000 ip from any to any bridged .Pp -Interfaces that cannot be put into promiscuous mode or that don't -support sending packets with arbitrary Ethernet source addresses -are not compatible with bridging. +near the beginning of your ruleset to implement specific rulesets +for bridged packets. + .Sh SEE ALSO .Xr ip 4 , .Xr ng_bridge 4 , +.Xr vlan 4 , .Xr ipfw 8 , .Xr sysctl 8 .Sh HISTORY -.Nm -bridging was introduced in +Bridging was introduced in .Fx 2.2.8 by .An Luigi Rizzo Aq luigi@iet.unipi.it . -- cgit v1.1