Skip to content
1337skills 1337skills

Keepalived Cheat Sheet

Overview

Keepalived is a routing software framework for Linux that provides high availability via VRRP (Virtual Router Redundancy Protocol) and load balancing through integration with Linux Virtual Server (LVS/IPVS). It is commonly used to create floating virtual IP addresses that automatically failover between servers when the primary goes down. Keepalived monitors the health of servers and services, promoting backup nodes to master when failures are detected.

The VRRP component manages virtual IP addresses across a group of servers, ensuring that exactly one server holds each VIP at any time. The LVS component distributes network traffic across multiple real servers using NAT, direct routing, or IP tunneling methods. Keepalived also supports custom health check scripts for application-level monitoring, SMTP notifications, and integration with firewall rules. It is widely used in front of web servers, database clusters, Kubernetes API servers, and any service requiring zero-downtime failover.

Installation

Package Installation

# Ubuntu/Debian
sudo apt install keepalived

# RHEL/CentOS/Rocky
sudo dnf install keepalived

# From source
wget https://www.keepalived.org/software/keepalived-2.2.8.tar.gz
tar xzf keepalived-2.2.8.tar.gz
cd keepalived-2.2.8
./configure
make && sudo make install

# Enable and start
sudo systemctl enable keepalived
sudo systemctl start keepalived

Kernel Requirements

# Enable IP forwarding
sudo sysctl -w net.ipv4.ip_forward=1

# Allow binding to non-local addresses
sudo sysctl -w net.ipv4.ip_nonlocal_bind=1

# Make persistent
echo "net.ipv4.ip_forward = 1" | sudo tee -a /etc/sysctl.d/keepalived.conf
echo "net.ipv4.ip_nonlocal_bind = 1" | sudo tee -a /etc/sysctl.d/keepalived.conf
sudo sysctl -p /etc/sysctl.d/keepalived.conf

Core Commands

CommandDescription
sudo systemctl start keepalivedStart keepalived
sudo systemctl stop keepalivedStop keepalived
sudo systemctl reload keepalivedReload configuration
sudo systemctl status keepalivedCheck service status
sudo kill -USR1 $(pidof keepalived)Dump VRRP state to syslog
sudo kill -USR2 $(pidof keepalived)Dump statistics
ip addr showVerify VIP assignment
ipvsadm -LnShow LVS rules (if using LVS)
journalctl -u keepalived -fFollow keepalived logs

Configuration

Simple VRRP Failover

Master node (/etc/keepalived/keepalived.conf):

global_defs {
    router_id LB_MASTER
    script_user root
    enable_script_security
}

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass secretpass
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
}

Backup node:

global_defs {
    router_id LB_BACKUP
    script_user root
    enable_script_security
}

vrrp_instance VI_1 {
    state BACKUP
    interface eth0
    virtual_router_id 51
    priority 90
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass secretpass
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
}

Health Check Scripts

vrrp_script chk_nginx {
    script "/usr/bin/systemctl is-active nginx"
    interval 2
    weight -20
    fall 3
    rise 2
}

vrrp_script chk_http {
    script "/usr/bin/curl -sf http://localhost/health"
    interval 5
    weight -30
    fall 3
    rise 2
    timeout 3
}

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass secretpass
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
    track_script {
        chk_nginx
        chk_http
    }
}

Notification Scripts

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass secretpass
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
    notify_master "/etc/keepalived/scripts/notify.sh MASTER"
    notify_backup "/etc/keepalived/scripts/notify.sh BACKUP"
    notify_fault  "/etc/keepalived/scripts/notify.sh FAULT"
}
#!/bin/bash
# /etc/keepalived/scripts/notify.sh
STATE=$1
HOSTNAME=$(hostname)
echo "$(date): $HOSTNAME transitioned to $STATE" >> /var/log/keepalived-notify.log

Load Balancing with LVS

virtual_server 192.168.1.100 80 {
    delay_loop 10
    lb_algo rr
    lb_kind DR
    persistence_timeout 300
    protocol TCP

    real_server 192.168.1.10 80 {
        weight 1
        HTTP_GET {
            url {
                path /health
                status_code 200
            }
            connect_timeout 3
            retry 3
            delay_before_retry 1
        }
    }

    real_server 192.168.1.11 80 {
        weight 1
        HTTP_GET {
            url {
                path /health
                status_code 200
            }
            connect_timeout 3
            retry 3
            delay_before_retry 1
        }
    }
}
LVS AlgorithmFlagDescription
Round RobinrrEqual distribution
Weighted Round RobinwrrWeighted distribution
Least ConnectionslcFewest active connections
Weighted Least ConnectionswlcWeighted least connections
Source HashingshClient IP based
Destination HashingdhDestination based

Advanced Usage

Multiple VIPs and VRRP Groups

vrrp_sync_group VG_1 {
    group {
        VI_1
        VI_2
    }
}

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    virtual_ipaddress {
        192.168.1.100/24
    }
}

vrrp_instance VI_2 {
    state MASTER
    interface eth0
    virtual_router_id 52
    priority 100
    advert_int 1
    virtual_ipaddress {
        192.168.1.101/24
    }
}

Track Interface

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    track_interface {
        eth0 weight -50
        eth1 weight -50
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
}

Unicast Mode (No Multicast)

vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    unicast_src_ip 10.0.0.1
    unicast_peer {
        10.0.0.2
        10.0.0.3
    }
    virtual_ipaddress {
        192.168.1.100/24
    }
}

Troubleshooting

IssueSolution
VIP not assignedCheck ip addr show; verify VRRP traffic not blocked by firewall (protocol 112)
Split-brain (both masters)Ensure VRRP multicast or unicast traffic flows between nodes; check virtual_router_id matches
Health check not workingTest script manually; ensure script_user and enable_script_security are set
VIP flappingIncrease advert_int or adjust weight values in health checks
Permission denied on scriptsSet script_user root and enable_script_security in global_defs
Cannot bind to VIPEnable net.ipv4.ip_nonlocal_bind=1 in sysctl
LVS real server not receiving trafficVerify ARP settings for DR mode; check ipvsadm -Ln output