KEEPALIVED(8)

🎀 NAME 🎀

keepalived — the load-balancing and high-availability service, bestie. This is the System Manager's Manual page, section 8, and she is THAT girl. 💅

---

✨ SYNOPSIS ✨

keepalived [-f|--use-file=FILE] [-P|--vrrp] [-C|--check] [-B|--no_bfd]
[--all] [-l|--log-console] [-D|--log-detail]
[-S|--log-facility={0-7|local{0-7}|user|daemon}] [-g|--log-file=FILE]
[--flush-log-file] [-G|--no-syslog] [-X|--release-vips]
[-V|--dont-release-vrrp] [-I|--dont-release-ipvs] [-R|--dont-respawn]
[-n|--dont-fork] [-d|--dump-conf] [-p|--pid=FILE] [-r|--vrrp_pid=FILE]
[-T|--genhash] [-c|--checkers_pid=FILE] [-a|--address-monitoring]
[-b|--bfd_pid=FILE] [-s|--namespace=NAME] [-e|--all-config]
[-i|--config-id id] [-x|--snmp] [-A|--snmp-agent-socket=FILE]
[-u|--umask=NUMBER] [-m|--core-dump] [-M|--core-dump-pattern[=PATTERN]]
[--signum=SIGFUNC] [-t|--config-test[=FILE]] [--perf[={all|run|end}]]
[--debug[=debug-options]] [--no-mem-check] [--ignore-sigint]
[-v|--version] [-h|--help]

Like, yes, that's a lot of flags. She's high-maintenance and we love that for her. 🫶

---

🌸 DESCRIPTION 🌸

So, keepalived hands you simple and robust facilities for load-balancing and high-availability. No cap.

The load-balancing framework? It rides on the well-known and widely used Linux Virtual Server (IPVS) kernel module, which is out here doing Layer4 load-balancing. Queen behavior.

Then keepalived implements a whole set of checkers to dynamically and adaptively maintain and manage a load-balanced server pool according to their health. Vibe check, but for servers. 💖

And on top of that, keepalived implements the VRRPv2 and VRRPv3 protocols to achieve high-availability with director failover. Periodt.

---

💅 OPTIONS 💅

Okay so here's the whole menu, bestie. Every single one. Buckle up. 🎀

