249 lines
8.1 KiB
Markdown
249 lines
8.1 KiB
Markdown
# prompt.md — Développement NetUI (Debian 13 / Passerelle LAN→Internet)
|
||
|
||
## Contexte
|
||
|
||
Tu es un assistant de développement (compatible Codex et Claude Code). Tu m’aides à construire une application **NetUI** : une **WebUI** d’administration réseau pour une **VM Debian 13 (Trixie)** jouant le rôle de **passerelle LAN → Internet** (NAT + pare-feu + DHCP + DNS).
|
||
|
||
Le serveur est une VM Proxmox nommée côté hyperviseur `mon-reseau`, mais **le nom système Debian** est :
|
||
- **hostname** : `server-home`
|
||
- **domaine** : `home`
|
||
- **FQDN** : `server-home.home`
|
||
|
||
Je me connecte en **SSH via VS Code** sur la VM.
|
||
|
||
### Contraintes impératives
|
||
|
||
1) **Aucun dépôt tiers** : uniquement les paquets des dépôts officiels Debian 13.
|
||
2) L’application doit utiliser **uniquement les outils réseau standard Debian**.
|
||
3) La WebUI est en **français**, pensée pour des **utilisateurs novices** :
|
||
- libellés explicites
|
||
- explications claires en info-bulles (tooltips)
|
||
- **éviter les acronymes** ; si un terme technique est nécessaire, l’expliquer en toutes lettres.
|
||
4) L’application est servie via **Nginx**.
|
||
5) L’accès WebUI est **limité au réseau local (LAN)**.
|
||
6) Au début (V1), on accepte une approche **permissive** sur les droits (sudo large), puis on durcira.
|
||
7) L’utilisateur système est **`gilles`** (ne pas créer de nouvel utilisateur).
|
||
8) Le dépôt Git est sur mon Gitea : `https://gitea.maison43.duckdns.org/gilles/netui.git`
|
||
|
||
---
|
||
|
||
## Périmètre fonctionnel V1 (à livrer)
|
||
|
||
NetUI V1 est composée de modules/pages :
|
||
|
||
1) **Réseau** (WAN/LAN)
|
||
- afficher l’état : adresses, routes, passerelle, serveurs de noms
|
||
- configurer WAN (adresse automatique ou fixe)
|
||
- configurer LAN (adresse fixe, domaine local)
|
||
|
||
2) **Pare-feu et partage de connexion**
|
||
- configuration **nftables** : règles de base + NAT
|
||
- mode novice : interrupteurs simples et règles prédéfinies compréhensibles
|
||
|
||
3) **Attribution d’adresses (DHCP)**
|
||
- serveur DHCP : **Kea DHCPv4**
|
||
- plages dynamiques, exclusions, réservations (adresse fixe par appareil)
|
||
- liste des appareils connectés (baux)
|
||
|
||
4) **Noms (DNS)**
|
||
- serveur DNS local : **Unbound**
|
||
- serveurs amont, entrées locales (nom → adresse)
|
||
|
||
5) **Services**
|
||
- page dédiée pour : installer (via `apt`), activer au démarrage, démarrer/arrêter
|
||
- services concernés V1 : nftables, kea-dhcp4-server, unbound, chrony
|
||
|
||
6) **Journaux (Logs)**
|
||
- afficher les logs des services avec filtres (date, texte, niveau)
|
||
- source : `journalctl`
|
||
|
||
7) **Activité réseau**
|
||
- afficher connexions actives (LAN → Internet) en langage clair
|
||
- afficher activité DNS (qui demande quel nom)
|
||
- afficher événements pare-feu (autorisé / bloqué)
|
||
- sources : `conntrack`, logs Unbound, logs nftables
|
||
|
||
8) **Migration DHCP sans casser le réseau**
|
||
- fonction d’import **depuis OPNsense** (CSV et XML) et **JSON**
|
||
- tout est normalisé vers un **format JSON canonique interne**
|
||
- génération de réservations DHCP à partir de l’import
|
||
- aucune application automatique sans validation
|
||
|
||
---
|
||
|
||
## Paquets Debian (référence)
|
||
|
||
Paquets attendus (installation manuelle possible) :
|
||
- WebUI/Backend : `nginx`, `python3`, `python3-venv`, `python3-pip`
|
||
- Réseau : `iproute2`, `systemd-networkd`, `systemd-resolved`
|
||
- Pare-feu/NAT : `nftables`
|
||
- Connexions : `conntrack`
|
||
- DHCP : `kea-dhcp4-server`
|
||
- DNS : `unbound`
|
||
- Temps : `chrony`
|
||
- Logs/diag : `rsyslog`, `tcpdump`, `ethtool`
|
||
- Dev : `git`
|
||
|
||
---
|
||
|
||
## Architecture technique souhaitée
|
||
|
||
### Serveur web
|
||
- Nginx sert le **frontend statique** et reverse-proxy `/api/` vers le backend.
|
||
- Le backend écoute sur `127.0.0.1:8000`.
|
||
- Nginx est configuré pour autoriser uniquement le réseau LAN (allow/deny).
|
||
|
||
### Backend
|
||
- Langage : **Python**
|
||
- Framework : **FastAPI**
|
||
- Validation : Pydantic
|
||
- Génération de configuration : templates + rendu
|
||
- Stockage config : fichier unique **source de vérité** : `/etc/netui/config.yaml`
|
||
|
||
### Frontend
|
||
- Simple : HTML/CSS/JS (pas de SPA lourde)
|
||
- Interface par **onglets**
|
||
- Style : **Gruvbox dark seventies** (contraste élevé, lisible)
|
||
|
||
### Exécution et droits (V1)
|
||
- Le backend est lancé sous l’utilisateur `gilles`.
|
||
- Les opérations système se font via `sudo` (V1 permissif).
|
||
- Ne pas activer automatiquement les services réseau tant que l’utilisateur n’a pas cliqué « Appliquer ».
|
||
|
||
---
|
||
|
||
## Exigences UX (très important)
|
||
|
||
- Tout champ de formulaire doit avoir :
|
||
- un libellé clair
|
||
- un exemple
|
||
- une info-bulle expliquant « à quoi ça sert »
|
||
- Bannière « Mode test » si la configuration n’est pas appliquée.
|
||
- Boutons distincts :
|
||
- **Générer** (préparer fichiers sans appliquer)
|
||
- **Tester** (vérifier syntaxe/cohérence)
|
||
- **Appliquer** (écrire + recharger services)
|
||
- Messages d’erreur en français, orientés solution.
|
||
|
||
---
|
||
|
||
## Règles de sécurité et de robustesse
|
||
|
||
1) **Jamais deux serveurs DHCP actifs** sur le LAN.
|
||
2) Appliquer une configuration en deux phases :
|
||
- écrire dans un répertoire de staging
|
||
- tester :
|
||
- Kea : validation de config
|
||
- nftables : validation (`nft -c`)
|
||
- unbound : validation (`unbound-checkconf`)
|
||
- basculer et recharger
|
||
3) Toujours prévoir un rollback (V2), mais en V1 au minimum : sauvegarde du dernier état avant « Appliquer ».
|
||
4) Journaliser toute action (qui / quoi / quand).
|
||
|
||
---
|
||
|
||
## Imports DHCP depuis OPNsense
|
||
|
||
### Objectif
|
||
Conserver les adresses IP existantes en important des réservations/baux puis en générant des réservations DHCP Kea.
|
||
|
||
### Sources d’import
|
||
- **OPNsense CSV** (baux ou réservations)
|
||
- **OPNsense XML** (export config)
|
||
- **JSON** (format pivot)
|
||
|
||
### Format JSON canonique interne (à utiliser partout)
|
||
|
||
```json
|
||
{
|
||
"source": "opnsense",
|
||
"interface": "lan",
|
||
"reservations": [
|
||
{
|
||
"nom": "nas",
|
||
"adresse_ip": "10.0.0.10",
|
||
"adresse_materielle": "AA:BB:CC:DD:EE:01"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Exigences import :
|
||
- mapping automatique des colonnes quand possible
|
||
- affichage d’une prévisualisation
|
||
- validation : doublons IP, doublons MAC, IP hors réseau
|
||
|
||
---
|
||
|
||
## Plan de développement (ordre recommandé)
|
||
|
||
1) **Squelette repo** + README installation
|
||
2) Backend FastAPI minimal :
|
||
- `/health`
|
||
- `/system/info` (hostname, FQDN, interfaces)
|
||
3) Page **Services** :
|
||
- détecter installé / actif / en cours
|
||
- start/stop/enable/disable
|
||
4) Page **Journaux** :
|
||
- lecture via `journalctl` + filtres
|
||
5) Page **Réseau (lecture seule)** : IP, routes, DNS
|
||
6) Module **Pare-feu/NAT** : générer ruleset minimal + test + apply
|
||
7) Module **DHCP Kea** : génération config minimale + apply + liste baux
|
||
8) Module **DNS Unbound** : config minimale + apply + overrides
|
||
9) Module **Activité réseau** : connexions + DNS + pare-feu
|
||
10) Module **Import OPNsense** : CSV/XML/JSON → canonique → réservations
|
||
|
||
---
|
||
|
||
## Ce que tu dois produire (attendu de l’assistant)
|
||
|
||
Quand je te demande de développer, tu dois :
|
||
|
||
1) Proposer une arborescence claire (si nécessaire).
|
||
2) Écrire du code complet et exécutable.
|
||
3) Ajouter des validations et messages d’erreurs clairs.
|
||
4) Indiquer exactement quelles commandes exécuter.
|
||
5) Fournir des fichiers prêts à coller :
|
||
- Nginx site
|
||
- systemd service (optionnel en dev)
|
||
- scripts d’application (même permissifs en V1)
|
||
|
||
---
|
||
|
||
## Règles de style (documentation et UI)
|
||
|
||
- Tout est en français.
|
||
- Aucun acronyme sans explication (ex : « passerelle (routeur) »).
|
||
- Ton ton doit être direct, structuré, et orienté actions.
|
||
|
||
---
|
||
|
||
## Commandes utiles (référence)
|
||
|
||
- État réseau : `ip -4 a`, `ip route`
|
||
- Services : `systemctl status <service>`
|
||
- Logs : `journalctl -u <service> --since ...`
|
||
- nftables (test) : `nft -c -f <fichier>`
|
||
- unbound (test) : `unbound-checkconf <fichier>`
|
||
- Connexions : `conntrack -L`
|
||
|
||
---
|
||
|
||
## Questions à ne PAS poser (déjà tranché)
|
||
|
||
- Pas de dépôt tiers.
|
||
- Debian 13.
|
||
- Nginx obligatoire.
|
||
- Modules V1 validés.
|
||
- Utilisateur unique : `gilles`.
|
||
|
||
---
|
||
|
||
## Démarrage immédiat
|
||
|
||
Commence par vérifier l’état du dépôt (arborescence actuelle) et propose :
|
||
- un premier commit « squelette backend + frontend + nginx »
|
||
- une commande unique de lancement en mode développement
|
||
- une première page WebUI (onglets) et une API `/health`.
|
||
|