# 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 ``. --- ## 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](https://github.com/EasyG0ing1/Migration) **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** : ```bash # Sur Linux : wget https://github.com/EasyG0ing1/Migration/releases/latest/download/migrate-linux chmod +x migrate-linux ``` 3. **Executer la migration** : ```bash # Placer config.xml dans le meme dossier ./migrate-linux ``` - L'outil lit les `` 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 ```bash # 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` : ```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 - [Documentation officielle Kea DHCP OPNsense](https://docs.opnsense.org/manual/kea.html) - [Documentation ISC DHCP (EOL)](https://docs.opnsense.org/manual/isc.html) - [Guide migration homenetworkguy.com](https://homenetworkguy.com/how-to/migrate-from-isc-dhcp-to-dnsmasq-or-kea-dhcp-in-opnsense/) - [Outil de migration communautaire](https://github.com/EasyG0ing1/Migration) - [Forum OPNsense - Migration ISC vers Kea](https://forum.opnsense.org/index.php?topic=40359.0) - [Forum OPNsense - Migration 25.7](https://forum.opnsense.org/index.php?topic=48030.0)