Post cover image

July 21, 2026

DHCP avec Kea sur Debian 13 : Guide Complet et API REST

Dans le monde de l’infrastructure réseau, le protocole DHCP (Dynamic Host Configuration Protocol) est un pilier fondamental. Il permet…

By ATTE-THM

5 min read

Dans le monde de l'infrastructure réseau, le protocole DHCP (Dynamic Host Configuration Protocol) est un pilier fondamental. Il permet d'attribuer automatiquement des adresses IP aux machines, simplifiant ainsi la gestion d'un parc informatique. Pendant des années, ISC DHCP a été la solution de référence. Mais aujourd'hui, Kea s'impose comme le successeur moderne, plus performant, flexible et riche en fonctionnalités.

Cet article est un guide pas-à-pas pour installer et configurer Kea DHCP sur un serveur Debian 13 (nom de code Trixie). Nous irons plus loin que la configuration de base en activant et en utilisant son API REST, une fonctionnalité clé pour l'automatisation et l'intégration dans des environnements de cloud ou de datacenter.

Mon labo est simple : un serveur Debian 13 avec une interface réseau ens33 qui fera office de serveur DHCP, et une machine cliente sous Windows 10 pour la validation

1. Prérequis et Installation de Kea

Commencez par mettre à jour votre système Debian.

sudo apt update && sudo apt upgrade -y

Installez ensuite les paquets Kea et les outils nécessaires pour interagir avec l'API.

# Installation de Kea
sudo apt install kea-dhcp4-server kea-ctrl-agent

# Installation des outils pour l'API
sudo apt install curl jq

Kea-dhcp4-server : Le cœur du serveur DHCP. Kea-ctrl-agent : Le service qui expose l'API REST. curl et jq : Respectivement, pour envoyer des requêtes HTTP et pour formater les réponses JSON de l'API.

2. Configuration de l'Interface Réseau du Serveur

Avant de configurer Kea, assurons-nous que notre interface réseau (ens33) a une adresse IP statique. Pour ce guide, le serveur DHCP aura l'IP 192.168.2.1 sur le réseau 192.168.2.0/24.

Sur Debian, nous allons configurer le fichier /etc/network/interfaces. Éditez le fichier de configuration :

sudo nano /etc/network/interfaces

Ajoutez la configuration suivante :

# Configuration statique pour ens33
auto ens33
iface ens33 inet static
    address 192.168.2.1
    netmask 255.255.255.0
    network 192.168.2.0
    broadcast 192.168.2.255

Puis redémarrez le réseau :

sudo systemctl restart networking
# ou
sudo ifdown ens33 && ifup ens33

Activer le forwarding IP (optionnel mais recommandé)

# Activer le forwarding IPv4
echo 1 > /proc/sys/net/ipv4/ip_forward

# Le rendre permanent
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf

3. Configuration du Serveur DHCP Kea (kea-dhcp4)

Le fichier de configuration principal est /etc/kea/kea-dhcp4.conf. Nous allons le configurer pas-à-pas.

Ouvrez le fichier avec sudo nano /etc/kea/kea-dhcp4.conf et collez le contenu suivant.

{
    "Dhcp4": {
        "interfaces-config": {
            "interfaces": [ "ens33" ]
        },
        "hooks-libraries": [
            {
                "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_lease_cmds.so"
            },
            {
                "library": "/usr/lib/x86_64-linux-gnu/kea/hooks/libdhcp_stat_cmds.so"
            }
        ],
        "subnet4": [
            {
                "id": 1,
                "subnet": "192.168.2.0/24",
                "pools": [ { "pool": "192.168.2.10 - 192.168.2.100" } ],
                "option-data": [
                    {
                        "name": "routers",
                        "data": "192.168.2.1"
                    },
                    {
                        "name": "domain-name-servers",
                        "data": "8.8.8.8, 1.1.1.1"
                    },
                    {
                        "name": "domain-name",
                        "data": "atte-thm.lab"
                    }
                ]
            }
        ],
        "control-socket": {
            "socket-type": "unix",
            "socket-name": "/run/kea/kea4-ctrl-socket"
        },
        "authoritative": true,
        "lease-database": {
            "type": "memfile",
            "name": "/var/lib/kea/kea-leases4.csv"
        },
        "valid-lifetime": 7200,
        "renew-timer": 3600,
        "rebind-timer": 5400,
        "loggers": [
            {
                "name": "kea-dhcp4",
                "output_options": [
                    {
                        "output": "/var/log/kea/kea-dhcp4.log",
                        "flush": true,
                        "maxsize": 104857600,
                        "maxver": 10
                    },
                    {
                        "output": "stdout"
                    }
                ],
                "severity": "INFO"
            }
        ]
    }
}

