share/man/man4/carp.4

   1 .\"     $NetBSD: carp.4,v 1.3 2006/12/23 06:52:49 wiz Exp $
   2 .\"     $OpenBSD: carp.4,v 1.19 2005/08/09 09:52:12 jmc Exp $
   3 .\"
   4 .\" Copyright (c) 2003, Ryan McBride.  All rights reserved.
   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 .Dd October 16, 2003
  28 .Dt CARP 4
  29 .Os
  30 .Sh NAME
  31 .Nm carp
  32 .Nd Common Address Redundancy Protocol
  33 .Sh SYNOPSIS
  34 .Cd "pseudo-device carp" Op Ar count
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 interface is a pseudo-device which implements and controls the
  39 CARP protocol.
  40 .Nm
  41 allows multiple hosts on the same local network to share a set of IP addresses.
  42 Its primary purpose is to ensure that these
  43 addresses are always available, but in some configurations
  44 .Nm
  45 can also provide load balancing functionality.
  46 .Pp
  47 A
  48 .Nm
  49 interface can be created at runtime using the
  50 .Ic ifconfig carp Ns Ar N Ic create
  51 command.
  52 .Pp
  53 To use
  54 .Nm ,
  55 the administrator needs to configure at minimum a common virtual host ID and
  56 virtual host IP address on each machine which is to take part in the virtual
  57 group.
  58 Additional parameters can also be set on a per-interface basis:
  59 .Cm advbase
  60 and
  61 .Cm advskew ,
  62 which are used to control how frequently the host sends advertisements when it
  63 is the master for a virtual host, and
  64 .Cm pass
  65 which is used to authenticate carp advertisements.
  66 Finally
  67 .Cm carpdev
  68 is used to specify which interface the
  69 .Nm
  70 device attaches to.
  71 If unspecified, the kernel attempts to set carpdev by looking for
  72 another interface with the same subnet.
  73 These configurations can be done using
  74 .Xr ifconfig 8 ,
  75 or through the
  76 .Dv SIOCSVH
  77 ioctl.
  78 .Pp
  79 Additionally, there are a number of global parameters which can be set using
  80 .Xr sysctl 8 :
  81 .Bl -tag -width xxxxxxxxxxxxxxxxxxxxxxxxxx
  82 .It net.inet.carp.allow
  83 Accept incoming
  84 .Nm
  85 packets.
  86 Enabled by default.
  87 .It net.inet.carp.preempt
  88 Allow virtual hosts to preempt each other.
  89 It is also used to failover
  90 .Nm
  91 interfaces as a group.
  92 When the option is enabled and one of the
  93 .Nm
  94 enabled physical interfaces
  95 goes down, advskew is changed to 240 on all
  96 .Nm
  97 interfaces.
  98 See also the first example.
  99 Disabled by default.
 100 .It net.inet.carp.log
 101 Log bad
 102 .Nm
 103 packets.
 104 Disabled by default.
 105 .It net.inet.carp.arpbalance
 106 Balance local traffic using ARP.
 107 Disabled by default.
 108 .El
 109 .Sh EXAMPLES
 110 For firewalls and routers with multiple interfaces, it is desirable to
 111 failover all of the
 112 .Nm
 113 interfaces together, when one of the physical interfaces goes down.
 114 This is achieved by the preempt option.
 115 Enable it on both host A and B:
 116 .Pp
 117 .Dl # sysctl -w net.inet.carp.preempt=1
 118 .Pp
 119 Assume that host A is the preferred master and 192.168.1.x/24 is
 120 configured on one physical interface and 192.168.2.y/24 on another.
 121 This is the setup for host A:
 122 .Bd -literal -offset indent
 123 # ifconfig carp0 create
 124 # ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1 \e
 125         netmask 255.255.255.0
 126 # ifconfig carp1 create
 127 # ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1/24 \e
 128         netmask 255.255.255.0
 129 .Ed
 130 .Pp
 131 The setup for host B is identical, but it has a higher advskew:
 132 .Bd -literal -offset indent
 133 # ifconfig carp0 create
 134 # ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e
 135         192.168.1.1 netmask 255.255.255.0
 136 # ifconfig carp1 create
 137 # ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e
 138         192.168.2.1 netmask 255.255.255.0
 139 .Ed
 140 .Pp
 141 Because of the preempt option, when one of the physical interfaces of
 142 host A fails, advskew is adjusted to 240 on all its
 143 .Nm
 144 interfaces.
 145 This will cause host B to preempt on both interfaces instead of
 146 just the failed one.
 147 .Pp
 148 In order to set up an ARP balanced virtual host, it is necessary to configure
 149 one virtual host for each physical host which would respond to ARP requests
 150 and thus handle the traffic.
 151 In the following example, two virtual hosts are configured on two hosts to
 152 provide balancing and failover for the IP address 192.168.1.10.
 153 .Pp
 154 First the
 155 .Nm
 156 interfaces on Host A are configured.
 157 The
 158 .Cm advskew
 159 of 100 on the second virtual host means that its advertisements will be sent
 160 out slightly less frequently.
 161 .Bd -literal -offset indent
 162 # ifconfig carp0 create
 163 # ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10 \e
 164         netmask 255.255.255.0
 165 # ifconfig carp1 create
 166 # ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e
 167         192.168.1.10 netmask 255.255.255.0
 168 .Ed
 169 .Pp
 170 The configuration for host B is identical, except the skew is on
 171 virtual host 1 rather than virtual host 2.
 172 .Bd -literal -offset indent
 173 # ifconfig carp0 create
 174 # ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e
 175         192.168.1.10 netmask 255.255.255.0
 176 # ifconfig carp1 create
 177 # ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10 \e
 178         netmask 255.255.255.0
 179 .Ed
 180 .Pp
 181 Finally, the ARP balancing feature must be enabled on both hosts:
 182 .Pp
 183 .Dl # sysctl -w net.inet.carp.arpbalance=1
 184 .Pp
 185 When the hosts receive an ARP request for 192.168.1.10, the source IP address
 186 of the request is used to compute which virtual host should answer the request.
 187 The host which is master of the selected virtual host will reply to the
 188 request, the other(s) will ignore it.
 189 .Pp
 190 This way, locally connected systems will receive different ARP replies and
 191 subsequent IP traffic will be balanced among the hosts.
 192 If one of the hosts fails, the other will take over the virtual MAC address,
 193 and begin answering ARP requests on its behalf.
 194 .Pp
 195 Note: ARP balancing only works on the local network segment.
 196 It cannot balance traffic that crosses a router, because the router
 197 itself will always be balanced to the same virtual host.
 198 .Sh SEE ALSO
 199 .Xr netstat 1 ,
 200 .Xr sysctl 3 ,
 201 .Xr arp 4 ,
 202 .Xr arp 8 ,
 203 .Xr ifconfig 8 ,
 204 .Xr sysctl 8
 205 .Sh HISTORY
 206 The
 207 .Nm
 208 device first appeared in
 209 .Ox 3.5 .