ucarp(8)

💖 ucarp(8) — automatic IP failover 💖

okay bestie, sit down, hydrate, because we're about to talk about ucarp, and it's genuinely one of the most iconic little tools in the failover game. no cap. it lives in section 8 of the manual, it's the Automatic IP failover girlie, and she's about to eat. 🍓

---

✨ NAME ✨

ucarp — automatic IP failover 💅

---

🌈 SYNOPSIS 🌈

ucarp [-i, --interface=INTERFACE]  [-s, --srcip=IPADDRESS]
      [-m, --mcast=<ip>] [-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] [-D, --debug] [-z, --shutdown] [-B, --daemonize]
      [-f, --facility=FACILITY] [-x, --xparam PARAM] [-S, --ignoreifstate]
      [-M, --nomcast]

---

🦋 DESCRIPTION 🦋

so basically, ucarp lets a pair of hosts share common IP addresses, which means an address can automatically fail over from one machine to the other. it's giving "if one of us goes down, the other one steps up" energy, and honestly? iconic. 👑

it's a portable userland implementation of the secure and patent-free Common Address Redundancy Protocol, aka CARP — which is OpenBSD's alternative to VRRP. no patents, no drama, just vibes. ✨

⚠️ Warning: Maximum length of the password used must be 20 characters. that's the limit, bestie, do not test her. 💀

---

🎀 OPTIONS 🎀

• -i INTERFACE, --interface=INTERFACE — the network interface you're binding to. that's your home base. 🏠
• -s IPADDRESS, --srcip=IPADDRESS — the persistent source address (the real IP) that goes with this interface. the genuine article. 💖
• -m IPADDRESS, --mcast=IPADDRESS — the multicast group IP address. defaults to 224.0.0.18. 🫶
• -v VHID, --vhid=VHID — the id of the virtual server, and it's gotta be in the range [1-255]. ✨
• -p PASSWORD, --pass=PASSWORD — the shared password. it gets encrypted, so it is not sent in the clear. we love a secure queen. 🔐
• -o PASSFILE, --passfile=PASSFILE — file to read the shared password from. the file should have the password on its first line, periodt.
• -P, --preempt — turn on preemptive failover. this makes an instance of ucarp assume master status right immediately. main character energy, immediately. 👑
• -n, --neutral — do not run the downscript on startup when the initial state is backup. she's staying neutral, she's minding her business. 🧘
• -a IPADDRESS, --addr=IPADDRESS — the IP address of the virtual server. the shared one. the moment. ⭐
• -h, --help — display a brief summary of the command line options. for when you're lost bestie, no shame. 🙈
• -b SECONDS, --advbase=SECONDS — interval in seconds that advertisements will occur. defaults to 1 second. ticking like a clock. ⏰
• -k SKEW, --advskew=SKEW — advertisement skew, range [1-255], defaults to 0. yes, skew. she's a little off and that's the point. 💅
• -u COMMAND, --upscript=COMMAND — specifies the command to run after ucarp has successfully become master. the interface name gets passed as an argument. typically it's a script used to bring up the virtual address, log the result, add routes, clear arp cache entries, etc. the glow-up script. 🌸
• -d COMMAND, --downscript=COMMAND — specifies the command that is run after ucarp 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. the graceful exit. 💜
• -r RATIO, --deadratio=RATIO — the ratio the backup uses to figure out how long to wait for an unresponsive master before considering it dead. not me judging from afar. 💀
• -D, --debug — enable debug output. turn the lights on. 🔥
• -z, --shutdown — using this command causes the command specified by the -d argument to be invoked when ucarp shuts down. clean exits only. ✨
• -B, --daemonize — causes ucarp to detach from the terminal and run in the background as a daemon. she's independent, she doesn't need you watching. 🦋
• -f, --facility=FACILITY — set the syslog facility. defaults to daemon. 🎀
• -x, --xparam=PARAMETER — specify an extra parameter to be supplied to the up/down scripts. a lil something extra. 😌
• -S, --ignoreifstate — ignore unplugged network cables. this option is useful when ucarp 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. old school, still valid. 🌈

---

🧚 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.

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

The backup might be configured something like this.

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

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.

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

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).

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

---

💫 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. like handing over the aux cord, respectfully. 🎧

---

👑 AUTHOR 👑

Written by Frank Denis <j@pureftpd.org>. 💖

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). 🫶

---

and that's the whole page, bestie!! this was ucarp-1.5.2+git20192404.1a9aaf7, dated 08 Jan 2023, and she ate. no crumbs. mwah. 💅✨🎀