# Kea DHCP Server

Kea is a high-performance, extensible DHCP server developed by Internet Systems Consortium (ISC). It provides DHCPv4 and DHCPv6 servers, a dynamic DNS update module (D2), a portable DHCP library (libdhcp++), a NETCONF agent for YANG/NETCONF interface, and a DHCP benchmarking tool (perfdhcp). Kea supports multiple lease storage backends including in-memory (memfile), MySQL, and PostgreSQL.

Kea's architecture is built around hook libraries that extend functionality, a RESTful control channel for runtime management, and JSON-based configuration files. It supports advanced features like High Availability (HA) with load balancing or hot standby modes, client classification, host reservations, shared networks, and dynamic DNS updates via the D2 daemon.

## DHCPv4 Server Configuration

The DHCPv4 server (kea-dhcp4) is configured using JSON format with support for interfaces, lease storage, subnets, pools, and options. The configuration defines network interfaces to listen on, lease database backend, address pools, and various timers.

```json
{
  "Dhcp4": {
    "interfaces-config": {
      "interfaces": ["eth0"]
    },
    "lease-database": {
      "type": "memfile",
      "lfc-interval": 3600
    },
    "valid-lifetime": 4000,
    "renew-timer": 1000,
    "rebind-timer": 2000,
    "subnet4": [
      {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [{ "pool": "192.0.2.1 - 192.0.2.200" }],
        "interface": "eth0",
        "option-data": [
          {
            "name": "routers",
            "data": "192.0.2.1"
          },
          {
            "name": "domain-name-servers",
            "data": "8.8.8.8, 8.8.4.4"
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp4",
        "output-options": [{ "output": "stdout" }],
        "severity": "INFO"
      }
    ]
  }
}
```

## DHCPv6 Server Configuration

The DHCPv6 server (kea-dhcp6) follows a similar configuration structure with IPv6-specific parameters like preferred-lifetime and support for prefix delegation (IA_PD).

```json
{
  "Dhcp6": {
    "interfaces-config": {
      "interfaces": ["eth0"]
    },
    "lease-database": {
      "type": "memfile",
      "lfc-interval": 3600
    },
    "preferred-lifetime": 3000,
    "valid-lifetime": 4000,
    "renew-timer": 1000,
    "rebind-timer": 2000,
    "subnet6": [
      {
        "id": 1,
        "subnet": "2001:db8:1::/64",
        "pools": [{ "pool": "2001:db8:1::/80" }],
        "interface": "eth0",
        "pd-pools": [
          {
            "prefix": "2001:db8:8::",
            "prefix-len": 56,
            "delegated-len": 64
          }
        ]
      }
    ],
    "loggers": [
      {
        "name": "kea-dhcp6",
        "output-options": [{ "output": "stdout" }],
        "severity": "INFO",
        "debuglevel": 0
      }
    ]
  }
}
```

## Control Socket and REST API

Kea provides a control channel via UNIX socket for runtime management. Commands are sent as JSON objects. The kea-shell utility provides a command-line interface to interact with the server.

```bash
# Configure control socket in kea-dhcp4.conf
{
  "Dhcp4": {
    "control-socket": {
      "socket-type": "unix",
      "socket-name": "/tmp/kea4-ctrl-socket"
    }
  }
}

# Using kea-shell to send commands
echo '{}' | kea-shell --host 127.0.0.1 --port 8000 list-commands

# Send command directly via socket using socat
echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea4-ctrl-socket -

# Get server configuration
echo '{ "command": "config-get" }' | socat UNIX:/tmp/kea4-ctrl-socket -

# Reload configuration
echo '{ "command": "config-reload" }' | socat UNIX:/tmp/kea4-ctrl-socket -

# Get server version
echo '{ "command": "version-get" }' | socat UNIX:/tmp/kea4-ctrl-socket -

# Response format
{
  "result": 0,
  "text": "Kea version...",
  "arguments": { ... }
}
```

## Host Reservations

Kea supports static IP address reservations based on various identifiers including hardware address, client-id, DUID, circuit-id, and flexible identifier expressions.

```json
{
  "Dhcp4": {
    "host-reservation-identifiers": ["hw-address", "client-id", "duid", "circuit-id", "flex-id"],
    "subnet4": [
      {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [{ "pool": "192.0.2.1 - 192.0.2.200" }],
        "reservations-global": false,
        "reservations-in-subnet": true,
        "reservations-out-of-pool": false,
        "reservations": [
          {
            "hw-address": "1a:1b:1c:1d:1e:1f",
            "ip-address": "192.0.2.201"
          },
          {
            "client-id": "01:11:22:33:44:55:66",
            "ip-address": "192.0.2.202",
            "hostname": "special-client"
          },
          {
            "duid": "01:02:03:04:05",
            "ip-address": "192.0.2.203",
            "option-data": [
              {
                "name": "domain-name-servers",
                "data": "10.1.1.202, 10.1.1.203"
              }
            ]
          },
          {
            "client-id": "01:0a:0b:0c:0d:0e:0f",
            "ip-address": "192.0.2.205",
            "next-server": "192.0.2.1",
            "server-hostname": "tftp-server",
            "boot-file-name": "/pxelinux.0"
          }
        ]
      }
    ]
  }
}
```

