ucarp/repos/community-x86_64/ucarp.8

   1 .TH "UCARP" "8"
   2 .SH "NAME"
   3 ucarp \(em Automatic IP failover
   4 .SH "SYNOPSIS"
   5 .PP
   6 \fBucarp\fR [\fB-i, \-\-interface=\fIINTERFACE\fR\fP]  [\fB-s, \-\-srcip=\fIIPADDRESS\fR\fP]
   7 .br
   8 [\fB-v, \-\-vhid=\fIVHID\fR\fP]  [\fB-p, \-\-pass=\fIPASSWORD\fR\fP]  [\fB-o, \-\-passfile=\fIPASSFILE\fR\fP]
   9 .br
  10 [\fB-P, \-\-preempt\fP]  [\fB-n, \-\-neutral\fP]  [\fB-a, \-\-addr=\fIIPADDR\fR\fP]  [\fB-h, \-\-help\fP]
  11 .br
  12 [\fB-b, \-\-advbase=\fISECS\fR\fP]  [\fB-k, \-\-advskew=\fISKEW\fR\fP]  [\fB-u, \-\-upscript=\fISCRIPT\fR\fP]
  13 .br
  14 [\fB-d, \-\-downscript=\fISCRIPT\fR\fP]  [\fB-r, \-\-deadratio=\fIRATIO\fR\fP]  [\fB-z, \-\-shutdown\fP]
  15 .br
  16 [\fB-B, \-\-daemonize\fP]  [\fB-f, \-\-facility=\fIFACILITY\fR\fP]  [\fB-x, \-\-xparam \fIPARAM\fR\fP]
  17 .br
  18 [\fB-S, \-\-ignoreifstate\fP]  [\fB-M, \-\-nomcast\fP]
  19 .SH "DESCRIPTION"
  20 .PP
  21 ucarp allows a pair of hosts to share common IP addresses in
  22 order to provide automatic failover of an address from one machine to
  23 another. It is a portable userland implementation of the secure and
  24 patent-free Common Address Redundancy Protocol, (CARP), OpenBSD's
  25 alternative to VRRP.
  26 .SH "OPTIONS"
  27 .PP
  28 ucarp supports the following command line options:
  29 .IP "\fB-i \fIINTERFACE\fR\fP\fB \-\-interface=\fIINTERFACE\fR\fP" 10
  30 The network interface to bind to.
  31 .IP "\fB-s \fIIPADDRESS\fR\fP\fB \-\-srcip=\fIIPADDRESS\fR\fP" 10
  32 The persistent source address, (real IP), associated with this
  33 interface.
  34 .IP "\fB-v \fIVHID\fR\fP\fB \-\-vhid=\fIVHID\fR\fP" 10
  35 The id of the virtual server [1-255].
  36 .IP "\fB-p \fIPASSWORD\fR\fP\fB \-\-pass=\fIPASSWORD\fR\fP" 10
  37 The shared password, (this gets encrypted and is not sent in the
  38 clear).
  39 .IP "\fB-o \fIPASSFILE\fR\fP\fB \-\-passfile=\fIPASSFILE\fR\fP" 10
  40 File to read the shared password from. The file specified
  41 should contain the password on the first line of the file.
  42 .IP "\fB-P \fP\fB\-\-preempt\fP" 10
  43 Turn on preemptive failover. This causes an instance of
  44 ucarp to assume master status right immediately.
  45 .IP "\fB-n \fP\fB\-\-neutral\fP" 10
  46 Do not run the downscript on startup when the
  47 initial state is backup.
  48 .IP "\fB-a \fIIPADDRESS\fR\fP\fB \-\-addr=\fIIPADDRESS\fR\fP" 10
  49 The IP address of the virtual server.
  50 .IP "\fB-h \fP\fB\-\-help\fP" 10
  51 Display a brief summary of the command line options.
  52 .IP "\fB-b \fISECONDS\fR\fP\fB \-\-advbase=\fISECONDS\fR\fP" 10
  53 Interval in seconds that advertisements will occur, (defaults
  54 to 1 second).
  55 .IP "\fB-k \fISKEW\fR\fP\fB \-\-advskew=\fISKEW\fR\fP" 10
  56 Advertisement skew [1-255], (defaults to 0).
  57 .IP "\fB-u \fICOMMAND\fR\fP\fB \-\-upscript=\fICOMMAND\fR\fP" 10
  58 Specifies the command to run after ucarp has successfully
  59 become master, the interface name gets passed as an argument.
  60 Typically a script used to bring up the virtual address, log the
  61 result, add routes, clear arp cache entries, etc.
  62 .IP "\fB-d \fICOMMAND\fR\fP\fB \-\-downscript=\fICOMMAND\fR\fP" 10
  63 Specifies the command that is run after ucarp has
  64 transitioned to the backup state, the interface name is passed
  65 as an argument. This is typically a script used to bring down
  66 the virtual interface, log the action, remove routes, etc.
  67 .IP "\fB-r \fIRATIO\fR\fP\fB \-\-deadratio=\fIRATIO\fR\fP" 10
  68 Ratio used by the backup to determine how long to wait for an
  69 unresponsive master before considering it dead.
  70 .IP "\fB-z\fP\fB \-\-shutdown\fP" 10
  71 Use of this command causes the command specified by the \-d
  72 argument to be invoked when ucarp shuts down.
  73 .IP "\fB-B\fP\fB \-\-daemonize\fP" 10
  74 Causes ucarp to detach from the terminal and run in the
  75 background as a daemon.
  76 .IP "\fB-f\fP\fB \-\-facility\fP" 10
  77 Set the syslog facility, defaults to daemon.
  78 .IP "\fB-x \fIPARAMETER\fR\fP\fB \-\-xparam=\fIPARAMETER\fR\fP" 10
  79 Specify an extra parameter to be supplied to the up/down
  80 scripts.
  81 .IP "\fB-S\fP\fB \-\-ignoreifstate\fP" 10
  82 Ignore unplugged network cables. This option is useful when
  83 ucarp nodes are connected with a crossover cable. Without
  84 this option the master will transition to backup when the other
  85 node is powered down, as it no longer has a link (NO-CARRIER).
  86
  87 .IP "\fB-M\fP\fB \-\-nomcast\fP" 10
  88 Use broadcast instead of multicast advertisements.
  89 .SH "EXAMPLES"
  90 .PP
  91 A host with a real IP of 10.1.1.10 configured to be the master
  92 in a preemptive configuration with a virtual IP of 10.1.1.252.
  93 .PP
  94 .nf
  95 \fB    \fPucarp \-i eth0 \-s 10.1.1.10 \-v 10 \-p secret \-a 10.1.1.252 \\
  96 \fB    \fP\-\-upscript=/usr/local/sbin/vip-up.sh \-\-downscript=/usr/local/sbin/vip-down.sh \-P
  97 .fi
  98 .PP
  99 The backup might be configured something like this.
 100 .PP
 101 .nf
 102 \fB    \fPucarp \-i eth0 \-s 10.1.1.11 \-v 10 \-p secret \-a 10.1.1.252 \\
 103 \fB    \fP\-\-upscript=/usr/local/sbin/vip-up.sh \-\-downscript=/usr/local/sbin/vip-down.sh
 104 .fi
 105 .PP
 106 A machine with a real IP of 192.168.1.19 is the preferred master for
 107 a virtual IP of 10.1.12.7, broadcasts are sent every 5 seconds.
 108 .PP
 109 .nf
 110 \fB    \fPucarp \-b 5 \-s 192.168.1.19 \-v 27 \-p badpass \-a 10.1.12.7 \\
 111 \fB    \fP-u /usr/local/sbin/vip-up.sh \-d /usr/local/sbin/vip-down.sh \-z
 112 .fi
 113 .PP
 114 The hot standby with an IP of 192.168.1.20 uses the following
 115 command, (note the advskew of 50 putting it at a disadvantage and making
 116 the first machine preferred).
 117 .PP
 118 .nf
 119 \fB    \fPucarp \-b 5 \-k 50 \-s 192.168.1.20 \-v 27 \-p badpass \-a 10.1.12.7 \\
 120 \fB    \fP-u /usr/local/sbin/vip-up.sh \-d /usr/local/sbin/vip-down.sh \-z
 121 .fi
 122 .SH "SIGNALS"
 123 .PP
 124 Sending the ucarp process a SIGUSR1 will have it log a status
 125 line to syslog, eg "Sep 13 12:59:56 localhost ucarp[2654]: [INFO]
 126 MASTER on eth0 id 1" or "Sep 13 13:00:25 localhost ucarp[2644]: [INFO]
 127 BACKUP on eth0 id 1"
 128 .PP
 129 Sending the ucarp process a SIGUSR2 will cause it to demote itself
 130 from master to backup, pause 3 seconds, then proceed as usual to listen
 131 for other masters, and promote itself if necessary. This could be useful
 132 if you wish another node to take over master.
 133
 134 .SH "AUTHOR"
 135 .PP
 136 ucarp was written by Frank Denis, <j@ucarp.org>.
 137 .PP
 138 This manual page was written by Eric Evans <eevans@debian.org>
 139 for \fBDebian\fP and adapted to \fBArchlinux\fP
 140 by Sébastien Luttringer <seblu@archlinux.org>.  Permission is
 141 granted to copy, distribute and/or modify this document under
 142 the terms of the GNU General Public License, Version 2 or any
 143 later version published by the Free Software Foundation.
 144
 145 .PP
 146 On Archlinux systems, the complete text of the GNU General Public
 147 License can be found in /usr/share/licenses/common/GPL.