• -f, --use-file=FILE — use the configuration file you specify. The default configuration file is /etc/keepalived/keepalived.conf.
• -P, --vrrp — only run the VRRP subsystem. Obsessed with this one if your configs don't use the IPVS load balancer.
• -C, --check — only run the healthcheck subsystem. Perfect when you're using the IPVS load balancer with a single director and there's no failover happening.
• -B, --no_bfd — don't run the BFD subsystem. Not today. 🙈
• --all — run all the subsystems, even if they have no configuration. All of them. Every one.
• -l, --log-console — log messages to the local console. The default behavior is to log messages to syslog.
• -D, --log-detail — detailed log messages. Give me the lore.
• -S, --log-facility={0-7|local{0-7}|user|daemon} — set the syslog facility to LOG_LOCAL[0-7], LOG_USER or LOG_DAEMON. The default syslog facility is LOG_DAEMON.
• -g, --log-file=FILE — write log entries to FILE. Here's the cute detail: FILE will have _vrrp, _healthcheckers, and _bfd inserted before the last . in FILE for the log output for those processes. It's giving organized. ✨
• --flush-log-file — if you're using the -g option, the log file stream will be flushed after each write. Every. Single. Write.
• -G, --no-syslog — do not write log entries to syslog. This can be useful if the rate of writing log entries is sufficiently high that syslog will rate limit them, and the -g option is used instead. Basically: syslog said "too much", so you go direct. 💀
• -X, --release-vips — drop VIP on transition from signal.
• -V, --dont-release-vrrp — don't remove VRRP VIPs and VROUTEs on daemon stop. The default behavior is to remove all VIPs and VROUTEs when keepalived exits.
• -I, --dont-release-ipvs — don't remove IPVS topology on daemon stop. The default behavior it to remove all entries from the IPVS virtual server table when keepalived exits.
• -R, --dont-respawn — don't respawn child processes. The default behavior is to restart the VRRP and checker processes if either process exits.
• -n, --dont-fork — don't fork the daemon process. This option will cause keepalived to run in the foreground. Main character stays visible. 👑
• -d, --dump-conf — dump the configuration data.
• -p, --pid=FILE — use the specified pidfile for the parent keepalived process. The default pidfile for keepalived is /run/keepalived.pid, unless a network namespace is being used. See NAMESPACES below for more details.
• -r, --vrrp_pid=FILE — use the specified pidfile for the VRRP child process. The default pidfile for the VRRP child process is /run/keepalived_vrrp.pid, unless a network namespace is being used.
• -T, --genhash — enter genhash utility mode. Previous versions of keepalived were shipped with a dedicated genhash utility. genhash is now part of the mainline code. We keep compatibility with previous genhash utility command line option. For more information please refer to the genhash(1) manpage.
• -c, --checkers_pid=FILE — use the specified pidfile for checkers child process. The default pidfile for the checker child process is /run/keepalived_checkers.pid unless a network namespace is being used.
• -a, --address-monitoring — log all address additions/deletions reported by netlink. All of them. We're watching. 👀
• -b, --bfd_pid=FILE — use the specified pidfile for the BFD child process. The default pidfile for the BFD child process is /run/keepalived_bfd.pid unless a network namespace is being used.
• -s, --namespace=NAME — run keepalived in network namespace NAME. See NAMESPACES below for more details.
• -e, --all-config — don't load if any configuration file is missing or cannot be read. If even one is missing, it's a no. 🚫
• -i, --config-id ID — use configuration id ID, for conditional configuration (defaults to hostname without the domain name).
• -x, --snmp — enable the SNMP subsystem.
• -A, --snmp-agent-socket=FILE — use the specified socket for connection to SNMP master agent.
• -u, --umask=NUMBER — the umask specified in the usual numeric way — see man umask(2).
• -m, --core-dump — override the RLIMIT_CORE hard and soft limits to enable keepalived to produce a coredump in the event of a segfault or other failure. This is most useful if keepalived has been built with 'make debug'. Core dumps will be created in /, unless keepalived is run with the --dont-fork option, in which case they will be created in the directory from which keepalived was run, or they will be created in the directory of a configuraton file if the fault occurs while reading the file.
• -M, --core-dump-pattern[=PATTERN] — sets option --core-dump, and also updates /proc/sys/kernel/core_pattern to the pattern specified, or 'core' if none specified. Provided the parent process doesn't terminate abnormally, it will restore /proc/sys/kernel/core_pattern to its original value on exit.

⚠️ Note: this will also affect any other process producing a core dump while keepalived is running. She's not just touching her own stuff, bestie. Be aware. 😭

• --signum=PATTERN — returns the signal number to use for STOP, RELOAD, DATA, STATS, STATS_CLEAR, JSON and TDATA. For example, to stop keepalived running, execute:

kill -s $(keepalived --signum=STOP) $(cat /run/keepalived.pid)

• -t, --config-test[=FILE] — keepalived will check the configuration file and exit with non-zero exit status if there are errors in the configuration, otherwise it exits with exit status 0 (see Exit status below for details).

Rather that writing to syslog, it will write diagnostic messages to stderr unless file is specified, in which case it will write to the file.

• --perf[={all|run|end}] — record perf data for the vrrp process. Data will be written to /perf_vrrp.data. The data recorded is for use with the perf tool.
• --no-mem-check — disable malloc() etc mem-checks if they have been compiled into keepalived.
• --ignore-sigint — disable SIGINT handling (defaults to terminating keepalived). This is needed for running keepalived under GDB. GDB girlies, this one's for you. 🫶
• --debug[=debug-options]] — enables debug options if they have been compiled into keepalived. debug-options is made up of a sequence of strings of the form Ulll.

The upper case letter specifies the debug option, and the lower case letters specify for which processes the option is to be enabled.

If a debug option is not followed by any lower case letters, the debug option is enabled for all processes.

The characters to identify the processes are:

• p — Parent process
• b — BFD process
• c — Checker process
• v — VRRP process

The characters used to identify the debug options are:

• D — Epoll thread dump
• E — Epoll debug
• F — VRRP fd debug
• N — Netlink timers
• P — Network timestamp
• X — Regex timers
• M — Email alert debug
• T — Timer debug
• S — TSM debug
• R — Regex debug
• B — Smtp connect debug
• U — Checksum diagnostics
• O — Track process debug
• A — Track process debug with extra detail
• C — Parser (config) debug
• H — Checker debug
• Z — Memory alloc/free error debug
• G — VRRP recvmsg() debug
• J — VRRP recvmsg() log rx data
• V — Script debugging
• K — Dump keywords

Example: --debug=DvEcvNR

• -v, --version — display the version and exit.
• -h, --help — display this help message and exit.

