gilles/ipwatch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
ipwatch/tuto_migration_isc_vers_kea.md
gilles dff1b03e42 ipwatch
2026-02-07 16:57:37 +01:00

9.9 KiB
Raw Permalink Blame History

Tutoriel : Migration ISC DHCP vers Kea DHCP sur OPNsense

Pourquoi migrer ?

ISC DHCP est End-of-Life (fin de vie) et ne recoit plus de mises a jour ni de correctifs de securite. OPNsense recommande fortement la migration vers Kea (ou Dnsmasq).

Kea apporte :

  • Une API REST complete (CRUD sur les reservations, baux, subnets)
  • La haute disponibilite (HA) native
  • Un support actif et des mises a jour regulieres
  • Une meilleure integration avec IPWatch (gestion des reservations via API)

Important

: ISC DHCP n'a PAS d'API pour gerer les mappages statiques. Kea expose des endpoints complets (add_reservation, del_reservation, etc.) C'est la raison principale pour laquelle IPWatch necessite Kea.

Pre-requis

  • OPNsense version 24.x ou superieure (Kea est inclus depuis la v24)
  • Acces administrateur a l'interface web OPNsense
  • Sauvegarder la configuration actuelle avant toute modification
  • Lister les mappages statiques actuels (pour verification post-migration)
  • Prevoir une fenetre de maintenance (courte coupure DHCP possible)

Etape 1 : Inventaire de la configuration ISC actuelle

Avant de toucher a quoi que ce soit, noter la configuration actuelle :

  1. Aller dans Services > ISC DHCPv4 > [Interface LAN]
  2. Noter :
    • Plage DHCP : IP debut et IP fin du pool dynamique
    • Serveurs DNS distribues
    • Passerelle (gateway) distribuee
    • Domaine distribue
    • Duree du bail (lease time)
  3. Aller dans l'onglet Static Mappings (en bas de la page)
  4. Lister tous les mappages statiques :
    • Prendre une capture d'ecran ou noter : MAC | IP | Hostname | Description
    • Ce sont les reservations a migrer vers Kea

Astuce : Si tu as beaucoup de mappages, exporte la config complete dans System > Configuration > Backups > Download (fichier config.xml). Ce fichier contient tous les static mappings dans les noeuds <staticmap>.

