Ubuntu Manpage: ucarp — Automatic IP failover

name
synopsis
description
options
examples
signals
author

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=/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

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, <j@ucarp.org>.

       This manual page was written by Eric Evans <eevans@debian.org> for the Debian system (but may be used  by
       others).   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 Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-
       licenses/GPL.

                                                                                                        UCARP(8)