# acassen/keepalived architecture

> Architecture diagram of the GitHub repository acassen/keepalived, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/acassen/keepalived
- Repository: https://github.com/acassen/keepalived

## Overview

##### Project type and purpose
- keepalived is an open-source C daemon providing Linux Layer-4 load-balancing (via IPVS), health-checking, and high-availability (via VRRP and BFD).
- It bundles multiple protocol engines (VRRP, BFD), checkers (HTTP, TCP, DNS, …), a scheduler/event multiplexer, and integrations (netlink, systemd, DBus, SNMP).

##### File structure
- Top-level build/config: configure.ac, Makefile.am, autogen.sh, m4/, Dockerfile.in, snap/ (snapcraft.yaml), bin_install/, bin/.
- Documentation: doc/, README.md, INSTALL, COPYING.
- Core code in keepalived/: subdivided into modules
- keepalived/core – daemon bootstrap, I/O multiplexer, config parser, global data, reload monitor, namespaces, netlink wrapper, scheduler
- keepalived/check – health-check implementations (HTTP, SMTP, PING, FILE, SSL, DNS, BFD, NFTables, …) and check API
- keepalived/vrrp – VRRP FSM, ARP, firewall rules, IP rules/routes, JSON serialization, notifications, SNMP hooks, sync
- keepalived/bfd – BFD protocol engine for fast link-failure detection
- keepalived/dbus – DBus interface templates for VRRP instances
- keepalived/etc – init scripts, systemd service templates, sample keepalived.conf
- keepalived/include – all public and internal headers
- Shared library code in lib/: utilities for parsing, JSON, logging, scheduling, event timers, process management, rbtree, vector, sockets, systemd support
- Tools & tests: tools/, test/, snap-tools/, goodies/

##### README for additional insights
- Describes architecture: I/O multiplexer at core, independent modules can be “used separately or together”
- Lists key protocols: IPVS (kernel), VRRP, BFD, plus health-check hooks

- keepalived Daemon
- Configuration Parser & Reload Monitor
- Event Multiplexer / Scheduler
- Health-Check Engine (check modules)
- VRRP Engine (FSM, ARP, firewall rules)
- BFD Engine
- Notification / Hooks (JSON, SNMP, custom scripts, DBus)
- IPVS Kernel Module (Layer-4 load-balancing)
- Netlink Interface (kernel communication)
- External Dependencies
- Configuration File (keepalived.conf)
- System Init (systemd / SysV scripts)
- DBus Bus
- SNMP Subsystem
- Logging subsystem (syslog)
- Client/Server Pools (backend servers, virtual IPs, real servers)
b. Relationships and interactions
- Daemon reads keepalived.conf → parser → internal data structures
- Scheduler drives I/O Multiplexer → triggers events for checkers, VRRP advertisements, BFD sessions
- Health-Check Engine → polls real servers → updates IPVS virtual server pool via Netlink/IPVS API
- VRRP Engine → sends/receives multicast VRRP packets → manages virtual router state → updates kernel ARP or iptables via Netlink
- BFD Engine → participates in BFD neighbor sessions → signals scheduler/VRRP for fast failover
- Notification Hooks → on state changes or check failures → emit JSON/SNMP or invoke scripts → optionally over DBus
c. Architectural patterns & principles
- Modular plugin-style checkers and protocol engines
- Central event loop (I/O multiplexer) with cooperative multi-threading
- Clear separation of concerns: config, core, checks, protocols, OS integration
d. Key technologies & libraries
- C99, libnl (netlink), IPVS kernel module, POSIX sockets, epoll/select, systemd unit interface, DBus XML templates