## Lease Commands API

The lease_cmds hook library provides commands for managing leases programmatically. Load the library and use JSON commands via the control channel.

```json
// Load the hook library
{
  "Dhcp4": {
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so" }
    ]
  }
}

// lease4-add: Add a new IPv4 lease
{
  "command": "lease4-add",
  "arguments": {
    "ip-address": "192.0.2.202",
    "hw-address": "1a:1b:1c:1d:1e:1f",
    "subnet-id": 1,
    "valid-lft": 3600,
    "hostname": "myhost.example.com",
    "fqdn-fwd": true,
    "fqdn-rev": true
  }
}
// Response: { "result": 0, "text": "Lease added." }

// lease4-get: Retrieve a lease by IP address
{
  "command": "lease4-get",
  "arguments": {
    "ip-address": "192.0.2.1"
  }
}
// Response:
{
  "result": 0,
  "text": "IPv4 lease found.",
  "arguments": {
    "ip-address": "192.0.2.1",
    "hw-address": "08:08:08:08:08:08",
    "client-id": "42:42:42:42:42:42:42:42",
    "subnet-id": 44,
    "valid-lft": 3600,
    "cltt": 12345678,
    "fqdn-fwd": false,
    "fqdn-rev": true,
    "hostname": "myhost.example.com.",
    "state": 0
  }
}

// lease4-get-by-hw-address: Get leases by MAC address
{
  "command": "lease4-get-by-hw-address",
  "arguments": {
    "hw-address": "08:08:08:08:08:08"
  }
}

// lease4-del: Delete a lease
{
  "command": "lease4-del",
  "arguments": {
    "ip-address": "192.0.2.202",
    "update-ddns": true
  }
}

// lease4-update: Update an existing lease
{
  "command": "lease4-update",
  "arguments": {
    "ip-address": "192.0.2.1",
    "hw-address": "1a:1b:1c:1d:1e:1f",
    "subnet-id": 44,
    "hostname": "newhostname.example.org",
    "force-create": true
  }
}

// lease4-get-page: Paginated lease retrieval
{
  "command": "lease4-get-page",
  "arguments": {
    "from": "start",
    "limit": 1024
  }
}

// lease4-wipe: Remove all leases from a subnet
{
  "command": "lease4-wipe",
  "arguments": {
    "subnet-id": 44
  }
}
```

## High Availability Configuration

The HA hook library enables failover and load balancing between Kea servers. It supports load-balancing, hot-standby, and passive-backup modes.

```json
{
  "Dhcp4": {
    "multi-threading": {
      "enable-multi-threading": true,
      "thread-pool-size": 4,
      "packet-queue-size": 64
    },
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so" },
      {
        "library": "/usr/lib/kea/hooks/libdhcp_ha.so",
        "parameters": {
          "high-availability": [
            {
              "this-server-name": "server1",
              "mode": "load-balancing",
              "heartbeat-delay": 10000,
              "max-response-delay": 60000,
              "max-ack-delay": 5000,
              "max-unacked-clients": 5,
              "sync-timeout": 60000,
              "multi-threading": {
                "enable-multi-threading": true,
                "http-dedicated-listener": true,
                "http-listener-threads": 0,
                "http-client-threads": 0
              },
              "peers": [
                {
                  "name": "server1",
                  "url": "http://192.168.1.10:8000/",
                  "role": "primary"
                },
                {
                  "name": "server2",
                  "url": "http://192.168.1.11:8000/",
                  "role": "secondary"
                }
              ]
            }
          ]
        }
      }
    ],
    "client-classes": [
      { "name": "HA_server1", "test": "member('ALL')" },
      { "name": "HA_server2", "test": "member('ALL')" }
    ],
    "subnet4": [
      {
        "id": 1,
        "subnet": "192.0.3.0/24",
        "pools": [
          { "pool": "192.0.3.100 - 192.0.3.150", "client-classes": ["HA_server1"] },
          { "pool": "192.0.3.151 - 192.0.3.200", "client-classes": ["HA_server2"] }
        ]
      }
    ]
  }
}
```

## Client Classification

Kea supports client classification based on packet attributes, options, and expressions. Classes can be used to assign specific options, restrict subnet access, or provide different configurations.

