Add section describing how ARP load balancing works and its

limitations:
  - Can't load balance behind router
  - ARP balancing + pfsync probably won't work

PR:		kern/93829
Wording by:	scottl

1 files changed, 34 insertions, 8 deletions

diff --git a/share/man/man4/carp.4 b/share/man/man4/carp.4
index 3cfcede..8333b4a 100644
--- a/share/man/man4/carp.4
+++ b/share/man/man4/carp.4
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 15, 2005
+.Dd June 6, 2006
 .Dt CARP 4
 .Os
 .Sh NAME
@@ -57,8 +57,8 @@ file.
 .Pp
 To use
 .Nm ,
-the administrator needs to configure at minimum a common virtual host ID and
-virtual host IP address on each machine which is to take part in the virtual
+the administrator needs to configure at minimum a common virtual host ID (VHID)
+and virtual host IP address on each machine which is to take part in the virtual
 group.
 Additional parameters can also be set on a per-interface basis:
 .Cm advbase
@@ -126,7 +126,7 @@ Values above 1 enable logging state changes of
 interfaces.
 Default value is 1.
 .It Va net.inet.carp.arpbalance
-Balance local traffic using ARP.
+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.
@@ -138,6 +138,36 @@ Value of 0 means that preemption is not suppressed, since no
 problems are detected.
 Every problem increments suppression counter.
 .El
+.Sh ARP level load balancing
+The
+.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
+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.
+See the
+.Sx EXAMPLES
+section for a practical example of load balancing.
+.Pp
+The ARP load balancing 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.
+Second, ARP load balancing can lead to asymmetric routing
+of incoming and outgoing traffic, and thus combining it with
+.Xr pfsync 4
+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
+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.
 .Sh EXAMPLES
 For firewalls and routers with multiple interfaces, it is desirable to
 failover all of the
@@ -219,10 +249,6 @@ This way, locally connected systems will receive different ARP replies and
 subsequent IP traffic will be balanced among the hosts.
 If one of the hosts fails, the other will take over the virtual MAC address,
 and begin answering ARP requests on its behalf.
-.Pp
-Note: 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.
 .Sh SEE ALSO
 .Xr inet 4 ,
 .Xr pfsync 4 ,