Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CARP(4)		       FreeBSD Kernel Interfaces Manual		       CARP(4)

     carp -- Common Address Redundancy Protocol

     pseudo-device carp

     The carp interface	is a pseudo-device which implements and	controls the
     CARP protocol.  carp allows multiple hosts	on the same local network to
     share a set of IP addresses.  Its primary purpose is to ensure that these
     addresses are always available, but in some configurations	carp can also
     provide load balancing functionality.

     A carp interface can be created at	runtime	using the ifconfig carpN
     create command or by setting up a hostname.if(5) configuration file for

     To	use carp, the administrator needs to configure at minimum a common
     virtual host ID (VHID) and	virtual	host IP	address	on each	machine	which
     is	to take	part in	the virtual group.  Additional parameters can also be
     set on a per-interface basis: advbase and advskew,	which are used to con-
     trol how frequently the host sends	advertisements when it is the master
     for a virtual host, and pass which	is used	to authenticate	carp adver-
     tisements.	 Finally carpdev is used to specify which interface the	carp
     device attaches to.  These	configurations can be done using ifconfig(8),
     or	through	the SIOCSVH ioctl.

     carp can also be used in conjunction with ifstated(8) to respond to
     changes in	CARP state; however, for most uses this	will not be necessary.
     See the manual page for ifstated(8) for more information.

     Additionally, there are a number of global	parameters which can be	set
     using sysctl(8):

     net.inet.carp.allow	 Accept	incoming carp packets.	Enabled	by de-

     net.inet.carp.preempt	 Allow virtual hosts to	preempt	each other.
				 Disabled by default.

     net.inet.carp.log		 Make carp log state changes, bad packets, and
				 other errors.	May be a value between 0 and 7
				 corresponding with syslog(3) priorities.  The
				 default value is 2, which limits logging to
				 changes in CARP state.

     carp uses IP balancing to load balance incoming traffic over a group of
     carp hosts.  IP balancing is not dependent	on ARP and therefore works for
     traffic that comes	over a router.	However	it requires the	traffic	that
     is	destined towards the load balanced IP addresses	to be received by all
     carp hosts.  While	this is	always the case	when connected to a hub, it
     has to play some tricks in	switched networks, which will result in	a
     higher network load.

     To	configure load balancing one has to specify multiple carp nodes	using
     the carpnodes option.  Each node in a load	balancing cluster is repre-
     sented by at least	one "vhid:advskew" pair	in a comma separated list.
     carp tries	to distribute the incoming network load	over all configured
     carpnodes.	 The following example creates a load balancing	group consist-
     ing of three nodes, using vhids 3,	4 and 6:

	   # ifconfig carp0 carpnodes 3:0,4:0,6:100

     The advskew value of the last node	is set to 100, so that this node is
     designated	to the BACKUP state.  It will only become MASTER if all	nodes
     with a lower advskew value	have failed.  By varying this value throughout
     the machines in the cluster it is possible	to decide which	share of the
     network load each node receives.  Therefore, all carp interfaces in the
     cluster are configured identically, except	for a different	advskew	value
     within the	carpnodes specification.

     IP	balancing works	by utilizing the network itself	to distribute incoming
     traffic to	all carp nodes in the cluster.	Each packet is filtered	on the
     incoming carp interface so	that only one node in the cluster accepts the
     packet.  All the other nodes will just silently drop it.  The filtering
     function uses a hash over the source and destination address of the IPv4
     or	IPv6 packet and	compares the result against the	state of the carpnode.

     IP	balancing is activated by setting the balancing	mode to	ip.  This is
     the recommended default setting.  In this mode, carp uses a multicast MAC
     address, so that a	switch sends incoming traffic towards all nodes.

     However, there are	a few OS and routers that do not accept	a multicast
     MAC address being mapped to a unicast IP.	This can be resolved by	using
     one of the	following unicast options.  For	scenarios where	a hub is used
     it	is not necessary to use	a multicast MAC	and it is safe to use the
     ip-unicast	mode.  Manageable switches can usually be tricked into for-
     warding unicast traffic to	all cluster nodes ports	by configuring them
     into some sort of monitoring mode.	 If this is not	possible, using	the
     ip-stealth	mode is	another	option,	which should work on most switches.
     In	this mode carp never sends packets with	its virtual MAC	address	as
     source.  Stealth mode prevents a switch from learning the virtual MAC ad-
     dress, so that it has to flood the	traffic	to all its ports.  Please note
     that activating stealth mode on a carp interface that has already been
     running might not work instantly.	As a workaround	the VHID of the	first
     carpnode can be changed to	a previously unused one, or just wait until
     the MAC table entry in the	switch times out.  Some	layer 3	switches do
     port learning based on ARP	packets.  Therefore the	stealth	mode cannot
     hide the virtual MAC address from these kind of devices.

     If	IP balancing is	being used on a	firewall, it is	recommended to config-
     ure the carpnodes in a symmetrical	manner.	 This is achieved by simply
     using the same carpnodes list on all sides	of the firewall.  This ensures
     that packets of one connection will pass in and out on the	same host and
     are not routed asymmetrically.

     For most scenarios	it is desirable	to have	a well-defined master,
     achieved by enabling the preempt option.  Enable it on both host A	and B:

	   # sysctl net.inet.carp.preempt=1

     Assume that host A	is the preferred master	and carp should	run on the
     physical interfaces em0 with the network and em1 with net-
     work  This	is the setup for host A:

	   # ifconfig carp0 carpdev em0 vhid 1
	   # ifconfig carp1 carpdev em1 vhid 2

     The setup for host	B is identical,	but it has a higher advskew:

	   # ifconfig carp0 carpdev em0 vhid 1 advskew 100
	   # ifconfig carp1 carpdev em1 vhid 2 advskew 100

     In	order to set up	a load balanced	virtual	host, it is necessary to con-
     figure one	carpnodes entry	for each physical host.	 In the	following ex-
     ample, two	physical hosts are configured to provide balancing and
     failover for the IP address

     First the carp interface on Host A	is configured.	The advskew of 100 on
     the second	carpnode entry means that its advertisements will be sent out
     slightly less frequently and will therefore become	the designated backup.

	   # ifconfig carp0 carpdev em0 carpnodes 1:0,2:100 \
		   balancing ip

     The configuration for host	B is identical,	except the skew	is on the
     carpnode entry with virtual host 1	rather than virtual host 2.

	   # ifconfig carp0 carpdev em0 carpnodes 1:100,2:0 \
		   balancing ip

     If	a different mode of load balancing is desired the balancing mode can
     be	adjusted accordingly.

     sysctl(2),	inet(4), pfsync(4), hostname.if(5), ifconfig(8), ifstated(8),
     netstart(8), sysctl(8)

     The carp device first appeared in OpenBSD 3.5.

     If	load balancing is used in setups where the carpdev does	not share an
     IP	in the same subnet as carp, it is not possible to use the IP of	the
     carp interface for	self originated	traffic.  This is because the return
     packets are also subject to load balancing	and might end up on any	other
     node in the cluster.

     If	an IPv6	load balanced carp interface is	taken down manually, it	will
     accept all	incoming packets for its address.  This	will lead to dupli-
     cated packets.

FreeBSD	13.0		       January 12, 2018			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help