```json
{
  "Dhcp4": {
    "client-classes": [
      {
        "name": "VoIP",
        "test": "substring(option[60].hex,0,6) == 'Aastra'",
        "next-server": "192.0.2.254",
        "server-hostname": "tftp-server",
        "boot-file-name": "/voip/config.cfg",
        "option-data": [
          { "name": "domain-name-servers", "data": "10.1.1.1" }
        ]
      },
      {
        "name": "special_client",
        "test": "pkt4.mac == 0x010203040506",
        "option-data": [
          { "name": "domain-name-servers", "data": "127.0.0.1" }
        ]
      },
      {
        "name": "discovers",
        "test": "pkt4.msgtype == 1"
      },
      {
        "name": "broken_clients",
        "test": "pkt4.transid == 0"
      }
    ],
    "subnet4": [
      {
        "id": 1,
        "subnet": "192.0.2.0/24",
        "pools": [{ "pool": "192.0.2.1 - 192.0.2.200" }],
        "client-classes": ["VoIP"]
      },
      {
        "id": 2,
        "subnet": "192.0.3.0/24",
        "pools": [
          { "pool": "192.0.3.1 - 192.0.3.100", "client-classes": ["VoIP"] },
          { "pool": "192.0.3.101 - 192.0.3.200" }
        ]
      }
    ]
  }
}
```

## Shared Networks

Shared networks allow multiple subnets to coexist on the same physical network segment, useful when expanding address space or supporting different client types.

```json
{
  "Dhcp4": {
    "shared-networks": [
      {
        "name": "office-network",
        "interface": "eth1",
        "match-client-id": false,
        "authoritative": true,
        "renew-timer": 100,
        "rebind-timer": 150,
        "valid-lifetime": 200,
        "subnet4": [
          {
            "id": 1,
            "subnet": "10.0.0.0/8",
            "pools": [{ "pool": "10.0.0.1 - 10.0.0.254" }]
          },
          {
            "id": 2,
            "subnet": "192.0.2.0/24",
            "pools": [{ "pool": "192.0.2.1 - 192.0.2.254" }]
          }
        ]
      }
    ],
    "subnet4": [
      {
        "id": 3,
        "subnet": "192.0.3.0/24",
        "pools": [{ "pool": "192.0.3.1 - 192.0.3.200" }],
        "interface": "eth0"
      }
    ]
  }
}
```

## Dynamic DNS (DDNS) Configuration

Kea integrates with the D2 daemon (kea-dhcp-ddns) to perform dynamic DNS updates when leases are assigned or released.

```json
// DHCPv4 server configuration with DDNS
{
  "Dhcp4": {
    "dhcp-ddns": {
      "enable-updates": true,
      "server-ip": "127.0.0.1",
      "server-port": 53001,
      "sender-ip": "0.0.0.0",
      "sender-port": 0,
      "max-queue-size": 2048,
      "ncr-protocol": "UDP",
      "ncr-format": "JSON"
    },
    "ddns-send-updates": true,
    "ddns-override-no-update": true,
    "ddns-override-client-update": true,
    "ddns-replace-client-name": "when-present",
    "ddns-generated-prefix": "myhost",
    "ddns-qualifying-suffix": "example.com.",
    "ddns-update-on-renew": false,
    "ddns-conflict-resolution-mode": "check-with-dhcid"
  }
}

// D2 (kea-dhcp-ddns) configuration
{
  "DhcpDdns": {
    "ip-address": "127.0.0.1",
    "port": 53001,
    "dns-server-timeout": 1000,
    "control-socket": {
      "socket-type": "unix",
      "socket-name": "/tmp/kea-ddns-ctrl-socket"
    },
    "forward-ddns": {
      "ddns-domains": [
        {
          "name": "example.com.",
          "key-name": "rndc-key",
          "dns-servers": [
            { "ip-address": "172.16.1.1" }
          ]
        }
      ]
    },
    "reverse-ddns": {
      "ddns-domains": [
        {
          "name": "2.0.192.in-addr.arpa.",
          "key-name": "rndc-key",
          "dns-servers": [
            { "ip-address": "172.16.1.1", "port": 53 }
          ]
        }
      ]
    },
    "tsig-keys": [
      {
        "name": "rndc-key",
        "algorithm": "HMAC-SHA256",
        "secret": "base64encodedsecret=="
      }
    ]
  }
}
```

## Database Backend Configuration

Kea supports three lease storage backends: memfile (in-memory with file persistence), MySQL, and PostgreSQL. Database backends require hook libraries since Kea 2.7.4.