🔥 Exit status 🔥

Because knowing why it bailed is the whole point:

• 0 — if OK ✨
• 1 — if unable to malloc memory
• 2 — if cannot initialise subsystems
• 3 — if running with --config-test and configuration cannot be run
• 4 — if running with --config-test and there are configuration errors but keepalived will run after modifying the configuration
• 5 — if running with --config-test and script security hasn't been enabled but scripts are configured.

---

🦋 NAMESPACES 🦋

So keepalived can be run in a network namespace (see keepalived.conf(5) for configuration details). When run in a network namespace, a local mount namespace is also created, and /run/keepalived/keepalived_NamespaceName is mounted on /run/keepalived.

By default, pid files with the usual default names are then created in /run/keepalived from the perspective of a process in the mount namespace, and they will be visible in /run/keepalived/keepalived_NamespaceName for a process running in the default mount namespace. It's giving nested realities, iykyk. 🌈

💌 SIGNALS 💌

okay bestie so keepalived reacts to a whole set of signals. You can yeet a signal at the parent keepalived process like this:

kill -SIGNAL $(cat /run/keepalived.pid)

or, lowkey the better way:

kill -s $(keepalived --signum=SIGFUNC) $(cat /run/keepalived.pid)

heads up though — if you go with the first option, you gotta swap out -SIGNAL for the actual signal you're trying to send, like HUP. So it turns into this:

kill -HUP $(cat /run/keepalived.pid)

✨ Important vibe check: signals other than for STOP, RELOAD, DATA and STATS may change depending on the kernel, and also on what functionality got included in your build of keepalived based on the build options used. So like, ymmv bestie. 🙈

---

• HUP or SIGFUNC=RELOAD — this makes keepalived close down all its interfaces, reload its configuration, and start up fresh with the new config. Slay. 💅

⚠️ Note: if a virtual_ipaddress, virtual_route or virtual_rule is being moved from one VRRP instance to another one, you're gonna need two reloads — the first one to remove the virtual ipaddress/route/rule, and the second reload to add it to the VRRP instance it's now supposed to be configured on. If you skip this, the ipaddress/route/rule might not get configured on the new instance at all when both the old and new instances are in master state. 😭 Note2: usually it works fine with a single reload, though, if either of the VRRP instances isn't in MASTER state, or if the VRRP instance the ipaddress/route/rule is being added to comes later in the original configuration file than the instance it's being removed from. 🫶 Note3 (real one): if a configuration is running with SNMP enabled, and then you do a reload with a configuration that does not enable SNMP, it is not possible to subsequently re-enable SNMP. The reason for this is not currently understood. (genuinely nobody knows, it's giving mystery 💀)

• TERM, INT or SIGFUNC=STOP — keepalived will shut down. bye bestie 👋
• USR1 or SIGFUNC=DATA — write configuration data to /tmp/keepalived.data or to the file configured by state_dump_file. 📝
• USR2 or SIGFUNC=STATS — write statistics info to /tmp/keepalived.stats or to the file configured by stats_dump_file. 📊
• SIGFUNC=STATS_CLEAR — write statistics info to /tmp/keepalived.stats or to the file configured by stats_dump_file, and clear the statistics counters. fresh start era ✨
• SIGFUNC=JSON — write configuration data in JSON format to /tmp/keepalived.json or to the file configured by json_dump_file. 🧚
• SIGFUNC=TDATA — this makes keepalived write the current state of its internal threads to the log. 🧵

---

🔥 USING KEEPALIVED WITH FIREWALLD 🔥

If you're running a firewall (peep firewalld(8)) you must let VRRP protocol traffic through it. No exceptions bestie, the firewall will simply not let it through otherwise. 🚫

For example, if this instance of keepalived(8) has a peer node on IPv4 address 192.168.0.1:

# firewall-cmd \
    --add-rich-rule="rule family='ipv4' \
                     source address='192.168.0.1' \
                     protocol value='vrrp' accept" --permanent
# firewall-cmd --reload

and that's the whole vibe. 🎀

---

🌈 SEE ALSO 🌈

keepalived.conf(5), ipvsadm(8)

go read those too, they're part of the lore, iykyk 📚

---

👑 AUTHOR 👑

This man page was written by Ryan O'Hara <rohara@redhat.com> 🫶

---

okay that's a wrap bestie!! this page is from the keepalived 2025-03-29 era, and you were reading KEEPALIVED(8) the whole time — iconic, no cap, periodt 💅✨