# 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)