Explication des paramètres :

  • interfaces-config : L'interface sur laquelle Kea écoutera les requêtes DHCP.
  • hooks-libraries : Charge la bibliothèque qui permet de gérer les baux via l'API.
  • subnet4 : Définit le réseau, la plage d'adresses distribuées, et les options (passerelle, DNS).
  • control-socket : Crée un socket Unix pour la communication avec le Control Agent.

Testez la syntaxe de votre configuration :

sudo kea-dhcp4 -t /etc/kea/kea-dhcp4.conf

Si tout est bon, vous devriez voir un message indiquant que la configuration est valide.

4. Gestion des Permissions et Démarrage

Kea tourne sous l'utilisateur système _kea. Il est crucial de donner à cet utilisateur l'accès aux bons répertoires.

# Créer les répertoires
sudo mkdir -p /run/kea /var/run/kea /var/lib/kea

# Donner la propriété à l'utilisateur _kea
sudo chown -R _kea:_kea /run/kea /var/run/kea /var/lib/kea
sudo chmod -R 755 /run/kea /var/run/kea /var/lib/kea

# Vérifier la présence de l'utilisateur
id _kea

Démarrez maintenant le service DHCP et activez-le au démarrage :

sudo systemctl start kea-dhcp4-server
sudo systemctl enable kea-dhcp4-server
sudo systemctl status kea-dhcp4-server

