NAME

       ucarp - automatic IP failover

SYNOPSIS

       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]

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.

       Warning: Maximum length of the password used must be 20 characters.

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.

       -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.

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

       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).