1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
.\" Text automatically generated by txt2man
.TH ucarp 8 "08 Jan 2023" "ucarp-1.5.2+git20192404.1a9aaf7" "Automatic IP failover"
.SH NAME
\fBucarp \fP- automatic IP failover
\fB
.SH SYNOPSIS
.nf
.fam C
\fBucarp\fP [\fB-i\fP, \fB--interface\fP=INTERFACE] [\fB-s\fP, \fB--srcip\fP=IPADDRESS]
[\fB-m\fP, \fB--mcast\fP=<ip>] [\fB-v\fP, \fB--vhid\fP=VHID] [\fB-p\fP, \fB--pass\fP=PASSWORD]
[\fB-o\fP, \fB--passfile\fP=PASSFILE] [\fB-P\fP, \fB--preempt\fP] [\fB-n\fP, \fB--neutral\fP]
[\fB-a\fP, \fB--addr\fP=IPADDR] [\fB-h\fP, \fB--help\fP] [\fB-b\fP, \fB--advbase\fP=SECS]
[\fB-k\fP, \fB--advskew\fP=SKEW] [\fB-u\fP, \fB--upscript\fP=SCRIPT] [\fB-d\fP, \fB--downscript\fP=SCRIPT]
[\fB-r\fP, \fB--deadratio\fP=RATIO] [\fB-D\fP, \fB--debug\fP] [\fB-z\fP, \fB--shutdown\fP] [\fB-B\fP, \fB--daemonize\fP]
[\fB-f\fP, \fB--facility\fP=FACILITY] [\fB-x\fP, \fB--xparam\fP \fIPARAM\fP] [\fB-S\fP, \fB--ignoreifstate\fP]
[\fB-M\fP, \fB--nomcast\fP]
.fam T
.fi
.fam T
.fi
.SH DESCRIPTION
\fBucarp\fP 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.
.PP
Warning: Maximum length of the password used must be 20 characters.
.SH OPTIONS
.TP
.B
\fB-i\fP INTERFACE, \fB--interface\fP=INTERFACE
The network interface to bind to.
.TP
.B
\fB-s\fP IPADDRESS, \fB--srcip\fP=IPADDRESS
The persistent source address, (real IP), associated with this interface.
.TP
.B
\fB-m\fP IPADDRESS, \fB--mcast\fP=IPADDRESS
Multicast group IP address (default 224.0.0.18).
.TP
.B
\fB-v\fP VHID, \fB--vhid\fP=VHID
The id of the virtual server [1-255].
.TP
.B
\fB-p\fP PASSWORD, \fB--pass\fP=PASSWORD
The shared password, (this gets encrypted and is not sent in the clear).
.TP
.B
\fB-o\fP PASSFILE, \fB--passfile\fP=PASSFILE
File to read the shared password from. The file specified should contain the password on the first line of the file.
.TP
.B
\fB-P\fP, \fB--preempt\fP
Turn on preemptive failover. This causes an instance of \fBucarp\fP to assume master status right immediately.
.TP
.B
\fB-n\fP, \fB--neutral\fP
Do not run the downscript on startup when the initial state is backup.
.TP
.B
\fB-a\fP IPADDRESS, \fB--addr\fP=IPADDRESS
The IP address of the virtual server.
.TP
.B
\fB-h\fP, \fB--help\fP
Display a brief summary of the command line options.
.TP
.B
\fB-b\fP SECONDS, \fB--advbase\fP=SECONDS
Interval in seconds that advertisements will occur, (defaults to 1 second).
.TP
.B
\fB-k\fP SKEW, \fB--advskew\fP=SKEW
Advertisement skew [1-255], (defaults to 0).
.TP
.B
\fB-u\fP COMMAND \fB--upscript\fP=COMMAND
Specifies the command to run after \fBucarp\fP 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.
.TP
.B
\fB-d\fP COMMAND, \fB--downscript\fP=COMMAND
Specifies the command that is run after \fBucarp\fP 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.
.TP
.B
\fB-r\fP RATIO, \fB--deadratio\fP=RATIO
Ratio used by the backup to determine how long to wait for an unresponsive master before considering it dead.
.TP
.B
\fB-D\fP, \fB--debug\fP
Enable debug output.
.TP
.B
\fB-z\fP, \fB--shutdown\fP
Use of this command causes the command specified by the \fB-d\fP argument to be invoked when \fBucarp\fP shuts down.
.TP
.B
\fB-B\fP, \fB--daemonize\fP
Causes \fBucarp\fP to detach from the terminal and run in the background as a daemon.
.TP
.B
\fB-f\fP, \fB--facility\fP=FACILITY
Set the syslog facility, defaults to daemon.
.TP
.B
\fB-x\fP, \fB--xparam\fP=PARAMETER
Specify an extra parameter to be supplied to the up/down scripts.
.TP
.B
\fB-S\fP, \fB--ignoreifstate\fP
Ignore unplugged network cables. This option is useful when \fBucarp\fP 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).
.TP
.B
\fB-M\fP, \fB--nomcast\fP
Use broadcast instead of multicast advertisements.
.SH 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.
.PP
.nf
.fam C
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
.fam T
.fi
The backup might be configured something like this.
.PP
.nf
.fam C
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
.fam T
.fi
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.
.PP
.nf
.fam C
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
.fam T
.fi
.TP
.B
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).
.PP
.nf
.fam C
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
.fam T
.fi
.SH SIGNALS
Sending the \fBucarp\fP process a SIGUSR1 will have it log a status line to syslog, eg "Sep 13 12:59:56 localhost \fBucarp\fP[2654]: [INFO] MASTER on eth0 id 1" or "Sep 13 13:00:25 localhost \fBucarp\fP[2644]: [INFO] BACKUP on eth0 id 1"
.PP
Sending the \fBucarp\fP 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.
.SH AUTHOR
Written by Frank Denis <j@pureftpd.org>.
.PP
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).
|
