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.

1 files changed, 146 insertions, 60 deletions

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 .