# isc-projects/kea architecture

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

- Interactive diagram: https://gitdiagram.com/isc-projects/kea
- Repository: https://github.com/isc-projects/kea

## Overview

##### Project type and purpose
- Kea is a modular C++ network services suite providing:
- DHCPv4 and DHCPv6 server daemons
- A dynamic DNS update module (DDNS)
- A control agent exposing a REST management interface
- A NETCONF/YANG agent
- A DHCP benchmarking tool (perfdhcp)
- It’s designed as a back-end network services platform (not a typical web front end).

##### High-level file structure and architectural patterns
- Top-level “src/bin/…” directories define each executable component (dhcp4, dhcp6, agent, d2, netconf, keactrl, perfdhcp, shell, lfc).
- “src/lib/…” holds a large collection of reusable libraries (network I/O, HTTP/REST, TCP/UDP abstraction, configuration, hooks framework, database backends, DNS, crypto, logging, YANG translator, etc.).
- “share/api” contains JSON schemas for the REST API commands.
- Build is orchestrated by Meson build scripts (meson.build files at multiple levels).
- Configuration, dynamic loading (hooks), inter-process communication, and multi-threading are key design principles.

##### Main components
a. Executable services (each in its own process):
- DHCPv4 server
- DHCPv6 server
- DDNS update module (plugin or process)
- Control Agent (REST/HTTP interface)
- NETCONF/YANG Agent
- perfdhcp benchmarking tool
- Auxiliary tools (shell, lfc, keactrl)
b. Shared library layers:
- Network I/O layer (asiolink, asiodns)
- Protocol libraries (libdhcp++, dns, dhcp_ddns, dhcpsrv, d2srv)
- HTTP/REST layer (lib/http, HTTP command mgr in lib/config)
- Hooks framework (lib/hooks) for dynamic callouts
- Configuration and translation (lib/config, lib/yang)
- Database abstraction (lib/database, backends mysql/pgsql)
- Logging and metrics (lib/log, lib/stats)
- Utility libraries (cryptolink, util, exceptions, process)
c. External dependencies:
- Network clients (actual DHCP clients)
- Upstream DNS servers (for DDNS)
- Databases: MySQL or PostgreSQL for storing leases and state
- Sysrepo/YANG datastore (for NETCONF agent, if used)

##### Relationships and interactions
- DHCP servers listen on UDP sockets (asiolink) → parse packets (lib/dhcp) → pass to service engine (lib/dhcpsrv) → storage backends (lib/database/mysql or lib/database/pgsql) → respond on network.
- Control Agent receives HTTP/REST requests (lib/http, lib/config) → configuration manager updates server config via IPC or direct API calls → queries status via control socket.
- NETCONF Agent uses YANG modules (lib/yang) → interfaces to config manager via control socket → applies changes.
- Hooks framework loaded by servers to run custom callouts at defined hook points.
- perfdhcp generates and sends simulated DHCP traffic via network I/O libraries.