```json
// Memfile backend (default)
{
  "Dhcp4": {
    "lease-database": {
      "type": "memfile",
      "persist": true,
      "lfc-interval": 3600
    }
  }
}

// MySQL backend
{
  "Dhcp4": {
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_mysql.so" }
    ],
    "lease-database": {
      "type": "mysql",
      "name": "kea",
      "host": "localhost",
      "port": 3306,
      "user": "kea",
      "password": "kea_password",
      "reconnect-wait-time": 3000,
      "max-reconnect-tries": 3,
      "on-fail": "stop-retry-exit",
      "connect-timeout": 5
    }
  }
}

// PostgreSQL backend
{
  "Dhcp4": {
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_pgsql.so" }
    ],
    "lease-database": {
      "type": "postgresql",
      "name": "kea",
      "host": "localhost",
      "port": 5432,
      "user": "kea",
      "password": "kea_password",
      "reconnect-wait-time": 3000,
      "max-reconnect-tries": 3,
      "on-fail": "stop-retry-exit",
      "connect-timeout": 5
    }
  }
}

// Initialize database with kea-admin
# MySQL
kea-admin db-init mysql -u kea -p kea_password -n kea

# PostgreSQL
kea-admin db-init pgsql -u kea -p kea_password -n kea
```

## Statistics Commands

The stat_cmds hook library provides commands for retrieving lease statistics, especially useful in multi-server deployments with shared backends.

```json
// Load the hook library
{
  "Dhcp4": {
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_stat_cmds.so" }
    ]
  }
}

// stat-lease4-get: Get statistics for all subnets
{
  "command": "stat-lease4-get"
}

// stat-lease4-get: Get statistics for specific subnet
{
  "command": "stat-lease4-get",
  "arguments": {
    "subnet-id": 10
  }
}

// stat-lease4-get: Get statistics for subnet range
{
  "command": "stat-lease4-get",
  "arguments": {
    "subnet-range": {
      "first-subnet-id": 10,
      "last-subnet-id": 50
    }
  }
}

// Response format
{
  "result": 0,
  "text": "stat-lease4-get: 2 rows found",
  "arguments": {
    "result-set": {
      "columns": ["subnet-id", "total-addresses", "assigned-addresses", "declined-addresses"],
      "rows": [
        [10, 256, 100, 2],
        [20, 512, 200, 5]
      ]
    }
  }
}
```

## Hook Libraries Overview

Kea's functionality is extended through hook libraries. Each library provides specific features and can be loaded with optional parameters.

```json
{
  "Dhcp4": {
    "hooks-libraries": [
      { "library": "/usr/lib/kea/hooks/libdhcp_lease_cmds.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_stat_cmds.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_mysql.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_ha.so", "parameters": { } },
      {
        "library": "/usr/lib/kea/hooks/libdhcp_flex_id.so",
        "parameters": {
          "identifier-expression": "relay4[2].hex"
        }
      },
      {
        "library": "/usr/lib/kea/hooks/libdhcp_legal_log.so",
        "parameters": {
          "path": "/var/log/kea",
          "base-name": "kea-forensic4"
        }
      },
      { "library": "/usr/lib/kea/hooks/libdhcp_bootp.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_host_cmds.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_subnet_cmds.so" },
      { "library": "/usr/lib/kea/hooks/libdhcp_class_cmds.so" }
    ]
  }
}

// Available hook libraries:
// - libdhcp_lease_cmds.so: Lease management commands
// - libdhcp_stat_cmds.so: Statistics commands
// - libdhcp_ha.so: High Availability
// - libdhcp_mysql.so: MySQL backend
// - libdhcp_pgsql.so: PostgreSQL backend
// - libdhcp_host_cmds.so: Host reservation commands
// - libdhcp_subnet_cmds.so: Subnet management commands
// - libdhcp_class_cmds.so: Client class commands
// - libdhcp_flex_id.so: Flexible identifier
// - libdhcp_legal_log.so: Forensic logging
// - libdhcp_bootp.so: BOOTP support
// - libdhcp_ddns_tuning.so: DDNS tuning
// - libdhcp_ping_check.so: Ping check before lease
// - libdhcp_run_script.so: Run external scripts
```

## Summary

Kea DHCP server is designed for enterprise deployments requiring high performance, flexibility, and reliability. Its primary use cases include large-scale network deployments with centralized DHCP management, high-availability configurations with automatic failover, integration with existing infrastructure through database backends and DNS updates, and custom DHCP behavior through hook libraries and client classification. The JSON-based configuration and REST API enable automation and integration with network management systems.

The typical integration pattern involves configuring Kea with appropriate subnets and pools, enabling the control socket for runtime management, loading required hook libraries for extended functionality (lease commands, HA, statistics), setting up database backends for persistent storage in multi-server environments, and integrating with D2 for dynamic DNS updates. Kea's modular architecture allows operators to enable only the features they need while maintaining consistent performance across IPv4 and IPv6 deployments.