ucarp8

Usage

Overview

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.