##### Important architectural patterns and principles
- Layered modular design: reusable libraries separated from executables.
- Plugin/hook architecture: lib/hooks provides dynamic extension.
- IPC and REST as management interfaces.
- Meson-based multi-project build orchestrating libraries and binaries.
- Separation of concerns: network I/O, protocol parsing, business logic, persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Executables"
        dhcp4["DHCPv4 Server"]:::exec
        dhcp6["DHCPv6 Server"]:::exec
        d2["DDNS Module (D2)"]:::exec
        agent["Control Agent"]:::exec
        netconf["NETCONF/YANG Agent"]:::exec
        perfdhcp["perfdhcp Tool"]:::exec
        shell["Shell Tool"]:::exec
        lfc["LFC Tool"]:::exec
        keactrl["Keactrl Script"]:::exec
    end

    subgraph "Libraries"
        asiolink["Network I/O (asiolink)"]:::lib
        asiodns["DNS I/O (asiodns)"]:::lib
        dhcp["Protocol Library (libdhcp++)"]:::lib
        dhcp_ddns["DDNS Library (libdhcp_ddns)"]:::lib
        dhcpsrv["DHCP Engine (libdhcpsrv)"]:::lib
        d2srv["DDNS Engine (lib/d2srv)"]:::lib
        dns_lib["DNS Msg Library (lib/dns)"]:::lib
        http["HTTP/REST (lib/http)"]:::lib
        config["Config Cmds (lib/config)"]:::lib
        hooks["Hooks Framework"]:::lib
        config_backend["Config Backend"]:::lib
        yang["YANG Translator"]:::lib
        database["DB Abstraction"]:::lib
        mysql["MySQL Backend"]:::lib
        pgsql["PostgreSQL Backend"]:::lib
        log["Logging (lib/log)"]:::lib
        stats["Metrics (lib/stats)"]:::lib
        cryptolink["Crypto (lib/cryptolink)"]:::lib
        util["Utilities (lib/util)"]:::lib
        exceptions["Exceptions"]:::lib
        process_lib["Process/IPC"]:::lib
        tcp["TCP Stream"]:::lib
    end

    subgraph "External"
        clients["DHCP Clients"]:::ext
        dns_upstream["Upstream DNS Servers"]:::ext
        mysql_srv["MySQL Server"]:::ext
        pgsql_srv["PostgreSQL Server"]:::ext
        sysrepo["Sysrepo/YANG Datastore"]:::ext
    end

    clients -->|DHCP requests| dhcp4
    clients -->|DHCP requests| dhcp6

    dhcp4 -->|uses| asiolink
    dhcp6 -->|uses| asiolink
    perfdhcp -->|simulates| asiolink

    dhcp4 -->|parses| dhcp
    dhcp6 -->|parses| dhcp
    perfdhcp -->|uses| dhcp

    dhcp4 -->|engine| dhcpsrv
    dhcp6 -->|engine| dhcpsrv
    d2 -->|engine| d2srv

    dhcpsrv -->|stores| database
    d2srv -->|stores| database

    database -->|connects| mysql
    database -->|connects| pgsql

    dhcpsrv -->|hooks| hooks
    dhcpsrv -->|dns msgs| dns_lib
    d2srv -->|dns I/O| asiodns
    d2srv -->|dns msgs| dns_lib

    agent -->|REST calls| http
    http -->|commands| config
    agent -->|IPC| process_lib
    process_lib --> dhcp4
    process_lib --> dhcp6
    process_lib --> d2

    netconf -->|YANG| yang
    netconf -->|IPC| process_lib
    netconf -->|stores| config_backend
    netconf -->|sync| sysrepo

    d2 -->|updates| dns_upstream

    classDef exec fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef ext fill:#FFA500,stroke:#000,stroke-width:1px;

    click dhcp4 "https://github.com/isc-projects/kea/tree/master/src/bin/dhcp4"
    click dhcp6 "https://github.com/isc-projects/kea/tree/master/src/bin/dhcp6"
    click d2 "https://github.com/isc-projects/kea/tree/master/src/bin/d2"
    click agent "https://github.com/isc-projects/kea/tree/master/src/bin/agent"
    click netconf "https://github.com/isc-projects/kea/tree/master/src/bin/netconf"
    click perfdhcp "https://github.com/isc-projects/kea/tree/master/src/bin/perfdhcp"
    click shell "https://github.com/isc-projects/kea/tree/master/src/bin/shell"
    click lfc "https://github.com/isc-projects/kea/tree/master/src/bin/lfc"
    click keactrl "https://github.com/isc-projects/kea/tree/master/src/bin/keactrl"

    click asiolink "https://github.com/isc-projects/kea/tree/master/src/lib/asiolink"
    click asiodns "https://github.com/isc-projects/kea/tree/master/src/lib/asiodns"
    click dhcp "https://github.com/isc-projects/kea/tree/master/src/lib/dhcp"
    click dhcp_ddns "https://github.com/isc-projects/kea/tree/master/src/lib/dhcp_ddns"
    click dhcpsrv "https://github.com/isc-projects/kea/tree/master/src/lib/dhcpsrv"
    click d2srv "https://github.com/isc-projects/kea/tree/master/src/lib/d2srv"
    click dns_lib "https://github.com/isc-projects/kea/tree/master/src/lib/dns"
    click http "https://github.com/isc-projects/kea/tree/master/src/lib/http"
    click config "https://github.com/isc-projects/kea/tree/master/src/lib/config"
    click hooks "https://github.com/isc-projects/kea/tree/master/src/lib/hooks"
    click config_backend "https://github.com/isc-projects/kea/tree/master/src/lib/config_backend"
    click yang "https://github.com/isc-projects/kea/tree/master/src/lib/yang"
    click database "https://github.com/isc-projects/kea/tree/master/src/lib/database"
    click mysql "https://github.com/isc-projects/kea/tree/master/src/lib/mysql"
    click pgsql "https://github.com/isc-projects/kea/tree/master/src/lib/pgsql"
    click log "https://github.com/isc-projects/kea/tree/master/src/lib/log"
    click stats "https://github.com/isc-projects/kea/tree/master/src/lib/stats"
    click cryptolink "https://github.com/isc-projects/kea/tree/master/src/lib/cryptolink"
    click util "https://github.com/isc-projects/kea/tree/master/src/lib/util"
    click exceptions "https://github.com/isc-projects/kea/tree/master/src/lib/exceptions"
    click process_lib "https://github.com/isc-projects/kea/tree/master/src/lib/process"
    click tcp "https://github.com/isc-projects/kea/tree/master/src/lib/tcp"
```
