share/man/man4/carp.4

   1 .\"     $OpenBSD: carp.4,v 1.16 2004/12/07 23:41:35 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 2003, Ryan McBride.  All rights reserved.
   4 .\" Copyright (c) 2011, Gleb Smirnoff <glebius@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd February 21, 2013
  30 .Dt CARP 4
  31 .Os
  32 .Sh NAME
  33 .Nm carp
  34 .Nd Common Address Redundancy Protocol
  35 .Sh SYNOPSIS
  36 .Cd "device carp"
  37 .Sh DESCRIPTION
  38 The CARP allows multiple hosts on the same local network to share a set of
  39 IPv4 and/or IPv6 addresses.
  40 Its primary purpose is to ensure that these
  41 addresses are always available.
  42 .Pp
  43 To use
  44 .Nm ,
  45 the administrator needs to configure at a minimum a common virtual host ID
  46 (vhid), and attach at least one IP address to this vhid on each machine which
  47 is to take part in the virtual group.
  48 Additional parameters can also be set on a per-vhid basis:
  49 .Cm advbase
  50 and
  51 .Cm advskew ,
  52 which are used to control how frequently the host sends advertisements when it
  53 is the master for a virtual host, and
  54 .Cm pass
  55 which is used to authenticate
  56 .Nm
  57 advertisements.
  58 The
  59 .Cm advbase
  60 parameter stands for
  61 .Dq "advertisement base" .
  62 It is measured in seconds and specifies the base of the advertisement interval.
  63 The
  64 .Cm advskew
  65 parameter stands for
  66 .Dq "advertisement skew" .
  67 It is measured in 1/256 of seconds.
  68 It is added to the base advertisement interval to make one host advertise
  69 a bit slower that the other does.
  70 Both
  71 .Cm advbase
  72 and
  73 .Cm advskew
  74 are put inside CARP advertisements.
  75 These values can be configured using
  76 .Xr ifconfig 8 ,
  77 or through the
  78 .Dv SIOCSVH
  79 .Xr ioctl 2 .
  80 .Pp
  81 CARP virtual hosts can be configured on multicast-capable interfaces: Ethernet,
  82 layer 2 VLAN, FDDI and Token Ring.
  83 An arbitrary number of virtual host IDs can be configured on an interface.
  84 An arbitrary number of IPv4 or IPv6 addresses can be attached to a particular
  85 vhid.
  86 It is important that all hosts participating in a vhid have the same list
  87 of prefixes configured on the vhid, since all prefixes are included in the
  88 cryptographic checksum supplied in each advertisement.
  89 Multiple vhids running on one interface participate in master/backup
  90 elections independently.
  91 .Pp
  92 Additionally, there are a number of global parameters which can be set using
  93 .Xr sysctl 8 :
  94 .Bl -tag -width ".Va net.inet.carp.ifdown_demotion_factor"
  95 .It Va net.inet.carp.allow
  96 Accept incoming
  97 .Nm
  98 packets.
  99 Enabled by default.
 100 .It Va net.inet.carp.preempt
 101 Allow virtual hosts to preempt each other.
 102 When enabled, a vhid in a backup state would preempt a master that
 103 is announcing itself with a lower advskew.
 104 Disabled by default.
 105 .It Va net.inet.carp.log
 106 Determines what events relating to
 107 .Nm
 108 vhids are logged.
 109 A value of 0 disables any logging.
 110 A value of 1 enables logging state changes of
 111 .Nm
 112 vhids.
 113 Values above 1 enable logging of bad
 114 .Nm
 115 packets.
 116 The default value is 1.
 117 .It Va net.inet.carp.demotion
 118 This value shows current level of CARP demotion.
 119 The value is added to the actual advskew sent in announcements for
 120 all vhids.
 121 At normal system operation the demotion factor is zero.
 122 However, problematic conditions raise its level: when
 123 .Nm
 124 experiences problem with sending announcements, when an interface
 125 running a vhid goes down, or while the
 126 .Xr pfsync 4
 127 interface is not synchronized.
 128 The demotion factor can be adjusted writing to the sysctl oid.
 129 The signed value supplied to the
 130 .Xr sysctl 8
 131 command is added to current demotion factor.
 132 This allows to control
 133 .Nm
 134 behaviour depending on some external conditions, for example on the status
 135 of some daemon utility.
 136 .It Va net.inet.carp.ifdown_demotion_factor
 137 This value is added to
 138 .Va net.inet.carp.demotion
 139 when an interface running a vhid goes down.
 140 The default value is 240 (the maximum advskew value).
 141 .It Va net.inet.carp.senderr_demotion_factor
 142 This value is added to
 143 .Va net.inet.carp.demotion
 144 when
 145 .Nm
 146 experiences errors sending its announcements.
 147 The default value is 240 (the maximum advskew value).
 148 .El
 149 .\".Sh ARP level load balancing
 150 .\"A
 151 .\".Nm
 152 .\"interface has limited abilities for load balancing incoming connections
 153 .\"between hosts in an Ethernet network.
 154 .\"For load-balancing operation, one needs several CARP interfaces that
 155 .\"are configured to the same IP address, but to a different vhids.
 156 .\"Once an ARP request is received, the CARP protocol will use a hashing
 157 .\"function against the source IP address in the ARP request to determine
 158 .\"which vhid the request will be assigned to.
 159 .\"If the corresponding CARP interface is the current
 160 .\"master interface, a reply will
 161 .\"be sent to the ARP request;
 162 .\"otherwise it will be ignored.
 163 .\"See the
 164 .\".Sx EXAMPLES
 165 .\"section for a practical example of load balancing.
 166 .\".Pp
 167 .\"The ARP load balancing implemented in
 168 .\".Nm
 169 .\"has some limitations.
 170 .\"First, ARP balancing only works on the local network segment.
 171 .\"It cannot balance traffic that crosses a router, because the
 172 .\"router itself will always be balanced to the same virtual host.
 173 .\"Second, ARP load balancing can lead to asymmetric routing
 174 .\"of incoming and outgoing traffic, and thus combining it with
 175 .\".Xr pfsync 4
 176 .\"is dangerous, because this creates a race condition between
 177 .\"balanced routers and a host they are serving.
 178 .\"Imagine an incoming packet creating state on the first router, being
 179 .\"forwarded to its destination, and the destination replying faster
 180 .\"than the state information is packed and synced with the second router.
 181 .\"If the reply would be load balanced to second router, it will be
 182 .\"dropped since the second router has not yet received information about
 183 .\"the connection state.
 184 .Sh STATE CHANGE NOTIFICATIONS
 185 Sometimes it is useful to get notified about
 186 .Nm
 187 status change events.
 188 This can be accomplished by using
 189 .Xr devd 8
 190 hooks.
 191 Master/slave events are signalled under system
 192 .Dv CARP .
 193 The subsystem specifies the vhid and name of the interface where
 194 the master/slave event occurred.
 195 The type of the message displays the new state of the vhid.
 196 Please see
 197 .Xr devd.conf 5
 198 and the
 199 .Sx EXAMPLES
 200 section for more information.
 201 .Sh EXAMPLES
 202 For firewalls and routers with multiple interfaces, it is desirable to
 203 failover all of the addresses running
 204 .Nm
 205 together, when one of the physical interfaces goes down.
 206 This is achieved by the use of the preempt option.
 207 Enable it on both hosts A and B:
 208 .Pp
 209 .Dl sysctl net.inet.carp.preempt=1
 210 .Pp
 211 Assume that host A is the preferred master and we are running the
 212 192.168.1.0/24 prefix on em0 and 192.168.2.0/24 on em1.
 213 This is the setup for host A:
 214 .Bd -literal -offset indent
 215 ifconfig em0 vhid 1 pass mekmitasdigoat 192.168.1.1/24
 216 ifconfig em1 vhid 2 pass mekmitasdigoat 192.168.2.1/24
 217 .Ed
 218 .Pp
 219 The setup for host B is identical, but it has a higher
 220 .Cm advskew :
 221 .Bd -literal -offset indent
 222 ifconfig em0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24
 223 ifconfig em1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24
 224 .Ed
 225 .Pp
 226 When one of the physical interfaces of host A fails,
 227 .Cm advskew
 228 is demoted to a configured value on all its
 229 .Nm
 230 vhids.
 231 Due to the preempt option, host B would start announcing itself, and thus
 232 preempt host A on both interfaces instead of just the failed one.
 233 .\".Pp
 234 .\"In order to set up an ARP balanced virtual host, it is necessary to configure
 235 .\"one virtual host for each physical host which would respond to ARP requests
 236 .\"and thus handle the traffic.
 237 .\"In the following example, two virtual hosts are configured on two hosts to
 238 .\"provide balancing and failover for the IP address 192.168.1.10.
 239 .\".Pp
 240 .\"First the
 241 .\".Nm
 242 .\"interfaces on host A are configured.
 243 .\"The
 244 .\".Cm advskew
 245 .\"of 100 on the second virtual host means that its advertisements will be sent
 246 .\"out slightly less frequently.
 247 .\".Bd -literal -offset indent
 248 .\"ifconfig carp0 create
 249 .\"ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10/24
 250 .\"ifconfig carp1 create
 251 .\"ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.1.10/24
 252 .\".Ed
 253 .\".Pp
 254 .\"The configuration for host B is identical, except the
 255 .\".Cm advskew
 256 .\"is on virtual host 1 rather than virtual host 2.
 257 .\".Bd -literal -offset indent
 258 .\"ifconfig carp0 create
 259 .\"ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.10/24
 260 .\"ifconfig carp1 create
 261 .\"ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10/24
 262 .\".Ed
 263 .\".Pp
 264 .\"Finally, the ARP balancing feature must be enabled on both hosts:
 265 .\".Pp
 266 .\".Dl sysctl net.inet.carp.arpbalance=1
 267 .\".Pp
 268 .\"When the hosts receive an ARP request for 192.168.1.10, the source IP address
 269 .\"of the request is used to compute which virtual host should answer the request.
 270 .\"The host which is master of the selected virtual host will reply to the
 271 .\"request, the other(s) will ignore it.
 272 .\".Pp
 273 .\"This way, locally connected systems will receive different ARP replies and
 274 .\"subsequent IP traffic will be balanced among the hosts.
 275 .\"If one of the hosts fails, the other will take over the virtual MAC address,
 276 .\"and begin answering ARP requests on its behalf.
 277 .Pp
 278 Processing of
 279 .Nm
 280 status change events can be set up by using the following devd.conf rule:
 281 .Bd -literal -offset indent
 282 notify 0 {
 283         match "system"          "CARP";
 284         match "subsystem"       "[0-9]+@[0-9a-z]+";
 285         match "type"            "(MASTER|BACKUP)";
 286         action "/root/carpcontrol.sh $subsystem $type";
 287 };
 288 .Ed
 289 .Pp
 290 To see
 291 .Nm
 292 packets decoded in
 293 .Xr tcpdump 8
 294 output, one needs to specify
 295 .Fl T Ar carp
 296 option, otherwise
 297 .Xr tcpdump 8
 298 tries to interpret them as VRRP packets:
 299 .Bd -literal -offset indent
 300 tcpdump -npi vlan0 -T carp
 301 .Ed
 302 .Sh SEE ALSO
 303 .Xr inet 4 ,
 304 .Xr pfsync 4 ,
 305 .Xr rc.conf 5 ,
 306 .Xr devd.conf 5 ,
 307 .Xr ifconfig 8 ,
 308 .Xr sysctl 8
 309 .Xr tcpdump 8
 310 .Sh HISTORY
 311 The
 312 .Nm
 313 device first appeared in
 314 .Ox 3.5 .
 315 The
 316 .Nm
 317 device was imported into
 318 .Fx 5.4 .
 319 In
 320 .Fx 10.0 ,
 321 .Nm
 322 was significantly rewritten, and is no longer a pseudo-interface.