Manpage bits for IP load balancing.

Configuration is subject to change.
With help from jmc@

1 files changed, 134 insertions, 45 deletions

diff --git a/share/man/man4/carp.4 b/share/man/man4/carp.4
index 489ead7a075..628fdd6dda2 100644
--- a/share/man/man4/carp.4
+++ b/share/man/man4/carp.4
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: carp.4,v 1.23 2006/06/15 08:55:39 jmc Exp $
+.\"	$OpenBSD: carp.4,v 1.24 2007/03/18 23:29:31 mpf Exp $
 .\"
 .\" Copyright (c) 2003, Ryan McBride.  All rights reserved.
 .\"
@@ -118,10 +118,57 @@ Disabled by default.
 Balance local traffic using ARP.
 Disabled by default.
 .El
-.Sh ARP LEVEL LOAD BALANCING
+.Sh LOAD BALANCING
 .Nm
-has limited abilities for load balancing the incoming connections
-between hosts in an Ethernet network.
+provides two mechanisms to load balance incoming traffic
+over a group of
+.Nm
+hosts:
+ARP balancing and IP balancing.
+.Pp
+Which one to use mainly depends on the network environment
+.Nm
+is being used in.
+ARP balancing has limited abilities for load balancing the
+incoming connections between hosts in an Ethernet network.
+It only works for clients in the local network, because
+ARP balancing spreads the load by varying ARP replies
+based on the source IP address of the host sending the query.
+Therefore it cannot balance traffic that crosses a router, because the
+router itself will always be balanced to the same virtual host.
+.Pp
+IP balancing is not dependent on ARP and therefore also works
+for traffic that comes over a router.
+This method should work in all environments and can
+also provide more fine grained load balancing than ARP balancing.
+The downside of IP balancing is that it requires the traffic
+that is destined towards the load balanced IP addresses
+to be received by all
+.Nm
+hosts.
+While this is always the case when connected to a hub,
+it has to play some tricks in switched networks, which
+will result in a higher network load.
+.Pp
+A rule of thumb might be to use ARP balancing if there
+are many hosts on the same network segment and
+to use IP balancing for all other cases.
+.Pp
+The configuration of ARP and IP load balancing is quite similar:
+a load balancing group is created out of multiple
+.Nm
+interfaces by configuring them with the same IP addresses,
+but to different VHIDs.
+All
+.Nm
+nodes in the cluster are configured identically, except
+for a different
+.Cm advskew
+to control which interfaces on a host will be the designated master.
+See the
+.Sx EXAMPLES
+section for a practical example of load balancing.
+.Ss ARP BALANCING
 For load balancing, several
 .Nm
 interfaces are configured to the same IP address, but to different VHIDs.
@@ -132,9 +179,6 @@ If the corresponding
 .Nm
 interface is in master state, the ARP request will be answered, 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.
 Firstly, ARP balancing only works on the local network segment.
@@ -153,6 +197,65 @@ This requires multiple CARP groups with
 .Em different
 IP addresses on the outgoing interface, configured so that each host is the
 master of one group.
+.Ss IP BALANCING
+IP load balancing works by utilizing the network itself to distribute
+incoming traffic to all
+.Nm
+nodes in the cluster.
+Each packet is filtered on the incoming
+.Nm
+interface so that only one node in the cluster accepts the
+packet.
+All the other nodes will just silently drop it.
+The filtering function uses a hash over the source and destination
+address of the IPv4 or IPv6 packet and compares the result against the
+state of the
+.Nm
+load balancing group.
+.Pp
+A load balancing group consists of two or more
+.Nm
+interfaces per host which are configured with common IP addresses
+but different VHIDs.
+IP balancing is activated by setting the
+.Cm link0
+flag on the first interface of the group.
+In most cases it is recommended to also enable the
+.Cm link1
+flag.
+This flag enables the stealth mode on the interface.
+In this mode
+.Nm
+never sends packets with its virtual MAC address as source.
+This is necessary to receive incoming traffic on all hosts in switched networks.
+Stealth mode prevents a switch from learning the virtual MAC
+address, so that it has to flood the traffic to all its ports.
+The
+.Cm link1
+flag can be avoided
+only if using a hub or if the switch ports that are connected
+to the cluster nodes can be configured into some sort of monitoring mode.
+Please note that activating stealth mode on a
+.Nm
+interface that has already been running might not work instantly.
+As a workaround the VHID can be changed to a previously unused
+one, or just wait until the MAC table entry in the switch times out.
+
+Some Layer-3 switches do port learning based on ARP packets.
+Therefore the stealth mode cannot hide the virtual MAC address
+from these kind of devices.
+In such cases,
+.Nm
+can be told to use a multicast MAC address by additionally enabling the
+.Cm link2
+flag.
+.Pp
+If IP balancing is being used on a firewall, it is recommended to
+configure the load balancing group in a symmetrical manner.
+This is achieved by prioritizing the interfaces in the same order
+(ascending by VHID) on both sides of the firewall.
+This ensures that packets of one connection will pass in and out
+on the same host and are not routed asymmetrically.
 .Sh EXAMPLES
 For firewalls and routers with multiple interfaces, it is desirable to
 failover all of the
