keepalived-fips

packaged by Chainguard

Chainguard Container for keepalived-fips

Keepalived implements the Virtual Router Redundancy Protocol (VRRP) so a virtual IP can fail over between routers, and drives the Linux Virtual Server (IPVS) kernel load balancer with health checkers that add and remove real servers as they come and go. This variant runs against an OpenSSL restricted to FIPS-approved algorithms.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/keepalived-fips:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The keepalived project does not publish a container image, so there is no upstream image to be a drop-in replacement for. Upstream ships a Dockerfile.in template in its source tree that users build themselves, and this image follows it: the entrypoint is the same, and the binary is reachable at both /usr/sbin/keepalived and /usr/bin/keepalived.

keepalived takes all of its cryptography from the system OpenSSL through the EVP API, so this is the same build as the standard keepalived image plus openssl-config-fipshardened, rather than a separately built binary.

No configuration file ships in the image. Upstream's Dockerfile copies a demo keepalived.conf that claims the address 10.247.254.2 on eth0; since nothing else advertises for that virtual router, a container started with it wins the election and takes that address on whatever network it joins. Mount your own instead. A commented reference configuration is included at /etc/keepalived/keepalived.conf.sample.

This image runs as root. VRRP assigns virtual IPs and the health checkers program IPVS, both of which require CAP_NET_ADMIN, so keepalived cannot run as an unprivileged user.

FIPS Support

keepalived uses MD5 in three places, none of them FIPS-approved: auth_type AH VRRP authentication, the url { digest } option of the HTTP_GET and SSL_GET checkers, and the bundled genhash tool. All three keep working in this image by default, because the OpenSSL legacy provider is enabled. Set CHAINGUARD_LEGACY_ALLOWED=0 in the container environment to turn MD5 off.

With MD5 off, keepalived logs IPSEC-AH : cannot compute HMAC-MD5 and sends an unauthenticated advert that peers reject, and a digest health check fails against a server that is actually healthy. Use the approved alternatives:

auth_type PASS is unaffected either way: it sends the password in clear text and involves no cryptography at all.

Do not deactivate the legacy provider on a running auth_type AH cluster. The node loses the ability to verify its peers as well as to sign its own adverts, so it discards everything it receives, times out and promotes itself, leaving two routers holding the virtual IP. Migrate to auth_hmac first.

For more on FIPS support in Chainguard Containers, consult the guide on FIPS-enabled Chainguard Containers.

Prerequisites

keepalived manages addresses and routes on a real network interface, so the container needs:

• CAP_NET_ADMIN and CAP_NET_RAW,
• a writable /run: keepalived writes keepalived.pid, keepalived_vrrp.pid and keepalived_checkers.pid there. Under a read-only root filesystem, mount a writable volume at /run, or the pid-file open fails and keepalived reports it as daemon is already running, and
• an interface it can act on. In practice that means host networking, or a network the container shares with the peers it fails over with. Set interface to that host's actual NIC name: keepalived exits if the interface does not exist, and it is often not eth0.

VRRP uses IP protocol 112 to the multicast group 224.0.0.18 rather than a TCP port, so no ports are published. Where multicast is unavailable, configure unicast_peer instead.

Getting Started

Write a configuration and mount it over /etc/keepalived/keepalived.conf. This example authenticates its adverts with auth_hmac, which is the option to use here, and claims a virtual IP on eth0; with --network host that is the host's interface name, so substitute your own everywhere eth0 appears below.

Generate the key rather than copying this one, with openssl rand -hex 32:

cat > keepalived.conf <<'EOF'
global_defs {
    router_id node1
}

vrrp_instance VI_1 {
    state BACKUP
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    auth_hmac {
        key 1 hex:000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
        active_key 1
        anti_replay monotonic
        mode enforce
    }
    virtual_ipaddress {
        192.0.2.100/32 dev eth0
    }
}
EOF

docker run -d --name keepalived \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --network host \
  -v "$PWD/keepalived.conf:/etc/keepalived/keepalived.conf:ro" \
  cgr.dev/ORGANIZATION/keepalived-fips:latest

Every peer sharing a virtual_router_id must carry the same key, or they will reject each other's adverts and each claim the virtual IP.

With no peer advertising a higher priority, the instance is promoted after the advertisement interval:

docker logs keepalived 2>&1 | grep "Entering MASTER STATE"

and the virtual IP is assigned to the interface:

docker exec keepalived ip -4 addr show dev eth0

Before starting the daemon, you can check a configuration without running it:

docker run --rm --entrypoint /usr/bin/keepalived \
  -v "$PWD/keepalived.conf:/etc/keepalived/keepalived.conf:ro" \
  cgr.dev/ORGANIZATION/keepalived-fips:latest --config-test

Configuration

keepalived itself is configured entirely through /etc/keepalived/keepalived.conf; it reads no environment variables of its own. The image honours CHAINGUARD_LEGACY_ALLOWED, described under FIPS Support above. The entrypoint runs the daemon in the foreground with --dont-fork --log-console, so it logs to stderr rather than to a file inside the container. docker logs shows it; pipe with 2>&1 when grepping.

Health checkers are the other half of a typical configuration. IPVS is a kernel facility, so the ip_vs module must already be loaded on the host: the image ships no modprobe, and without it keepalived logs IPVS: Can't initialize ipvs and silently stops load balancing.

This virtual_server load balances two backends and removes one automatically when its HTTP check fails. It matches on status_code rather than digest, since the digest option is MD5:

virtual_server 192.0.2.100 80 {
    delay_loop 5
    lb_algo rr
    lb_kind NAT
    protocol TCP

    real_server 192.0.2.11 80 {
        weight 1
        HTTP_GET {
            url { path /healthz status_code 200 }
            connect_timeout 2
        }
    }

    real_server 192.0.2.12 80 {
        weight 1
        HTTP_GET {
            url { path /healthz status_code 200 }
            connect_timeout 2
        }
    }
}

If you use notify or vrrp_script hooks, keepalived runs them as the keepalived_script user, which this image creates. Scripts must be readable and executable by that user, and every directory in the path to the script must be owned by root and not writable by anyone else, or enable_script_security refuses to run them.

This image ships no shell or interpreter, so a hook must be an executable the kernel can run directly -- a dynamically linked ELF binary is fine, as long as its libraries are in the image. A #!/bin/sh script fails to exec, and a command written as a shell string is run through system(), which also needs a shell. Add busybox with Custom Assembly if your hooks need one.

keepalived's parent process stays alive if the VRRP child exits transiently, so a container can look healthy while doing nothing. It does exit on a configuration error, a fatal error or a missing permission, so container liveness catches those. For everything else, watch for Entering MASTER STATE or poll the virtual IP rather than relying on container liveness alone.

This image is built with VRRP, LVS/IPVS, BFD, nftables, iptables, ipset, SNMP (including the RFC VRRP MIBs), DBus, JSON and regex support compiled in. SNMP is an AgentX subagent, so it needs a master agent reachable at /var/agentx/master; neither that socket nor its directory exists in the image, so mount the socket in from a master agent on the host. Run docker run --rm --entrypoint /usr/bin/keepalived cgr.dev/ORGANIZATION/keepalived-fips:latest -v to print the full list.

Documentation and Resources

• FIPS-enabled Chainguard Containers
• Standard keepalived container image
• keepalived user guide
• keepalived.conf reference
• Upstream source

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.