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.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd February 25, 2005 29.Dt CARP 4 30.Os 31.Sh NAME 32.Nm carp 33.Nd Common Address Redundancy Protocol 34.Sh SYNOPSIS 35.Cd "device carp" 36.Sh DESCRIPTION 37The 38.Nm 39interface is a pseudo-device that implements and controls the 40CARP protocol. 41CARP allows multiple hosts on the same local network to share a set of IP addresses. 42Its primary purpose is to ensure that these 43addresses are always available, but in some configurations 44.Nm 45can also provide load balancing functionality. 46.Pp 47A 48.Nm 49interface can be created at runtime using the 50.Nm ifconfig Li carp Ns Ar N Cm create 51command or by setting up configuration in 52.Pa /etc/rc.conf 53file. 54.Pp 55To use 56.Nm , 57the administrator needs to configure at minimum a common virtual host ID and 58virtual host IP address on each machine which is to take part in the virtual 59group. 60Additional parameters can also be set on a per-interface basis: 61.Cm advbase 62and 63.Cm advskew , 64which are used to control how frequently the host sends advertisements when it 65is the master for a virtual host, and 66.Cm pass 67which is used to authenticate 68.Nm 69advertisements. 70Finally 71.Cm carpdev 72is used to specify which interface the 73.Nm 74device attaches to. 75If unspecified, the kernel attempts to set 76.Cm carpdev 77by looking for 78another interface with the same subnet. 79These configurations can be done using 80.Xr ifconfig 8 , 81or through the 82.Dv SIOCSVH 83.Xr ioctl 2 . 84.Pp 85Additionally, there are a number of global parameters which can be set using 86.Xr sysctl 8 : 87.Bl -tag -width ".Va net.inet.carp.arpbalance" 88.It Va net.inet.carp.allow 89Accept incoming 90.Nm 91packets. 92Enabled by default. 93.It Va net.inet.carp.preempt 94Allow virtual hosts to preempt each other. 95It is also used to failover 96.Nm 97interfaces as a group. 98When the option is enabled and one of the 99.Nm 100enabled physical interfaces 101goes down, 102.Cm advskew 103is changed to 240 on all 104.Nm 105interfaces. 106See also the first example. 107Disabled by default. 108.It Va net.inet.carp.log 109Value of 0 disables any logging. 110Value of 1 enables logging of bad 111.Nm 112packets. 113Values above 1 enable logging state changes of 114.Nm 115interfaces. 116Default value is 1. 117.It Va net.inet.carp.arpbalance 118Balance local traffic using ARP. 119Disabled by default. 120.El 121.Sh EXAMPLES 122For firewalls and routers with multiple interfaces, it is desirable to 123failover all of the 124.Nm 125interfaces together, when one of the physical interfaces goes down. 126This is achieved by the preempt option. 127Enable it on both host A and B: 128.Pp 129.Dl sysctl net.inet.carp.preempt=1 130.Pp 131Assume that host A is the preferred master and 192.168.1.x/24 is 132configured on one physical interface and 192.168.2.y/24 on another. 133This is the setup for host A: 134.Bd -literal -offset indent 135ifconfig carp0 create 136ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.1 \e 137 255.255.255.0 138ifconfig carp1 create 139ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.2.1 \e 140 255.255.255.0 141.Ed 142.Pp 143The setup for host B is identical, but it has a higher 144.Cm advskew : 145.Bd -literal -offset indent 146ifconfig carp0 create 147ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e 148 192.168.1.1 255.255.255.0 149ifconfig carp1 create 150ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e 151 192.168.2.1 255.255.255.0 152.Ed 153.Pp 154Because of the preempt option, when one of the physical interfaces of 155host A fails, 156.Cm advskew 157is adjusted to 240 on all its 158.Nm 159interfaces. 160This will cause host B to preempt on both interfaces instead of 161just the failed one. 162.Pp 163In order to set up an ARP balanced virtual host, it is necessary to configure 164one virtual host for each physical host which would respond to ARP requests 165and thus handle the traffic. 166In the following example, two virtual hosts are configured on two hosts to 167provide balancing and failover for the IP address 192.168.1.10. 168.Pp 169First the 170.Nm 171interfaces on host A are configured. 172The 173.Cm advskew 174of 100 on the second virtual host means that its advertisements will be sent 175out slightly less frequently. 176.Bd -literal -offset indent 177ifconfig carp0 create 178ifconfig carp0 vhid 1 pass mekmitasdigoat 192.168.1.10 \e 179 255.255.255.0 180ifconfig carp1 create 181ifconfig carp1 vhid 2 advskew 100 pass mekmitasdigoat \e 182 192.168.1.10 255.255.255.0 183.Ed 184.Pp 185The configuration for host B is identical, except the 186.Cm advskew 187is on virtual host 1 rather than virtual host 2. 188.Bd -literal -offset indent 189ifconfig carp0 create 190ifconfig carp0 vhid 1 advskew 100 pass mekmitasdigoat \e 191 192.168.1.10 255.255.255.0 192ifconfig carp1 create 193ifconfig carp1 vhid 2 pass mekmitasdigoat 192.168.1.10 \e 194 255.255.255.0 195.Ed 196.Pp 197Finally, the ARP balancing feature must be enabled on both hosts: 198.Pp 199.Dl sysctl net.inet.carp.arpbalance=1 200.Pp 201When the hosts receive an ARP request for 192.168.1.10, the source IP address 202of the request is used to compute which virtual host should answer the request. 203The host which is master of the selected virtual host will reply to the 204request, the other(s) will ignore it. 205.Pp 206This way, locally connected systems will receive different ARP replies and 207subsequent IP traffic will be balanced among the hosts. 208If one of the hosts fails, the other will take over the virtual MAC address, 209and begin answering ARP requests on its behalf. 210.Pp 211Note: ARP balancing only works on the local network segment. 212It cannot balance traffic that crosses a router, because the router 213itself will always be balanced to the same virtual host. 214.Sh SEE ALSO 215.Xr inet 4 , 216.Xr rc.conf 5 , 217.Xr ifconfig 8 , 218.Xr sysctl 8 219.Sh HISTORY 220The 221.Nm 222device first appeared in 223.Ox 3.5 . 224The 225.Nm 226device was imported into 227.Fx 5.4 . 228