<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@

    
     The docbook-to-man binary is found in the docbook-to-man package.
     Please remember that if you create the nroff version in one of the
     debian/rules file targets (such as build), you will need to include
     docbook-to-man in your Build-Depends control field.

  -->

  <!ENTITY dhfirstname "<firstname>Eric</firstname>">
  <!ENTITY dhsurname   "<surname>Evans</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>July 26, 2011</date>">
  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
  <!ENTITY dhemail     "<email>eevans@debian.org</email>">
  <!ENTITY dhusername  "Eric Evans">
  <!ENTITY dhucpackage "<refentrytitle>UCARP</refentrytitle>">
  <!ENTITY dhpackage   "ucarp">

  <!ENTITY debian      "<productname>Debian</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2003</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  
  <refnamediv>
      <refname>&dhpackage;</refname>
      <refpurpose>Automatic IP failover</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>&dhpackage;</command>
      <arg><option>-i, --interface=<replaceable>INTERFACE</replaceable></option></arg>
      <arg><option>-s, --srcip=<replaceable>IPADDRESS</replaceable></option></arg>
      <sbr>
      <arg><option>-v, --vhid=<replaceable>VHID</replaceable></option></arg>
      <arg><option>-p, --pass=<replaceable>PASSWORD</replaceable></option></arg>
      <arg><option>-o, --passfile=<replaceable>PASSFILE</replaceable></option></arg>
      <sbr>
      <arg><option>-P, --preempt</option></arg>
      <arg><option>-n, --neutral</option></arg>
      <arg><option>-a, --addr=<replaceable>IPADDR</replaceable></option></arg>
      <arg><option>-h, --help</option></arg>
      <sbr>
      <arg><option>-b, --advbase=<replaceable>SECS</replaceable></option></arg>
      <arg><option>-k, --advskew=<replaceable>SKEW</replaceable></option></arg>
      <arg><option>-u, --upscript=<replaceable>SCRIPT</replaceable></option></arg>
      <sbr>
      <arg><option>-d, --downscript=<replaceable>SCRIPT</replaceable></option></arg>
      <arg><option>-r, --deadratio=<replaceable>RATIO</replaceable></option></arg>
      <arg><option>-z, --shutdown</option></arg>
      <sbr>
      <arg><option>-B, --daemonize</option></arg>
      <arg><option>-f, --facility=<replaceable>FACILITY</replaceable></option></arg>
      <arg><option>-x, --xparam <replaceable>PARAM</replaceable</option></arg>
      <sbr>
      <arg><option>-S, --ignoreifstate</option></arg>
      <arg><option>-M, --nomcast</option></arg>
      </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>DESCRIPTION</title>

    <para>&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.</para>
  </refsect1>

  <refsect1>
    <title>OPTIONS</title>

    <para>&dhpackage; supports the following command line options:</para>

    <variablelist>
      <varlistentry>
        <term><option>-i <replaceable>INTERFACE</replaceable></option><option> --interface=<replaceable>INTERFACE</replaceable></option></term>
        <listitem><para>The network interface to bind to.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-s <replaceable>IPADDRESS</replaceable></option><option> --srcip=<replaceable>IPADDRESS</replaceable></option></term>
        <listitem>
          <para>The persistent source address, (real IP), associated with this
          interface.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v <replaceable>VHID</replaceable></option><option> --vhid=<replaceable>VHID</replaceable></option></term>
        <listitem>
          <para>The id of the virtual server [1-255].</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-p <replaceable>PASSWORD</replaceable></option><option> --pass=<replaceable>PASSWORD</replaceable></option></term>
        <listitem>
          <para>The shared password, (this gets encrypted and is not sent in the
          clear).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-o <replaceable>PASSFILE</replaceable></option><option> --passfile=<replaceable>PASSFILE</replaceable></option></term>
        <listitem>
          <para>File to read the shared password from. The file specified
           should contain the password on the first line of the file.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-P </option><option>--preempt</option></term>
        <listitem>
          <para>Turn on preemptive failover. This causes an instance of 
          &dhpackage; to assume master status right immediately.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-n </option><option>--neutral</option></term>
        <listitem>
            <para>Do not run the downscript on startup when the 
            initial state is backup.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-a <replaceable>IPADDRESS</replaceable></option><option> --addr=<replaceable>IPADDRESS</replaceable></option></term>
        <listitem>
          <para>The IP address of the virtual server.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-h </option><option>--help</option></term>
        <listitem>
            <para>Display a brief summary of the command line options.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-b <replaceable>SECONDS</replaceable></option><option> --advbase=<replaceable>SECONDS</replaceable></option></term>
        <listitem>
          <para>Interval in seconds that advertisements will occur, (defaults 
          to 1 second).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-k <replaceable>SKEW</replaceable></option><option> --advskew=<replaceable>SKEW</replaceable></option></term>
        <listitem>
          <para>Advertisement skew [1-255], (defaults to 0).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-u <replaceable>COMMAND</replaceable></option><option> --upscript=<replaceable>COMMAND</replaceable></option></term>
        <listitem>
          <para>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.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-d <replaceable>COMMAND</replaceable></option><option> --downscript=<replaceable>COMMAND</replaceable></option></term>
        <listitem>
          <para>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.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-r <replaceable>RATIO</replaceable></option><option> --deadratio=<replaceable>RATIO</replaceable></option></term>
        <listitem>
          <para>Ratio used by the backup to determine how long to wait for an
          unresponsive master before considering it dead.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-z</option><option> --shutdown</option></term>
        <listitem>
          <para>Use of this command causes the command specified by the -d 
          argument to be invoked when ucarp shuts down.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-B</option><option> --daemonize</option></term>
        <listitem>
          <para>Causes &dhpackage; to detach from the terminal and run in the
          background as a daemon.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-f</option><option> --facility</option></term>
        <listitem>
          <para>Set the syslog facility, defaults to daemon.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-x <replaceable>PARAMETER</replaceable></option><option> --xparam=<replaceable>PARAMETER</replaceable></option></term>
        <listitem>
          <para>Specify an extra parameter to be supplied to the up/down
          scripts.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-S</option><option> --ignoreifstate</option></term>
        <listitem>
          <para>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).
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-M</option><option> --nomcast</option></term>
        <listitem>
          <para>Use broadcast instead of multicast advertisements.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>EXAMPLES</title>
    <para>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.</para>
    <synopsis><literal>    </literal>&dhpackage; -i eth0 -s 10.1.1.10 -v 10 -p secret -a 10.1.1.252 \\
    <literal>    </literal>--upscript=/etc/vip-up.sh --downscript=/etc/vip-down.sh -P</synopsis>
    
    <para>The backup might be configured something like this.</para>
    <synopsis><literal>    </literal>&dhpackage; -i eth0 -s 10.1.1.11 -v 10 -p secret -a 10.1.1.252 \\
    <literal>    </literal>--upscript=/etc/vip-up.sh --downscript=/etc/vip-down.sh</synopsis>

    <para>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.</para>
    <synopsis><literal>    </literal>&dhpackage; -b 5 -s 192.168.1.19 -v 27 -p badpass -a 10.1.12.7 \\
    <literal>    </literal>-u /etc/vip-up.sh -d /etc/vip-down.sh -z</synopsis>

    <para>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).</para>
    <synopsis><literal>    </literal>&dhpackage; -b 5 -k 50 -s 192.168.1.20 -v 27 -p badpass -a 10.1.12.7 \\
    <literal>    </literal>-u /etc/vip-up.sh -d /etc/vip-down.sh -z</synopsis>
  </refsect1>

  <refsect1>
    <title>SIGNALS</title>
    <para>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"</para>
    <para>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.
    </para>

  </refsect1>

  <refsect1>
    <title>AUTHOR</title>
    <para>&dhpackage; was written by Frank Denis, &lt;j@ucarp.org&gt;.</para>

    <para>This manual page was written by &dhusername; &lt;&dhemail;&gt;
    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.
    </para>
    <para>On Debian systems, the complete text of the GNU General Public
    License can be found in /usr/share/common-licenses/GPL.
    </para>
  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->


