docs/159854: grammar updates for carp.4

[Benjamin Kaduk]

And the main diff.

-Ben
-------------- next part --------------
--- carp.4.whitespace	2011-08-17 14:13:19.000000000 -0400
+++ carp.4	2011-08-17 20:11:54.000000000 -0400
@@ -50,9 +50,9 @@
 interface can be created at runtime using the
 .Nm ifconfig Li carp Ns Ar N Cm create
 command or by configuring
-it via
+one via the
 .Va cloned_interfaces
-in the
+variable in the
 .Pa /etc/rc.conf
 file.
 .Pp
@@ -88,7 +88,7 @@
 and
 .Cm advskew
 are put inside CARP advertisements.
-These configurations can be done using
+These values can be configured using
 .Xr ifconfig 8 ,
 or through the
 .Dv SIOCSVH
@@ -96,7 +96,7 @@
 .Pp
 Additionally, there are a number of global parameters which can be set using
 .Xr sysctl 8 :
-.Bl -tag -width ".Va net.inet.carp.arpbalance"
+.Bl -tag -width ".Va net.inet.carp.suppress_preempt"
 .It Va net.inet.carp.allow
 Accept incoming
 .Nm
@@ -118,44 +118,52 @@
 See also the first example.
 Disabled by default.
 .It Va net.inet.carp.log
-Value of 0 disables any logging.
-Value of 1 enables logging state changes of
+Determine what events relating to
+.Nm
+interfaces are logged.
+A value of 0 disables any logging.
+A value of 1 enables logging state changes of
 .Nm
 interfaces.
 Values above 1 enable logging of bad
 .Nm
 packets.
-Default value is 1.
+The default value is 1.
 .It Va net.inet.carp.arpbalance
 Balance local traffic using ARP (see below).
 Disabled by default.
 .It Va net.inet.carp.suppress_preempt
-A read only value showing the status of preemption suppression.
+A read-only value showing the status of preemption suppression.
 Preemption can be suppressed if link on an interface is down
-or when
+or when the
 .Xr pfsync 4
 interface is not synchronized.
-Value of 0 means that preemption is not suppressed, since no
+A value of 0 means that preemption is not suppressed, since no
 problems are detected.
-Every problem increments suppression counter.
+The value is incremented when a problem is detected.
 .El
 .Sh ARP level load balancing
-The
+A
 .Nm
-has limited abilities for load balancing the incoming connections
-between hosts in Ethernet network.
-For load balancing operation, one needs several CARP interfaces that
+interface
+has limited abilities for load-balancing incoming connections
+between hosts in an Ethernet network.
+For load-balancing operation, one needs several CARP interfaces that
 are configured to the same IP address, but to a different VHIDs.
 Once an ARP request is received, the CARP protocol will use a hashing
 function against the source IP address in the ARP request to determine
-which VHID should this request belong to.
-If the corresponding CARP interface is in master state, the ARP request
-will be replied, otherwise it will be ignored.
+which VHID the request will be assigned to.
+If the corresponding CARP interface is the current
+master interface, a reply will
+be sent to the ARP request;
+otherwise it will be ignored.
 See the
 .Sx EXAMPLES
 section for a practical example of load balancing.
 .Pp
-The ARP load balancing has some limitations.
+The ARP load balancing implemented in
+.Nm
+has some limitations.
 First, ARP balancing only works on the local network segment.
 It cannot balance traffic that crosses a router, because the
 router itself will always be balanced to the same virtual host.
@@ -165,10 +173,11 @@
 is dangerous, because this creates a race condition between
 balanced routers and a host they are serving.
 Imagine an incoming packet creating state on the first router, being
-forwarded to its destination, and destination replying faster
+forwarded to its destination, and the destination replying faster
 than the state information is packed and synced with the second router.
 If the reply would be load balanced to second router, it will be
-dropped due to no state.
+dropped since the second router has not yet received information about
+the connection state.
 .Sh STATE CHANGE NOTIFICATIONS
 Sometimes it is useful to get notified about
 .Nm
@@ -182,10 +191,10 @@
 .Dv LINK_UP
 or
 .Dv LINK_DOWN
-event.
+events.
 Please see
 .Xr devd.conf 5
-and
+and the
 .Sx EXAMPLES
 section for more information.
 .Sh EXAMPLES
@@ -193,8 +202,8 @@
 failover all of the
 .Nm
 interfaces together, when one of the physical interfaces goes down.
-This is achieved by the preempt option.
-Enable it on both host A and B:
+This is achieved by the use of the preempt option.
+Enable it on both hosts A and B:
 .Pp
 .Dl sysctl net.inet.carp.preempt=1
 .Pp