ucarp - automatic IP failover
ucarp [-i, --interface=INTERFACE] [-s, --srcip=IPADDRESS]
[-m, --mcast=<ip>] [-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] [-D, --debug] [-z, --shutdown] [-B, --daemonize]
[-f, --facility=FACILITY] [-x, --xparam PARAM] [-S, --ignoreifstate]
[-M, --nomcast]
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.
Warning: Maximum length of the password used must be 20
characters.
- -i INTERFACE,
--interface=INTERFACE
- The network interface to bind to.
- -s IPADDRESS,
--srcip=IPADDRESS
- The persistent source address, (real IP), associated with this
interface.
- -m IPADDRESS,
--mcast=IPADDRESS
- Multicast group IP address (default 224.0.0.18).
- -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 upthe 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.
- -D,
--debug
- Enable debug output.
- -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=FACILITY
- Set the syslog facility, defaults to daemon.
- -x,
--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.
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=/etc/vip-up.sh --downscript=/etc/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=/etc/vip-up.sh --downscript=/etc/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 /etc/vip-up.sh -d /etc/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 /etc/vip-up.sh -d /etc/vip-down.sh -z
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.
Written by Frank Denis <j@pureftpd.org>.
This manual page was written by Guilherme de Paula Xavier Segundo
<guilherme.lnx@gmail.com> and Eric Evans <eevans@debian.org> for
the Debian project (but may be used by others).