##### Final advice
- Be detailed: break out each module (core, check, vrrp, bfd, lib, dbus)
- Essential OS integration points (netlink, systemd, DBus, SNMP, syslog)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-space Daemon
    subgraph "User-space Daemon"
        subgraph "Core"
            DaemonCore["Daemon Core"]:::core
            ConfigParser["Configuration Parser & Reload Monitor"]:::core
            EventLoop["Event Multiplexer / Scheduler"]:::core
        end
        subgraph "Protocol Engines"
            HealthCheck["Health-Check Engine"]:::proto
            VRRPEngine["VRRP Engine"]:::proto
            BFDEngine["BFD Engine"]:::proto
        end
        subgraph "Notification & Hooks"
            Notify["Notification & Hooks"]:::os
        end
        subgraph "Libs & Utils"
            NetlinkIPVS["Netlink / IPVS Integration"]:::os
            SNMP["SNMP Support"]:::os
            Logging["Logging & Utilities"]:::lib
        end
    end

    %% Kernel-space Interfaces
    subgraph "Kernel-space Interfaces"
        IPVS["IPVS Kernel Module"]:::os
        NetlinkIF["Netlink Interface"]:::os
        RawSockets["Raw Sockets (VRRP/BFD)"]:::os
    end

    %% External Systems
    subgraph "External Systems"
        ConfFile["Configuration File"]:::ext
        SysInit["System Init (systemd/SysV)"]:::ext
        DBus["DBus Bus"]:::ext
        SNMPSub["SNMP Subsystem"]:::ext
        Syslog["Logging Subsystem (syslog)"]:::ext
        Backends["Client/Server Pools"]:::ext
    end

    %% Connections
    ConfFile -->|"reads"| ConfigParser
    ConfigParser -->|"builds data"| DaemonCore
    DaemonCore --> EventLoop
    EventLoop -->|"triggers"| HealthCheck
    EventLoop -->|"triggers"| VRRPEngine
    EventLoop -->|"triggers"| BFDEngine

    HealthCheck -->|"updates pool"| NetlinkIPVS
    NetlinkIPVS -->|"calls"| IPVS

    VRRPEngine -->|"multicast packets"| RawSockets
    VRRPEngine -->|"netlink updates"| NetlinkIPVS
    RawSockets -->|"network"| Backends

    BFDEngine -->|"raw packets"| RawSockets
    BFDEngine -->|"signals"| EventLoop

    VRRPEngine -->|"state changes"| Notify
    HealthCheck -->|"failures"| Notify
    BFDEngine -->|"failures"| Notify

    Notify --> DBus
    Notify --> SNMPSub
    Notify --> Syslog

    DaemonCore --> NetlinkIPVS
    SysInit --> DaemonCore
    Logging --> Syslog

    %% Click Events
    click DaemonCore "https://github.com/acassen/keepalived/blob/master/keepalived/main.c"
    click ConfigParser "https://github.com/acassen/keepalived/blob/master/keepalived/core/global_parser.c"
    click EventLoop "https://github.com/acassen/keepalived/blob/master/lib/scheduler.c"
    click HealthCheck "https://github.com/acassen/keepalived/tree/master/keepalived/check/"
    click VRRPEngine "https://github.com/acassen/keepalived/blob/master/keepalived/vrrp/vrrp.c"
    click BFDEngine "https://github.com/acassen/keepalived/blob/master/keepalived/bfd/bfd.c"
    click Notify "https://github.com/acassen/keepalived/blob/master/keepalived/vrrp/vrrp_notify.c"
    click NetlinkIPVS "https://github.com/acassen/keepalived/blob/master/keepalived/core/keepalived_netlink.c"
    click SNMP "https://github.com/acassen/keepalived/blob/master/keepalived/core/snmp.c"
    click Logging "https://github.com/acassen/keepalived/blob/master/lib/logger.c"
    click ConfFile "https://github.com/acassen/keepalived/blob/master/keepalived/etc/keepalived/keepalived.conf"
    click SysInit "https://github.com/acassen/keepalived/tree/master/keepalived/etc/init.d/keepalived"

    %% Styles
    classDef core fill:#D6E9F8,stroke:#2B6CB0,stroke-width:2px
    classDef proto fill:#DFFFE0,stroke:#2F855A,stroke-width:2px
    classDef os fill:#FFF5D1,stroke:#DD6B20,stroke-width:2px
    classDef lib fill:#F0E68C,stroke:#B7791F,stroke-width:2px
    classDef ext fill:#E2E8F0,stroke:#4A5568,stroke-width:2px
```
