1.\" $NetBSD: carp.4,v 1.8 2020/10/12 15:18:48 roy 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 12, 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 79Additionally, 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 83Accept incoming 84.Nm 85packets. 86Enabled by default. 87.It net.inet.carp.preempt 88Allow virtual hosts to preempt each other. 89It is also used to failover 90.Nm 91interfaces as a group. 92When the option is enabled and one of the 93.Nm 94enabled physical interfaces 95goes down, advskew is changed to 240 on all 96.Nm 97interfaces. 98See also the first example. 99Disabled by default. 100.It net.inet.carp.log 101Log bad 102.Nm 103packets. 104Disabled by default. 105.It net.inet.carp.arpbalance 106Balance local traffic using ARP. 107Disabled by default. 108.El 109.Sh EXAMPLES 110For firewalls and routers with multiple interfaces, it is desirable to 111failover all of the 112.Nm 113interfaces together, when one of the physical interfaces goes down. 114This is achieved by the preempt option. 115Enable it on both host A and B: 116.Pp 117.Dl # sysctl -w net.inet.carp.preempt=1 118.Pp 119Assume that host A is the preferred master and 192.168.1.x/24 is 120configured on one physical interface and 192.168.2.y/24 on another. 121This 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 \e 128 netmask 255.255.255.0 129.Ed 130.Pp 131The 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 141Because of the preempt option, when one of the physical interfaces of 142host A fails, advskew is adjusted to 240 on all its 143.Nm 144interfaces. 145This will cause host B to preempt on both interfaces instead of 146just the failed one. 147.Pp 148In order to set up an ARP balanced virtual host, it is necessary to configure 149one virtual host for each physical host which would respond to ARP requests 150and thus handle the traffic. 151In the following example, two virtual hosts are configured on two hosts to 152provide balancing and failover for the IP address 192.168.1.10. 153.Pp 154First the 155.Nm 156interfaces on Host A are configured. 157The 158.Cm advskew 159of 100 on the second virtual host means that its advertisements will be sent 160out 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 170The configuration for host B is identical, except the skew is on 171virtual 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 181Finally, the ARP balancing feature must be enabled on both hosts: 182.Pp 183.Dl # sysctl -w net.inet.carp.arpbalance=1 184.Pp 185When the hosts receive an ARP request for 192.168.1.10, the source IP address 186of the request is used to compute which virtual host should answer the request. 187The host which is master of the selected virtual host will reply to the 188request, the other(s) will ignore it. 189.Pp 190This way, locally connected systems will receive different ARP replies and 191subsequent IP traffic will be balanced among the hosts. 192If one of the hosts fails, the other will take over the virtual MAC address, 193and begin answering ARP requests on its behalf. 194.Pp 195Note: ARP balancing only works on the local network segment. 196It cannot balance traffic that crosses a router, because the router 197itself 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 206The 207.Nm 208device first appeared in 209.Ox 3.5 . 210