5. Configuration du Control Agent (L'API REST)

C'est ici que la magie opère. Le Control Agent (kea-ctrl-agent) est un serveur HTTP qui agit comme un pont entre l'API et le socket Unix du serveur DHCP.

Créez son fichier de configuration : /etc/kea/kea-ctrl-agent.conf

sudo nano /etc/kea/kea-ctrl-agent.conf

Copiez cette configuration :

{
    "Control-agent": {
        "http-host": "127.0.0.1",
        "http-port": 8000,
        "control-sockets": {
            "dhcp4": {
                "socket-type": "unix",
                "socket-name": "/run/kea/kea4-ctrl-socket"
            }
        }
    }
}

Le Control Agent écoutera en local sur le port 8000. Il utilisera le socket Unix créé par le serveur DHCP.

Sécurisons l'API avec un mot de passe :

Créez un fichier pour stocker le mot de passe :

sudo nano /etc/kea/kea-api-password

Mettre un bon mot de passe. Pour mon cas de test, j'ai mit: password123

None 
# Changer le propriétaire pour que seul kea puisse le lire
sudo chown _kea:_kea /etc/kea/kea-api-password
sudo chmod 640 /etc/kea/kea-api-password

Note : Dans cet exemple, pour simplifier, je n'ai pas activé l'authentification au niveau de la configuration, car elle est souvent gérée par un proxy externe. Cependant, il est fortement recommandé d'ajouter une couche d'authentification (HTTP Basic Auth via un reverse proxy comme Nginx) pour exposer l'API en production.

Démarrez le Control Agent :

sudo systemctl start kea-ctrl-agent
sudo systemctl enable kea-ctrl-agent
sudo systemctl status kea-ctrl-agent

6. Interaction avec l'API REST

Voilà le moment tant attendu : interagir avec notre serveur DHCP via l'API.

Vérification du client Windows 10

Pendant ce temps, un client Windows 10 a reçu une IP.

Sur le serveur, observez les logs pour voir son arrivée :

sudo journalctl -u kea-dhcp4-server -f

Vous devriez voir une ligne similaire :

DHCP4_LEASE_ALLOC [hwtype=1 00:0c:29:bb:b7:05], cid=[...], address=192.168.2.10

Commandes fondamentales via curl

L'API accepte des commandes au format JSON. Le client Windows a l'adresse 192.168.2.10, nous allons l'utiliser pour nos exemples.

  1. Liste de toutes les commandes disponibles :
curl -X POST -H "Content-Type: application/json" \
-d '{"command": "list-commands", "service": ["dhcp4"]}' \
http://127.0.0.1:8000/ | jq .
  1. Voir la configuration complète :
curl -X POST -H "Content-Type: application/json" \
-d '{"command": "config-get", "service": ["dhcp4"]}' \
http://127.0.0.1:8000/ | jq .
  1. Récupérer tous les baux du sous-réseau 1 :
curl -X POST -H "Content-Type: application/json" \
-d '{"command": "lease4-get-all", "service": ["dhcp4"], "arguments": {"subnets": [1]}}' \
http://127.0.0.1:8000/ | jq .

Le résultat devrait ressembler à ceci :

[
  {
    "arguments": {
      "leases": [
        {
          "ip-address": "192.168.2.10",
          "hw-address": "00:0c:29:bb:b7:05",
          "hostname": "desktop-d3d1dnj",
          "valid-lft": 7200,
          "subnet-id": 1,
          "state": 0
        }
      ]
    }
  }
]
  1. Ajouter un bail statique (utile pour les imprimantes, serveurs) :
curl -X POST -H "Content-Type: application/json" \
-d '{"command": "lease4-add", "service": ["dhcp4"], "arguments": {"ip-address": "192.168.2.50", "hw-address": "aa:bb:cc:dd:ee:ff", "subnet-id": 1, "valid-lft": 3600, "hostname": "imprimante-bureau"}}' \
http://127.0.0.1:8000/ | jq .
  1. Récupérer un bail par adresse MAC :
curl -X POST -H "Content-Type: application/json" \
-d '{"command": "lease4-get-by-hw-address", "service": ["dhcp4"], "arguments": {"hw-address": "00:0c:29:bb:b7:05"}}' \
http://127.0.0.1:8000/ | jq .

7. Astuces et Automatisation avec des Alias

Pour ne pas avoir à retaper ces longues commandes, ajoutez des alias à votre ~/.bashrc.

nano ~/.bashrc

Ajoutez ces lignes :

# --- Alias pour l'API Kea ---
alias kea-list='curl -X POST -s -H "Content-Type: application/json" -d '\''{"command": "lease4-get-all", "service": ["dhcp4"], "arguments": {"subnets": [1]}}'\'' http://127.0.0.1:8000/ | jq .'
alias kea-status='curl -X POST -s -H "Content-Type: application/json" -d '\''{"command": "status-get", "service": ["dhcp4"]}'\'' http://127.0.0.1:8000/ | jq .'
alias kea-config='curl -X POST -s -H "Content-Type: application/json" -d '\''{"command": "config-get", "service": ["dhcp4"]}'\'' http://127.0.0.1:8000/ | jq .'
alias kea-commands='curl -X POST -s -H "Content-Type: application/json" -d '\''{"command": "list-commands", "service": ["dhcp4"]}'\'' http://127.0.0.1:8000/ | jq .'

Rechargez le fichier :

source ~/.bashrc

Maintenant, tapez simplement kea-list pour voir vos baux !

Conclusion

Vous avez réussi à installer et configurer Kea DHCP sur Debian 13. Vous avez non seulement un serveur DHCP fonctionnel, mais vous avez également mis en place son API REST, vous permettant désormais d'intégrer la gestion de vos adresses IP dans vos scripts d'automatisation, votre infrastructure en tant que code (IaC), ou tout simplement pour une administration centralisée plus efficace.

Kea offre bien d'autres possibilités : la haute disponibilité (HA), le stockage des baux dans une base de données (PostgreSQL, MySQL), ou encore la gestion des réservations par hostname. L'aventure ne fait que commencer !

Si vous avez des questions ou des retours, n'hésitez pas à commenter cet article.

Bonne administration !