Latest revision as of 22:23, 21 January 2025

Summary

ISC Kea is an open-source, high-performance Dynamic Host Configuration Protocol (DHCP) server developed by the Internet Systems Consortium (ISC). It is designed to provide DHCP services for IPv4 and IPv6 networks, including the allocation of IP addresses, network configuration parameters, and dynamic updates. ISC Kea is the successor to ISC's earlier DHCP server software, ISC DHCP, and is built to offer improved scalability, flexibility, and extensibility.

Configuration

Control

Info: keactrl is only available if you compile kea from source.

Get DHCP4 Server Status

keactrl status -s dhcp4

Reload DHCP4 Server

You'll want to do this after making changes to the kea-dhcp4.conf file.

keactrl reload -s dhcp4

Leases

Leases are stored in memfile, by default. But you can also have them written to a CSV file:

"lease-database": {
    "type": "memfile", // write leases to memfile...
    "persist": true,
    "name": "/tmp/kea-leases4.csv", // ...but also write them to csv
    "lfc-interval": 3600,
    "max-row-errors": 100
},

MySQL

To use host reservations from MySQL, you need to add the "hosts-database" section to the "Dhcp4" section of the config file, like this:

"hosts-database": {
    "type": "mysql",
    "name": "kea_db",
    "user": "kea-user",
    "password": "{password}",
    "host": "localhost",
    "port": 3306
},

Subnet-Ids need to be defined in your subnet declarations, too.

You can use both the hosts database and the configuration file for host reservations at the same time.

IPv4 Reservations

SELECT host_id,dhcp_identifier,dhcp4_subnet_id,ipv4_address,hostname FROM hosts;

Insert Statement Example:

START TRANSACTION;
SET @ipv4_reservation='10.10.0.16';
SET @hostname = 'hostname';
SET @identifier_type='hw-address';
SET @identifier_value='be:ef:be:ef:be:ef';
SET @dhcp4_subnet_id=10;

INSERT INTO hosts (dhcp_identifier,
   dhcp_identifier_type,
   dhcp4_subnet_id,
   ipv4_address,
   hostname)
VALUES (UNHEX(REPLACE(@identifier_value, ':', '')),
   (SELECT type FROM host_identifier_type WHERE name=@identifier_type),
    @dhcp4_subnet_id,
    INET_ATON(@ipv4_reservation),
    @hostname);

COMMIT;

Info: IP Address get stored in the db in decimal format.

Manual Dump of Host Reservations

mysqldump -u kea-user -p kea_db hosts > kea-hosts.sql

Sync db From Primary to Standby Peers

Follow the steps below to configure a Standby peer to sync its hosts db from the Primary peer. We will create a MySQL user kea-xfer with just enough privileges to be able to sync the hosts table.

Info: Assume that net1 is the Primary and net2 is the Standby peer you want to sync to.

Do on Primary Peer

CREATE USER 'kea-xfer'@'localhost' IDENTIFIED BY '{password}';
CREATE USER 'kea-xfer'@'net2.lambnet.us' IDENTIFIED BY '{password}';
GRANT SELECT ON `kea_db`.`hosts` TO 'kea-xfer'@'localhost';
GRANT SELECT ON `kea_db`.`hosts` TO 'kea-xfer'@'net2.lambnet.us';

Do on Standby Peer

CREATE USER 'kea-xfer'@'localhost' IDENTIFIED BY '{password}';
GRANT LOCK TABLES ON `kea_db`.* TO `kea-xfer`@`localhost`;
GRANT REFERENCES ON `kea_db`.`host_identifier_type` TO `kea-xfer`@`localhost`;
GRANT SELECT, INSERT, CREATE, DROP, ALTER ON `kea_db`.`hosts` TO `kea-xfer`@`localhost`;

Crontab for use on Standby peers

Use this crontab to automatically sync a Standby peer with the Primary peer's kea_db.hosts table (i.e., push from Primary to Standby).

*/5 * * * *  mysqldump -h net1.lambnet.us -u kea-xfer -p{password} --single-transaction --no-tablespaces kea_db hosts | mysql -u kea-xfer -p{password} kea_db

MySQL Performance Tuning

Configure in /etc/mysql/my.cnf:

[mysqld]
innodb_flush_log_at_trx_commit=2

SystemD Tip

You may encounter an issue where kea-dhcp4 fails to start at boot. Try adding this to /usr/lib/systemd/system/kea-dhcp4.service, at the end of the [Unit] section:

After=mysqld.service

Kea-Shell

Commands

[ { "arguments": [ "build-report", "config-backend-pull", "config-get", "config-reload", "config-set", "config-test", "config-write", "dhcp-disable", "dhcp-enable", "ha-continue", "ha-heartbeat", "ha-maintenance-cancel", "ha-maintenance-notify", "ha-maintenance-start", "ha-reset", "ha-scopes", "ha-sync", "ha-sync-complete-notify", "lease4-add", "lease4-del", "lease4-get", "lease4-get-all", "lease4-get-by-client-id", "lease4-get-by-hostname", "lease4-get-by-hw-address", "lease4-get-page", "lease4-resend-ddns", "lease4-update", "lease4-wipe", "lease6-add", "lease6-bulk-apply", "lease6-del", "lease6-get", "lease6-get-all", "lease6-get-by-duid", "lease6-get-by-hostname", "lease6-get-page", "lease6-resend-ddns", "lease6-update", "lease6-wipe", "leases-reclaim", "libreload", "list-commands", "server-tag-get", "shutdown", "statistic-get", "statistic-get-all", "statistic-remove", "statistic-remove-all", "statistic-reset", "statistic-reset-all", "statistic-sample-age-set", "statistic-sample-age-set-all", "statistic-sample-count-set", "statistic-sample-count-set-all", "status-get", "version-get" ], "result": 0 } ]

Get Status

kea-shell --host net2.lambnet.us --service dhcp4 status-get

Info: Don't forget to press Ctrl+D after sending a kea-shell command.

Links

ISC-Kea: https://kea.readthedocs.io/en/latest/arm/config.html
Stork: https://stork.readthedocs.io/en/v1.8.0/; https://gitlab.isc.org/isc-projects/stork/-/wikis/Screenshots