--- name: "ucarp" section: "8" platform: "linux" package: "ucarp" version: "1.5.2-9" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ucarp" --- # ucarp(8) Automatic IP failover ## NAME ucarp — Automatic IP failover ## SYNOPSIS **ucarp** \[**-i, --interface=***INTERFACE\] \[***-s, --srcip=***IPADDRESS\]* \ *\[***-v, --vhid=***VHID\] \[***-p, --pass=***PASSWORD\] \[***-o, --passfile=***PASSFILE\]* \ *\[***-P, --preempt***\] \[***-n, --neutral***\] \[***-a, --addr=***IPADDR\] \[***-h, --help***\]* \ *\[***-b, --advbase=***SECS\] \[***-k, --advskew=***SKEW\] \[***-u, --upscript=***SCRIPT\]* \ *\[***-d, --downscript=***SCRIPT\] \[***-r, --deadratio=***RATIO\] \[***-z, --shutdown***\]* \ *\[***-B, --daemonize***\] \[***-f, --facility=***FACILITY\] \[***-x, --xparam** *PARAM\]* \ *\[***-S, --ignoreifstate***\] \[***-M, --nomcast***\]* ## DESCRIPTION *ucarp allows a pair of hosts to share common IP addresses in* *order to provide automatic failover of an address from one machine to* *another. It is a portable userland implementation of the secure and* *patent-free Common Address Redundancy Protocol, (CARP), OpenBSD's* *alternative to VRRP.* ## OPTIONS *ucarp supports the following command line options:* - **-i** *INTERFACE* **--interface=***INTERFACE* *The network interface to bind to.* - **-s** *IPADDRESS* **--srcip=***IPADDRESS* *The persistent source address, (real IP), associated with this* *interface.* - **-v** *VHID* **--vhid=***VHID* *The id of the virtual server \[1-255\].* - **-p** *PASSWORD* **--pass=***PASSWORD* *The shared password, (this gets encrypted and is not sent in the* *clear).* - **-o** *PASSFILE* **--passfile=***PASSFILE* *File to read the shared password from. The file specified* *should contain the password on the first line of the file.* - **-P --preempt** *Turn on preemptive failover. This causes an instance of* *ucarp to assume master status right immediately.* - **-n --neutral** *Do not run the downscript on startup when the* *initial state is backup.* - **-a** *IPADDRESS* **--addr=***IPADDRESS* *The IP address of the virtual server.* - **-h --help** *Display a brief summary of the command line options.* - **-b** *SECONDS* **--advbase=***SECONDS* *Interval in seconds that advertisements will occur, (defaults* *to 1 second).* - **-k** *SKEW* **--advskew=***SKEW* *Advertisement skew \[1-255\], (defaults to 0).* - **-u** *COMMAND* **--upscript=***COMMAND* *Specifies the command to run after ucarp has successfully* *become master, the interface name gets passed as an argument.* *Typically a script used to bring up the virtual address, log the* *result, add routes, clear arp cache entries, etc.* - **-d** *COMMAND* **--downscript=***COMMAND* *Specifies the command that is run after ucarp has* *transitioned to the backup state, the interface name is passed* *as an argument. This is typically a script used to bring down* *the virtual interface, log the action, remove routes, etc.* - **-r** *RATIO* **--deadratio=***RATIO* *Ratio used by the backup to determine how long to wait for an* *unresponsive master before considering it dead.* - **-z --shutdown** *Use of this command causes the command specified by the -d* *argument to be invoked when ucarp shuts down.* - **-B --daemonize** *Causes ucarp to detach from the terminal and run in the* *background as a daemon.* - **-f --facility** *Set the syslog facility, defaults to daemon.* - **-x** *PARAMETER* **--xparam=***PARAMETER* *Specify an extra parameter to be supplied to the up/down* *scripts.* - **-S --ignoreifstate** *Ignore unplugged network cables. This option is useful when* *ucarp nodes are connected with a crossover cable. Without* *this option the master will transition to backup when the other* *node is powered down, as it no longer has a link (NO-CARRIER).* - **-M --nomcast** *Use broadcast instead of multicast advertisements.* ## EXAMPLES *A host with a real IP of 10.1.1.10 configured to be the master* *in a preemptive configuration with a virtual IP of 10.1.1.252.* ``` ucarp -i eth0 -s 10.1.1.10 -v 10 -p secret -a 10.1.1.252 \ --upscript=/usr/local/sbin/vip-up.sh --downscript=/usr/local/sbin/vip-down.sh -P ``` *The backup might be configured something like this.* ``` ucarp -i eth0 -s 10.1.1.11 -v 10 -p secret -a 10.1.1.252 \ --upscript=/usr/local/sbin/vip-up.sh --downscript=/usr/local/sbin/vip-down.sh ``` *A machine with a real IP of 192.168.1.19 is the preferred master for* *a virtual IP of 10.1.12.7, broadcasts are sent every 5 seconds.* ``` ucarp -b 5 -s 192.168.1.19 -v 27 -p badpass -a 10.1.12.7 \ -u /usr/local/sbin/vip-up.sh -d /usr/local/sbin/vip-down.sh -z ``` *The hot standby with an IP of 192.168.1.20 uses the following* *command, (note the advskew of 50 putting it at a disadvantage and making* *the first machine preferred).* ``` ucarp -b 5 -k 50 -s 192.168.1.20 -v 27 -p badpass -a 10.1.12.7 \ -u /usr/local/sbin/vip-up.sh -d /usr/local/sbin/vip-down.sh -z ``` ## SIGNALS *Sending the ucarp process a SIGUSR1 will have it log a status* *line to syslog, eg "Sep 13 12:59:56 localhost ucarp\[2654\]: \[INFO\]* *MASTER on eth0 id 1" or "Sep 13 13:00:25 localhost ucarp\[2644\]: \[INFO\]* *BACKUP on eth0 id 1"* *Sending the ucarp process a SIGUSR2 will cause it to demote itself* *from master to backup, pause 3 seconds, then proceed as usual to listen* *for other masters, and promote itself if necessary. This could be useful* *if you wish another node to take over master.* ## AUTHOR *ucarp was written by Frank Denis, \.* *This manual page was written by Eric Evans \* *for* **Debian** *and adapted to* **Archlinux** *by Sébastien Luttringer \. Permission is* *granted to copy, distribute and/or modify this document under* *the terms of the GNU General Public License, Version 2 or any* *later version published by the Free Software Foundation.* *On Archlinux systems, the complete text of the GNU General Public* *License can be found in /usr/share/licenses/common/GPL.*