.:. UCARP .:.
                         Documentation for version 1.2


           ------------------------ BLURB ------------------------


UCARP allows a couple of hosts to share common virtual IP addresses in order
to provide automatic failover. It is a portable userland implementation of the
secure and patent-free Common Address Redundancy Protocol (CARP, OpenBSD's
alternative to the patents-bloated VRRP).

Strong points of the CARP protocol are: very low overhead, cryptographically
signed messages, interoperability between different operating systems and no
need for any dedicated extra network link between redundant hosts.

Home page is http://www.ucarp.org/


        ------------------------ COMPILATION ------------------------


libpcap (http://www.tcpdump.org/) must be installed on your system, with
development files (headers).

Then, follow the boring traditional procedure:

./configure
make install-strip

For details, have a look at the INSTALL file.

The software has been successfully tested on Linux 2.4, Linux 2.6, MacOS X,
OpenBSD, MirBSD and NetBSD.


        ------------------------ REQUIREMENTS ------------------------


A couple of virtual hosts must be given:

- A shared virtual IP, which will be dynamically answered by one alive host.
Services that need high availability need to be assigned to that virtual IP.

- A real IP address for each host.

- A shared identifier for the virtual IP address, which is a number between 1
and 255.

- For each host : an advertisement time base and skew, which is the frequency
the host will tell the other one that it's still alive. By default, base is 1
and skew is 0, which basically means one advertisement a second. The protocol
is very light, a tiny packet every second won't have any noticeable impact on
your network.

- A shared password (that will never go plaintext to the network).

- A script to bring the virtual address up when a host becomes the master.

- Another script to bring the virtual address down when a host is no more the
master.


            ------------------------ USAGE ------------------------


The server will usually be installed as : /usr/local/sbin/ucarp
Everything is driven through command-line options.
In order to see the list of available options, try : /usr/local/sbin/ucarp -h

Better than a long technical discussion, here's a real-life setup example.

Your company has an internal mail relay whose IP address is 10.1.1.252. Every
user has configured his mail client with that host or IP address and the
service must always be up and running without reconfiguring mail clients in
case of a failure.

It's why you set up two mail servers hosts with an identical configuration.
Their real IP addresses are 10.1.1.1 and 10.1.1.2.
Let's see how to assign the same additionnal IP address (10.1.1.252) to both
servers, so that when one goes down, the other one goes up.

First, we will create a script that brings the virtual IP address up. Let's
save that file as /etc/vip-up.sh :

#! /bin/sh
/sbin/ip addr add 10.1.1.252/24 dev eth0

Now another script to bring it down, /etc/vip-down.sh :

#! /bin/sh
/sbin/ip addr del 10.1.1.252/24 dev eth0

Of course, anything can go in these scripts. For instance, you may want to add
routes, to add something to log files or to send mail. And last, but not
least, you can use a script that will connect to your switches and flush their
ARP cache. Some users reported that transitions were way faster when also
switching MAC addresses.
The interface name is passed as an argument to the called scripts, so feel
free to replace "eth0" with "$1" in the previous examples.

Don't forget to make those files executable :

chmod +x /etc/vip-up.sh /etc/vip-down.sh

Right. What we need now is an identifier for the virtual IP. Let's take "42".
And we also need a password. Let's take "love".

Now, on the first host (whoose real IP is 10.1.1.1), run :

/usr/local/sbin/ucarp -v 42 -p love -a 10.1.1.252 -s 10.1.1.1 &

On the second host, whose real IP is 10.1.1.2, run :

/usr/local/sbin/ucarp -v 42 -p love -a 10.1.1.252 -s 10.1.1.2 &

You should see that one of those hosts quickly becomes the master, and the
other one the backup. Related scripts are spawned on change.

Now unplug the master. After a few seconds, the other host becomes the new
master.

By changing the base (the -b switch) you can have a "preferred" master. The
lower the value is, the more likely it's going to be a master.

Please note that by default, and if everything's ok, a master will stay a
master as long as possible. If you want a "preferred" master to immediately
become a master even if another host is already the master:
- add the --preempt (or -P) switch to *all* hosts
- use a lower skew or a lower base for the "preferred" one.

When ucarp first runs, it starts as a backup and listens to the network to
determine if it should become the master. When it enters the backup state, it
normally runs the downscript. That can be useful to remove old temporary files
or clean up an interface that is in an unknown state. In some circumstances,
however, it is undesirable to run the downscript if the service was not
already up. In that case, use the --neutral (-n) switch for ucarp to not run
the downscript when it enters the backup state the first time. All changes
from the master state to the backup state after that will run the downscript.

--shutdown (-z) will run the downscript at exit, unless ucarp is already in
the backup state. 

The "dead ratio" (--deadratio=...) knob basically changes how long a backup
server will wait for an unresponsive master before considering it as dead, and
becoming the new master. In the original protocol, the ratio is 3. This is
also the default when this command-line switch is missing.

Notices are sent both to stderr/stdout and to the syslog daemon (with the
"daemon" facility) by default. stderr/stdout are bypassed if the daemon is
started in background (--daemonize). Facilities can be changed with the
--syslog switch. Use --syslog=none to disable syslog logging, for instance if
prefer using something like multilog.


        ------------------------ TRANSLATIONS ------------------------


UCARP can speak your native language through gettext / libintl.
If you want to translate the software, have a look at the po/ directory.
Copy the ucarp.pot file to <your locale name>.po and use software like Kbabel
or Emacs to update the file.
Better use use your local charset than UTF-8.


      ------------------------ DOWNLOADING UCARP ------------------------


UCARP home page is: http://www.ucarp.org/ .

UCARP mailing-list: http://www.ucarp.org/ml/


Thank you,