1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
<table class="head">
<tr>
<td class="head-ltitle">CARP(4)</td>
<td class="head-vol">Device Drivers Manual</td>
<td class="head-rtitle">CARP(4)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">carp</code> — <span class="Nd">Common
Address Redundancy Protocol</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">device carp</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The CARP allows multiple hosts on the same local network to share
a set of IPv4 and/or IPv6 addresses. Its primary purpose is to ensure that
these addresses are always available.</p>
<p class="Pp">To use <code class="Nm">carp</code>, the administrator needs to
configure at a minimum a common virtual host ID (vhid), and attach at least
one IP address to this vhid on each machine which is to take part in the
virtual group. Additional parameters can also be set on a per-vhid basis:
<code class="Cm">advbase</code> and <code class="Cm">advskew</code>, which
are used to control how frequently the host sends advertisements when it is
the master for a virtual host, and <code class="Cm">pass</code> which is
used to authenticate <code class="Nm">carp</code> advertisements. The
<code class="Cm">advbase</code> parameter stands for “advertisement
base”. It is measured in seconds and specifies the base of the
advertisement interval. The <code class="Cm">advskew</code> parameter stands
for “advertisement skew”. It is measured in 1/256 of seconds.
It is added to the base advertisement interval to make one host advertise a
bit slower that the other does. Both <code class="Cm">advbase</code> and
<code class="Cm">advskew</code> are put inside CARP advertisements. These
values can be configured using <a class="Xr">ifconfig(8)</a>.</p>
<p class="Pp">CARP defaults to using multicast messages, but can be configured
to unicast announcements to peers using the <code class="Cm">peer</code> and
<code class="Cm">peer6</code> parameters. Default addresses can be restored
using <code class="Cm">mcast</code> and <code class="Cm">mcast6</code>. Note
that TTL verification is disabled if the peer address is not a multicast
address. These values can be configured using
<a class="Xr">ifconfig(8)</a>.</p>
<p class="Pp"><a class="Xr">carp(4)</a> can be configured to use either the
non-standard CARP protocol, or VRRPv3 (RFC 5798). Use the
<code class="Cm">carpver</code> parameter to select either 2 (CARP) or 3
(VRRPv3). VRRPv3 specific parameters can be configured using the
<code class="Cm">vrrpprio</code> and <code class="Cm">vrrpinterval</code>
parameters.</p>
<p class="Pp">CARP virtual hosts can be configured on multicast-capable
interfaces: Ethernet, layer 2 VLAN, FDDI and Token Ring. An arbitrary number
of virtual host IDs can be configured on an interface. An arbitrary number
of IPv4 or IPv6 addresses can be attached to a particular vhid. It is
important that all hosts participating in a vhid have the same list of
prefixes configured on the vhid, since all the prefixes are included in the
cryptographic checksum supplied in each advertisement. Multiple vhids
running on one interface participate in master/backup elections
independently.</p>
<p class="Pp">Additionally, there are a number of global parameters which can be
set using <a class="Xr">sysctl(8)</a>:</p>
<dl class="Bl-tag">
<dt id="net.inet.carp.allow"><var class="Va">net.inet.carp.allow</var></dt>
<dd>Allow <code class="Nm">carp</code> operation. When disabled, virtual hosts
remain in initial state, neither sending nor receiving announcements or
traffic. Enabled by default.</dd>
<dt id="net.inet.carp.preempt"><var class="Va">net.inet.carp.preempt</var></dt>
<dd>Allow virtual hosts to preempt each other. When enabled, a vhid in a
backup state would preempt a master that is announcing itself with a lower
advskew. Disabled by default.</dd>
<dt id="net.inet.carp.dscp"><var class="Va">net.inet.carp.dscp</var></dt>
<dd>DSCP value in carp packet. Valid Values are 0 to 63. A value of 4 is
equivalent to the old standard of TOS LOW_DELAY. TOS values were
deprecated and replaced by DSCP in 1998. The default value is 56
(CS7/Network Control).</dd>
<dt id="net.inet.carp.log"><var class="Va">net.inet.carp.log</var></dt>
<dd>Determines what events relating to <code class="Nm">carp</code> vhids are
logged. A value of 0 disables any logging. A value of 1 enables logging
state changes of <code class="Nm">carp</code> vhids. Values above 1 enable
logging of bad <code class="Nm">carp</code> packets. The default value is
1.</dd>
<dt id="net.inet.carp.demotion"><var class="Va">net.inet.carp.demotion</var></dt>
<dd>This value shows the current level of CARP demotion. The value is added to
the actual advskew sent in announcements for all vhids. During normal
system operation the demotion factor is zero. However, problematic
conditions raise its level: when <code class="Nm">carp</code> experiences
problem with sending announcements, when an interface running a vhid goes
down, or while the <a class="Xr">pfsync(4)</a> interface is not
synchronized. The demotion factor can be adjusted writing to the sysctl
oid. The signed value supplied to the <a class="Xr">sysctl(8)</a> command
is added to current demotion factor. This allows to control
<code class="Nm">carp</code> behaviour depending on some external
conditions, for example on the status of some daemon utility.</dd>
<dt id="net.inet.carp.ifdown_demotion_factor"><var class="Va">net.inet.carp.ifdown_demotion_factor</var></dt>
<dd>This value is added to <var class="Va">net.inet.carp.demotion</var> when
an interface running a vhid goes down. The default value is 240 (the
maximum advskew value).</dd>
<dt id="net.inet.carp.senderr_demotion_factor"><var class="Va">net.inet.carp.senderr_demotion_factor</var></dt>
<dd>This value is added to <var class="Va">net.inet.carp.demotion</var> when
<code class="Nm">carp</code> experiences errors sending its announcements.
The default value is 240 (the maximum advskew value).</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="STATE_CHANGE_NOTIFICATIONS"><a class="permalink" href="#STATE_CHANGE_NOTIFICATIONS">STATE
CHANGE NOTIFICATIONS</a></h1>
<p class="Pp">Sometimes it is useful to get notified about
<code class="Nm">carp</code> status change events. This can be accomplished
by using <a class="Xr">devd(8)</a> hooks. Master/slave events are signalled
under system <code class="Dv">CARP</code>. The subsystem specifies the vhid
and name of the interface where the master/slave event occurred. The type of
the message displays the new state of the vhid. Please see
<a class="Xr">devd.conf(5)</a> and the
<a class="Sx" href="#EXAMPLES">EXAMPLES</a> section for more
information.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
<p class="Pp">For firewalls and routers with multiple interfaces, it is
desirable to failover all of the addresses running
<code class="Nm">carp</code> together, when one of the physical interfaces
goes down. This is achieved by the use of the preempt option. Enable it on
both hosts A and B:</p>
<p class="Pp"></p>
<div class="Bd Bd-indent"><code class="Li">sysctl
net.inet.carp.preempt=1</code></div>
<p class="Pp">Assume that host A is the preferred master and we are running the
192.168.1.0/24 prefix on em0 and 192.168.2.0/24 on em1. This is the setup
for host A (advskew is above 0 so it could be overwritten in the emergency
situation from the other host):</p>
<div class="Bd Pp Bd-indent Li">
<pre>ifconfig em0 vhid 1 advskew 100 pass mekmitasdigoat 192.168.1.1/24
ifconfig em1 vhid 2 advskew 100 pass mekmitasdigoat 192.168.2.1/24</pre>
</div>
<p class="Pp">The setup for host B is identical, but it has a higher
<code class="Cm">advskew</code>:</p>
<div class="Bd Pp Bd-indent Li">
<pre>ifconfig em0 vhid 1 advskew 200 pass mekmitasdigoat 192.168.1.1/24
ifconfig em1 vhid 2 advskew 200 pass mekmitasdigoat 192.168.2.1/24</pre>
</div>
<p class="Pp">When one of the physical interfaces of host A fails,
<code class="Cm">advskew</code> is demoted to a configured value on all its
<code class="Nm">carp</code> vhids. Due to the preempt option, host B would
start announcing itself, and thus preempt host A on both interfaces instead
of just the failed one.</p>
<p class="Pp">Processing of <code class="Nm">carp</code> status change events
can be set up by using the following devd.conf rule:</p>
<div class="Bd Pp Bd-indent Li">
<pre>notify 0 {
match "system" "CARP";
match "subsystem" "[0-9]+@[0-9a-z.]+";
match "type" "(MASTER|BACKUP)";
action "/root/carpcontrol.sh $subsystem $type";
};</pre>
</div>
<p class="Pp">To see <code class="Nm">carp</code> packets decoded in
<a class="Xr">tcpdump(1)</a> output, one needs to specify the
<code class="Fl">-T</code> <var class="Ar">carp</var> option, otherwise
<a class="Xr">tcpdump(1)</a> will interpret them as VRRP packets:</p>
<div class="Bd Pp Bd-indent Li">
<pre>tcpdump -npi vlan0 -T carp</pre>
</div>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">tcpdump(1)</a>, <a class="Xr">inet(4)</a>,
<a class="Xr">pfsync(4)</a>, <a class="Xr">devd.conf(5)</a>,
<a class="Xr">rc.conf(5)</a>, <a class="Xr">ifconfig(8)</a>,
<a class="Xr">sysctl(8)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">carp</code> device first appeared in
<span class="Ux">OpenBSD 3.5</span>. The <code class="Nm">carp</code> device
was imported into <span class="Ux">FreeBSD 5.4</span>. In
<span class="Ux">FreeBSD 10.0</span>, <code class="Nm">carp</code> was
significantly rewritten, and is no longer a pseudo-interface.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">March 11, 2026</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