Etape 2 : Configurer Kea DHCP (sans l'activer)

On prepare Kea AVANT de desactiver ISC. Ainsi la bascule sera quasi-instantanee.

2.1 Creer les Subnets

  1. Aller dans Services > Kea DHCP > DHCPv4 > Subnets
  2. Cliquer + pour ajouter un subnet
  3. Remplir :
    • Subnet : 10.0.0.0/22 (ton reseau, adapter selon ta config)
    • Pools : definir la plage dynamique, ex: 10.0.1.100 - 10.0.1.254
      • ⚠️ Les reservations statiques doivent etre EN DEHORS de cette plage
    • Routers : 10.0.0.1 (passerelle)
    • DNS Servers : 10.0.0.1 (ou tes serveurs DNS)
    • Domain Name : ton domaine local (ex: local)
    • Valid Lifetime : duree du bail en secondes (ex: 86400 pour 24h)
  4. Sauvegarder (ne pas encore activer le service)

Note

: Si tu as plusieurs VLANs/sous-reseaux, creer un subnet par VLAN.

2.2 Activer le Control Agent (recommande)

  1. Aller dans Services > Kea DHCP > Control Agent
  2. Cocher Enabled
  3. Bind address : 127.0.0.1
  4. Bind port : 8000
  5. Sauvegarder

Le Control Agent expose l'API REST locale de Kea, utile pour le monitoring et la HA.

Etape 3 : Migrer les mappages statiques

Option A : Migration manuelle (peu de mappages, < 10)

Pour chaque mappage statique ISC :

  1. Aller dans Services > Kea DHCP > DHCPv4 > Reservations
  2. Cliquer + pour ajouter
  3. Remplir :
    • Subnet : selectionner le subnet cree a l'etape 2
    • IP address : l'IP fixe (ex: 10.0.0.5)
    • MAC address : l'adresse MAC du client (ex: AA:BB:CC:DD:EE:FF)
    • Hostname : le nom d'hote (ex: debian-vm5)
    • Description : Migration depuis ISC DHCP (ou description originale)
  4. Sauvegarder
  5. Repeter pour chaque mappage

Option B : Migration automatique avec l'outil communautaire (beaucoup de mappages)

Un outil gratuit existe : Migration Tool

Etapes :

  1. Exporter la config OPNsense :

    • Aller dans System > Configuration > Backups
    • Cliquer Download configuration
    • Tu obtiens un fichier config.xml

  2. Telecharger l'outil Migration :

    # Sur Linux :
wget https://github.com/EasyG0ing1/Migration/releases/latest/download/migrate-linux
chmod +x migrate-linux

  3. Executer la migration :

    # Placer config.xml dans le meme dossier
./migrate-linux
    • L'outil lit les <staticmap> de ISC DHCP dans le config.xml
    • Il les convertit en reservations Kea
    • Il genere un fichier new_config.xml

  4. Importer dans OPNsense :

    • Aller dans System > Configuration > Backups
    • Cliquer Restore configuration et selectionner new_config.xml
    • ⚠️ Decocher "Reboot after restore" !
    • Cliquer Restore

  5. Verifier les reservations dans Services > Kea DHCP > DHCPv4 > Reservations

Option C : Migration via OPNsense 25.7+ (si disponible)

A partir de la version 25.7, OPNsense propose des options d'export integrees pour faciliter la transition des baux statiques. Verifier dans :

  • Services > ISC DHCPv4 → bouton Export (si present)

Etape 4 : Basculer d'ISC vers Kea

C'est l'etape critique. Les deux services ne peuvent PAS tourner en meme temps sur la meme interface.

4.1 Desactiver ISC DHCP

  1. Aller dans Services > ISC DHCPv4 > [Chaque interface]
  2. Decocher "Enable DHCP server on [interface]"
  3. Sauvegarder
  4. Repeter pour chaque interface configuree

4.2 Activer Kea DHCP

  1. Aller dans Services > Kea DHCP > DHCPv4 > Settings
  2. Cocher Enabled
  3. Selectionner les Interfaces (ex: LAN, VLAN10, etc.)
  4. Cocher Firewall rules (ajoute automatiquement les regles necessaires)
  5. Cliquer Save
  6. Cliquer Apply pour demarrer le service

Temps d'arret : Quelques secondes entre la desactivation d'ISC et l'activation de Kea. Les clients existants conservent leur bail actuel, donc pas de coupure immediate.

Etape 5 : Verification post-migration

5.1 Verifier le service

  1. Aller dans Services > Kea DHCP > DHCPv4 > Settings
  2. Le badge doit afficher "Running" (vert)
  3. Verifier aussi dans System > Diagnostics > Services que kea-dhcp4 est actif

5.2 Verifier les reservations

  1. Services > Kea DHCP > DHCPv4 > Reservations
  2. Comparer avec ta liste de l'etape 1 : toutes les IPs/MAC sont presentes ?

5.3 Tester l'attribution DHCP

  1. Sur un client, renouveler le bail :
    • Linux : sudo dhclient -r && sudo dhclient
    • Windows : ipconfig /release && ipconfig /renew
    • Mac : Preferences Systeme > Reseau > Renouveler le bail DHCP
  2. Verifier que le client recoit la bonne IP (surtout pour les reservations statiques)

5.4 Verifier les logs

  1. Services > Kea DHCP > Log File
  2. Chercher les messages d'attribution (DHCPACK) et d'erreur
  3. Pas de warnings = migration reussie

5.5 Verifier la resolution DNS

Si tu utilises Unbound avec registrations DHCP :

  • ⚠️ Kea ne synchronise PAS automatiquement les noms dynamiques avec Unbound
  • Seules les reservations statiques sont synchronisees
  • Pour les clients dynamiques, il faut creer des host overrides manuellement (ou via IPWatch !)

Etape 6 : Nettoyage

  1. Verifier pendant 24-48h que tout fonctionne (renouvellement des baux)
  2. Ne pas supprimer ISC DHCP tout de suite (garder en backup)
  3. Une fois satisfait, tu peux desinstaller le plugin ISC si souhaite

Etape 7 : Configurer l'API pour IPWatch

Maintenant que Kea est actif, IPWatch peut utiliser l'API complete :

7.1 Creer une cle API OPNsense (si pas deja fait)

  1. System > Access > Users
  2. Creer un utilisateur dedie (ex: ipwatch_api) ou utiliser l'existant
  3. Dans l'onglet API Keys, cliquer + pour generer une paire key/secret
  4. Sauvegarder le key et le secret

7.2 Tester la connexion API

# Tester depuis la machine IPWatch :
curl -k -u "KEY:SECRET" https://10.0.0.1/api/core/service/search

# Verifier que kea-dhcp4 apparait dans les services :
curl -k -u "KEY:SECRET" https://10.0.0.1/api/kea/dhcpv4/search_reservation

7.3 Configurer dans IPWatch

Ajouter dans config.yaml :

opnsense:
  enabled: true
  host: "10.0.0.1"
  api_key: "ta_cle_api"
  api_secret: "ton_secret_api"
  verify_ssl: false  # si certificat auto-signe
  sync_interval: 300  # secondes entre chaque synchro

Resume des endpoints Kea disponibles apres migration

Action Endpoint Methode
Lister reservations /api/kea/dhcpv4/search_reservation GET/POST
Detail reservation /api/kea/dhcpv4/get_reservation/{uuid} GET
Ajouter reservation /api/kea/dhcpv4/add_reservation POST
Modifier reservation /api/kea/dhcpv4/set_reservation/{uuid} POST
Supprimer reservation /api/kea/dhcpv4/del_reservation/{uuid} POST

Champs : subnet, ip_address, hw_address, hostname, description

Depannage

Probleme Solution
Kea ne demarre pas Verifier les logs dans Services > Kea DHCP > Log File
Client ne recoit pas d'IP Verifier que l'interface est selectionnee dans Settings
Reservation ne fonctionne pas Verifier que l'IP est hors du pool dynamique
Conflit d'IP Deux clients avec le meme MAC ? Verifier les doublons
API ne repond pas Verifier le Control Agent (port 8000) et la cle API
DNS ne resout plus les noms Creer des host overrides Unbound pour les clients dynamiques

Sources

Reference in New Issue View Git Blame Copy Permalink