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