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