@@ -167,22 +270,14 @@ Assume that host A is the preferred master and 192.168.1.x/24 is
 configured on one physical interface and 192.168.2.y/24 on another.
 This is the setup for host A:
 .Bd -literal -offset indent
-# ifconfig carp0 create
-# ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1 \e
-	netmask 255.255.255.0
-# ifconfig carp1 create
-# ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1 \e
-	netmask 255.255.255.0
+# ifconfig carp0 192.168.1.1 vhid 1
+# ifconfig carp1 192.168.2.1 vhid 2
 .Ed
 .Pp
 The setup for host B is identical, but it has a higher advskew:
 .Bd -literal -offset indent
-# ifconfig carp0 create
-# ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e
-	192.168.1.1 netmask 255.255.255.0
-# ifconfig carp1 create
-# ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e
-	192.168.2.1 netmask 255.255.255.0
+# ifconfig carp0 192.168.1.1 vhid 1 advskew 100
+# ifconfig carp1 192.168.2.1 vhid 2 advskew 100
 .Ed
 .Pp
 Because of the preempt option, when one of the physical interfaces of
@@ -191,10 +286,9 @@ host A fails, advskew is adjusted to 240 on all its
 interfaces.
 This will cause host B to preempt on both interfaces instead of
 just the failed one.
-.Pp
-In order to set up an ARP balanced virtual host, it is necessary to configure
-one virtual host for each physical host which would respond to ARP requests
-and thus handle the traffic.
+.Ss LOAD BALANCING
+In order to set up an load balanced virtual host, it is necessary to configure
+one virtual host for each physical host.
 In the following example, two virtual hosts are configured on two hosts to
 provide balancing and failover for the IP address 192.168.1.10.
 .Pp
@@ -204,40 +298,35 @@ interfaces on Host A are configured.
 The
 .Cm advskew
 of 100 on the second virtual host means that its advertisements will be sent
-out slightly less frequently.
+out slightly less frequently and will therefore become the designated backup.
 .Bd -literal -offset indent
-# ifconfig carp0 create
-# ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10 \e
-	netmask 255.255.255.0
-# ifconfig carp1 create
-# ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e
-	192.168.1.10 netmask 255.255.255.0
+# ifconfig carp0 192.168.1.10 vhid 1
+# ifconfig carp1 192.168.1.10 vhid 2 advskew 100
 .Ed
 .Pp
 The configuration for host B is identical, except the skew is on
 virtual host 1 rather than virtual host 2.
 .Bd -literal -offset indent
-# ifconfig carp0 create
-# ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e
-	192.168.1.10 netmask 255.255.255.0
-# ifconfig carp1 create
-# ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10 \e
-	netmask 255.255.255.0
+# ifconfig carp0 192.168.1.10 vhid 1 advskew 100
+# ifconfig carp1 192.168.1.10 vhid 2
 .Ed
 .Pp
-Finally, the ARP balancing feature must be enabled on both hosts:
+If ARP balancing is being used, it must be enabled on both hosts:
 .Pp
 .Dl # sysctl net.inet.carp.arpbalance=1
 .Pp
-When the hosts receive an ARP request for 192.168.1.10, the source IP address
-of the request is used to compute which virtual host should answer the request.
-The host which is master of the selected virtual host will reply to the
-request, the other(s) will ignore it.
+If IP balancing is being used, instead enable the
+.Cm link0
+and
+.Cm link1
+flags on the first interface of the load balancing group on both hosts:
+.Bd -literal -offset indent
+A# ifconfig carp0 192.168.1.10 vhid 1 link0 link1
+A# ifconfig carp1 192.168.1.10 vhid 2 advskew 100
 .Pp
-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.
+B# ifconfig carp0 192.168.1.10 vhid 1 advskew 100 link0 link1
+B# ifconfig carp1 192.168.1.10 vhid 2
+.Ed
 .Sh SEE ALSO
 .Xr sysctl 3 ,
 .Xr inet 4 ,