share/man/man4/carp.4

   1 .\"
   2 .\" Copyright (c) 2003, Ryan McBride.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $
  26 .\" $FreeBSD: src/share/man/man4/carp.4,v 1.10 2006/06/07 10:26:51 glebius Exp $
  27 .\" $DragonFly: src/share/man/man4/carp.4,v 1.4 2008/10/17 12:41:38 swildner Exp $
  28 .\"
  29 .Dd April 9, 2007
  30 .Dt CARP 4
  31 .Os
  32 .Sh NAME
  33 .Nm carp
  34 .Nd Common Address Redundancy Protocol
  35 .Sh SYNOPSIS
  36 .Cd "options CARP"
  37 .Cd "pseudo-device carp"
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 interface is a pseudo-device that implements and controls the
  42 CARP protocol.
  43 CARP allows multiple hosts on the same local network to share a set of IP addresses.
  44 Its primary purpose is to ensure that these
  45 addresses are always available, but in some configurations
  46 .Nm
  47 can also provide load balancing functionality.
  48 .Pp
  49 A
  50 .Nm
  51 interface can be created at runtime using the
  52 .Nm ifconfig Li carp Ns Ar N Cm create
  53 command or by configuring
  54 it via
  55 .Va cloned_interfaces
  56 in the
  57 .Pa /etc/rc.conf
  58 file.
  59 .Pp
  60 To use
  61 .Nm ,
  62 the administrator needs to configure at minimum a common virtual host ID (VHID)
  63 and virtual host IP address on each machine which is to take part in the virtual
  64 group.
  65 Additional parameters can also be set on a per-interface basis:
  66 .Cm advbase
  67 and
  68 .Cm advskew ,
  69 which are used to control how frequently the host sends advertisements when it
  70 is the master for a virtual host, and
  71 .Cm pass
  72 which is used to authenticate
  73 .Nm
  74 advertisements.
  75 The
  76 .Cm advbase
  77 parameter stands for
  78 .Dq "advertisement base" .
  79 It is measured in seconds and specifies the base of the advertisement interval.
  80 The
  81 .Cm advskew
  82 parameter stands for
  83 .Dq "advertisement skew" .
  84 It is measured in 1/256 of seconds.
  85 It is added to the base advertisement interval to make one host advertise
  86 a bit slower than the other does.
  87 Both
  88 .Cm advbase
  89 and
  90 .Cm advskew
  91 are put inside CARP advertisements.
  92 These configurations can be done using
  93 .Xr ifconfig 8 ,
  94 or through the
  95 .Dv SIOCSVH
  96 .Xr ioctl 2 .
  97 .Pp
  98 Additionally, there are a number of global parameters which can be set using
  99 .Xr sysctl 8 :
 100 .Bl -tag -width ".Va net.inet.carp.arpbalance"
 101 .It Va net.inet.carp.allow
 102 Accept incoming
 103 .Nm
 104 packets.
 105 Enabled by default.
 106 .It Va net.inet.carp.preempt
 107 Allow virtual hosts to preempt each other.
 108 It is also used to failover
 109 .Nm
 110 interfaces as a group.
 111 When the option is enabled and one of the
 112 .Nm
 113 enabled physical interfaces
 114 goes down,
 115 .Cm advskew
 116 is changed to 240 on all
 117 .Nm
 118 interfaces.
 119 See also the first example.
 120 Disabled by default.
 121 .It Va net.inet.carp.log
 122 Value of 0 disables any logging.
 123 Value of 1 enables logging of bad
 124 .Nm
 125 packets.
 126 Values above 1 enable logging state changes of
 127 .Nm
 128 interfaces.
 129 Default value is 1.
 130 .It Va net.inet.carp.arpbalance
 131 Balance local traffic using ARP (see below).
 132 Disabled by default.
 133 .It Va net.inet.carp.suppress_preempt
 134 A read only value showing the status of preemption suppression.
 135 Preemption can be suppressed if link on an interface is down
 136 or when
 137 .Xr pfsync 4
 138 interface is not synchronized.
 139 Value of 0 means that preemption is not suppressed, since no
 140 problems are detected.
 141 Every problem increments suppression counter.
 142 .El
 143 .Sh ARP LEVEL LOAD BALANCING
 144 The
 145 .Nm
 146 has limited abilities for load balancing the incoming connections
 147 between hosts in Ethernet network.
 148 For load balancing operation, one needs several CARP interfaces that
 149 are configured to the same IP address, but to a different VHIDs.
 150 Once an ARP request is received, the CARP protocol will use a hashing
 151 function against the source IP address in the ARP request to determine
 152 which VHID should this request belong to.
 153 If the corresponding CARP interface is in master state, the ARP request
 154 will be replied, otherwise it will be ignored.
 155 See the
 156 .Sx EXAMPLES
 157 section for a practical example of load balancing.
 158 .Pp
 159 The ARP load balancing has some limitations.
 160 First, ARP balancing only works on the local network segment.
 161 It cannot balance traffic that crosses a router, because the
 162 router itself will always be balanced to the same virtual host.
 163 Second, ARP load balancing can lead to asymmetric routing
 164 of incoming and outgoing traffic, and thus combining it with
 165 .Xr pfsync 4
 166 is dangerous, because this creates a race condition between
 167 balanced routers and a host they are serving.
 168 Imagine an incoming packet creating state on the first router, being
 169 forwarded to its destination, and destination replying faster
 170 than the state information is packed and synced with the second router.
 171 If the reply would be load balanced to second router, it will be
 172 dropped due to no state.
 173 .Sh EXAMPLES
 174 For firewalls and routers with multiple interfaces, it is desirable to
 175 failover all of the
 176 .Nm
 177 interfaces together, when one of the physical interfaces goes down.
 178 This is achieved by the preempt option.
 179 Enable it on both host A and B:
 180 .Pp
 181 .Dl sysctl net.inet.carp.preempt=1
 182 .Pp
 183 Assume that host A is the preferred master and 192.168.1.x/24 is
 184 configured on one physical interface and 192.168.2.y/24 on another.
 185 This is the setup for host A:
 186 .Bd -literal -offset indent
 187 ifconfig carp0 create
 188 ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1/24
 189 ifconfig carp1 create
 190 ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1/24
 191 .Ed
 192 .Pp
 193 The setup for host B is identical, but it has a higher
 194 .Cm advskew :
 195 .Bd -literal -offset indent
 196 ifconfig carp0 create
 197 ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24
 198 ifconfig carp1 create
 199 ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24
 200 .Ed
 201 .Pp
 202 Because of the preempt option, when one of the physical interfaces of
 203 host A fails,
 204 .Cm advskew
 205 is adjusted to 240 on all its
 206 .Nm
 207 interfaces.
 208 This will cause host B to preempt on both interfaces instead of
 209 just the failed one.
 210 .Pp
 211 In order to set up an ARP balanced virtual host, it is necessary to configure
 212 one virtual host for each physical host which would respond to ARP requests
 213 and thus handle the traffic.
 214 In the following example, two virtual hosts are configured on two hosts to
 215 provide balancing and failover for the IP address 192.168.1.10.
 216 .Pp
 217 First the
 218 .Nm
 219 interfaces on host A are configured.
 220 The
 221 .Cm advskew
 222 of 100 on the second virtual host means that its advertisements will be sent
 223 out slightly less frequently.
 224 .Bd -literal -offset indent
 225 ifconfig carp0 create
 226 ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10/24
 227 ifconfig carp1 create
 228 ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24
 229 .Ed
 230 .Pp
 231 The configuration for host B is identical, except the
 232 .Cm advskew
 233 is on virtual host 1 rather than virtual host 2.
 234 .Bd -literal -offset indent
 235 ifconfig carp0 create
 236 ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24
 237 ifconfig carp1 create
 238 ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10/24
 239 .Ed
 240 .Pp
 241 Finally, the ARP balancing feature must be enabled on both hosts:
 242 .Pp
 243 .Dl sysctl net.inet.carp.arpbalance=1
 244 .Pp
 245 When the hosts receive an ARP request for 192.168.1.10, the source IP address
 246 of the request is used to compute which virtual host should answer the request.
 247 The host which is master of the selected virtual host will reply to the
 248 request, the other(s) will ignore it.
 249 .Pp
 250 This way, locally connected systems will receive different ARP replies and
 251 subsequent IP traffic will be balanced among the hosts.
 252 If one of the hosts fails, the other will take over the virtual MAC address,
 253 and begin answering ARP requests on its behalf.
 254 .Sh SEE ALSO
 255 .Xr inet 4 ,
 256 .Xr pfsync 4 ,
 257 .Xr rc.conf 5 ,
 258 .Xr ifconfig 8 ,
 259 .Xr sysctl 8
 260 .Sh HISTORY
 261 The
 262 .Nm
 263 device first appeared in
 264 .Ox 3.5 .
 265 It was imported into
 266 .Dx 1.11 .