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

284 lines
9.9 KiB
Markdown
Raw 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](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 `<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
```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)
Reference in New Issue View Git Blame Copy Permalink