mdoc(7) police: tidy up.

share/man/man4/bridge.4

@@ -9,7 +9,6 @@
 .Nd bridging support
 .Sh SYNOPSIS
 .Cd "options BRIDGE"
-.Cd kldload /modules/bridge.ko
 .Sh DESCRIPTION
 .Fx
 supports bridging on Ethernet-type interfaces, including VLANs.
@@ -20,25 +19,39 @@ A single
 .Fx
 host can do bridging on independent sets of interfaces,
 which are called
-.Ar clusters .
+.Dq clusters .
 Each cluster connects a set of interfaces, and is
-identified by a "cluster-id" which is a number in the range 1..65535.
+identified by a
+.Dq 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
+a
+.Dq 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.
+so-called
+.Dq "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
+By putting both physical and logical
+.Pq Xr vlan 4
+interfaces in the same cluster, a
+.Fx
+box can also implement what in commercial terms is called a
+.Dq 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
+on the wire on the
+.Dq parent
+interfaces of any VLAN
 interface belonging to the cluster, with the
-proper VLAN tag. Similarly, packets coming from a
+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
@@ -50,7 +63,6 @@ Runtime operation of the
 is controlled by several
 .Xr sysctl 8
 variables, as follows.
-.Pp
 .Bl -tag -width indent
 .It Va net.link.ether.bridge
 set to
@@ -58,7 +70,6 @@ set to
 to enable bridging, set to
 .Li 0
 to disable it.
-.Pp
 .It Va net.link.ether.bridge_ipfw
 set to
 .Li 1
@@ -76,16 +87,22 @@ section and the
 .Xr ipfw 8
 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
+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
+cluster it belongs to (defaults to 1 if the cluster-ID is missing), e.g.\&
+.Dq Li "dc0:1,dc1,vlan0:3 dc2:3"
+will put
+.Li dc0
+and
+.Li dc1
+in cluster number 1, and
+.Li vlan0
+and
+.Li dc2
+in cluster
 number 3.
 See the
 .Sx EXAMPLES
@@ -93,27 +110,27 @@ 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
+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.
+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
 A simple bridge configuration with three interfaces in the same
-cluster can be set as follows. No cluster-id is specified here, which
+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
+.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
@@ -122,38 +139,48 @@ configuration, as follows:
 .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
+Out of the list, only Ethernet and 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.
+clusters, e.g.\&
 .Pp
-.Dl sysctl net.link.ether.bridge_cfg=dc0:3,dc1:3,fxp0:4,fxp1:4
+.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:
+Finally, interesting configurations involve VLANs and parent interfaces.
+As an example, the following configuration will use interface
+.Li dc0
+as a
+.Dq trunk
+interface, and pass packets
+for 802.1q VLANs 10 and 20 to physical interfaces
+.Li dc1
+and
+.Li dc2 :
+.Bd -literal -offset indent
+sysctl net.link.ether.bridge_cfg=vlan0:34,dc1:34,vlan1:56,dc2:56
+ifconfig vlan0 vlan 10 vlandev dc0
+ifconfig vlan1 vlan 20 vlandev dc0
+.Ed
 .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.
+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
+.Va bridge_cfg
+variable.
 .Pp
 Note also that the trunk interface
-does not even appear in the bridge_cfg, as vlan tag insertion/removal
+does not even appear in the
+.Va 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
+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
@@ -174,18 +201,24 @@ 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 ,
+.Va net.inet.ip.fw.one_pass ,
 and that some
-.Nm ipfw
+.Xr ipfw 8
 actions such as
-.Nm divert 
+.Cm 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
+.Dl "skipto 20000 ip from any to any bridged"
 .Pp
 near the beginning of your ruleset to implement specific rulesets
 for bridged packets.
+.Sh FILES
+.Bl -tag -width ".Pa /boot/kernel/bridge.ko" -compact
+.It Pa /boot/kernel/bridge.ko
+.Nm
+loadable module.
+.El
 .Sh SEE ALSO
 .Xr ip 4 ,
 .Xr ng_bridge 4 ,