&dhucpackage; &dhsection;

&dhpackage;

Automatic IP failover

          &dhpackage;
          -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

&dhpackage; 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

&dhpackage; 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 &dhpackage; 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 &dhpackage; 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 &dhpackage; 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 &dhpackage; 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 &dhpackage; 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.

        &dhpackage; -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.

        &dhpackage; -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.

        &dhpackage; -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).

        &dhpackage; -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

&dhpackage; was written by Frank Denis, <j@ucarp.org>.

This manual page was written by &dhusername; <&dhemail;> 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.