Téléverser les fichiers vers "/"

This commit is contained in:
2026-01-22 23:33:55 +01:00
parent cbb1ad1950
commit 53d35adb1e
4 changed files with 843 additions and 0 deletions

View File

@@ -0,0 +1,249 @@
# PROJET WEBUI PASSERELLE RÉSEAU SYNTHÈSE COMPLÈTE
Ce document reprend **lintégralité de la discussion**, structurée et consolidée, sur la conception et le développement dune **WebUI dadministration réseau** destinée à une **VM Debian 13 (Trixie)** jouant le rôle de **passerelle LAN → Internet**.
---
## 1. OBJECTIF GÉNÉRAL
Créer une **application Web dadministration réseau**, installée dans une **machine virtuelle Debian 13**, permettant de configurer et superviser :
- le réseau local (LAN)
- laccès Internet (WAN)
- lattribution dadresses IP (DHCP)
- la résolution de noms (DNS)
- le pare-feu et le partage de connexion (NAT)
- les services réseau associés
Contraintes clés :
- uniquement **outils réseau standards Debian 13** (aucun dépôt tiers)
- **WebUI simple et pédagogique**, adaptée à des utilisateurs novices
- libellés clairs, textes explicatifs, info-bulles, **pas dacronymes non expliqués**
- accès WebUI limité au **réseau local**
- architecture modulaire (services activables/installables)
---
## 2. ARCHITECTURE GÉNÉRALE
### 2.1 Schéma fonctionnel
Navigateur → HTTPS → Nginx → API backend (non root) → scripts contrôlés → services système Debian
### 2.2 Composants
- **Frontend** : HTML/CSS/JavaScript léger (onglets + formulaires)
- **Serveur Web** : Nginx
- **Backend** : Python (API REST)
- **Services système** : configurés via fichiers standards Debian
- **Contrôle système** : systemctl, journalctl, nftables, kea, unbound
### 2.3 Sécurité
- WebUI accessible uniquement depuis le LAN
- utilisateur système dédié pour lapplication
- droits permissifs en phase V1 (sudo large), durcissement ultérieur
- aucune modification appliquée sans validation explicite
---
## 3. MACHINE VIRTUELLE (PROXMOX)
### 3.1 Paramétrage recommandé
- Type : VM Linux
- Machine : q35
- BIOS : OVMF (UEFI)
- CPU : 1 socket / 2 à 4 cœurs / type host
- RAM : 4 Go (ballooning désactivé)
- Disque : 32 Go, VirtIO SCSI, iothread activé
- Réseau :
- 2 cartes VirtIO
- 1 WAN (Internet)
- 1 LAN (réseau local)
- Pare-feu Proxmox : désactivé
- Watchdog : activé
### 3.2 Rôle de la VM
- passerelle LAN → Internet
- serveur DHCP principal
- serveur DNS local
- point central dobservation du trafic
---
## 4. SERVICES UTILISÉS (STANDARD DEBIAN 13)
### 4.1 Services cœur (V1)
- Gestion réseau : systemd-networkd
- Pare-feu / NAT : nftables
- DHCPv4 : kea-dhcp4-server
- DNS local : unbound
- Logs : systemd-journald
- Connexions réseau : conntrack
### 4.2 Services optionnels (V2/V3)
- Découverte réseau : avahi-daemon (LAN uniquement)
- VPN : wireguard
- QoS : tc
- IDS/IPS : suricata (non V1)
---
## 5. WEBUI ORGANISATION DES PAGES (V1)
### 5.1 Tableau de bord
- état WAN / LAN
- état des services
- alertes simples
### 5.2 Réseau
- côté Internet : adresse automatique ou fixe
- côté réseau local : adresse de la passerelle, domaine
### 5.3 Pare-feu et partage de connexion
- interrupteurs simples
- règles prédéfinies compréhensibles
### 5.4 Attribution dadresses (DHCP)
- plages dynamiques
- réservations fixes
- liste des appareils connectés
### 5.5 Noms (DNS)
- serveurs amont
- domaine local
- entrées fixes nom → adresse
### 5.6 Services
- installation via apt (liste blanche)
- démarrage / arrêt / activation au boot
- état en temps réel
### 5.7 Journaux
- lecture des logs par service
- filtres (date, texte, niveau)
### 5.8 Activité réseau
- connexions LAN → Internet
- requêtes DNS
- événements du pare-feu
---
## 6. MÉTHODOLOGIE DE TEST ET DÉPLOIEMENT
### 6.1 Phase 0 Développement hors réseau
- DHCP désactivé
- pare-feu non bloquant
- génération et validation de configuration uniquement
### 6.2 Phase 1 Intégration passive
- VM connectée au LAN
- observation uniquement (logs, trafic)
### 6.3 Phase 2 Test DHCP contrôlé
- arrêt temporaire de lancien DHCP
- activation du nouveau
- tests sur un ou deux clients
- rollback immédiat possible
### 6.4 Phase 3 Remplacement définitif
- bascule complète
- surveillance
---
## 7. MIGRATION DES ADRESSES IP EXISTANTES
### 7.1 Principe
- conserver les adresses IP actuelles
- éviter toute reconfiguration côté clients
### 7.2 Méthode retenue (recommandée)
**Import des baux DHCP existants** depuis lancien serveur
### 7.3 Sources supportées
- OPNsense :
- CSV (baux DHCP)
- XML (config complète)
- Fichier JSON générique
### 7.4 Format JSON canonique interne
{
"source": "opnsense",
"interface": "lan",
"reservations": [
{
"nom": "nas",
"adresse_ip": "10.0.0.10",
"adresse_materielle": "AA:BB:CC:DD:EE:01"
}
]
}
Tous les imports sont normalisés vers ce format.
### 7.5 Processus WebUI
- import fichier
- analyse et validation
- prévisualisation
- génération réservations DHCP
- aucune application automatique
---
## 8. PHILOSOPHIE DU PROJET
- sécurité avant automatisation
- aucune action irréversible sans confirmation
- priorité à la lisibilité et à la pédagogie
- architecture modulaire
- pas de dépendance externe
---
## 9. PÉRIMÈTRE V1 VALIDÉ
Modules inclus :
1. Réseau WAN/LAN
2. Pare-feu + NAT
3. DHCPv4 (Kea)
4. DNS (Unbound)
5. Services
6. Journaux
7. Activité réseau
---
## 10. ÉTAPES SUIVANTES POSSIBLES
- création du canevas de projet (arborescence + fichiers)
- écrans WebUI détaillés
- moteur dimport OPNsense (CSV/XML → JSON)
- génération automatique des configurations Kea / Unbound / nftables
---
FIN DU DOCUMENT

248
prompt.md Normal file
View File

@@ -0,0 +1,248 @@
# prompt.md — Développement NetUI (Debian 13 / Passerelle LAN→Internet)
## Contexte
Tu es un assistant de développement (compatible Codex et Claude Code). Tu maides à construire une application **NetUI** : une **WebUI** dadministration 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) Lapplication 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, lexpliquer en toutes lettres.
4) Lapplication est servie via **Nginx**.
5) Laccè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) Lutilisateur 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 dadresses (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 dimport **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 limport
- 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 lutilisateur `gilles`.
- Les opérations système se font via `sudo` (V1 permissif).
- Ne pas activer automatiquement les services réseau tant que lutilisateur na 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 nest pas appliquée.
- Boutons distincts :
- **Générer** (préparer fichiers sans appliquer)
- **Tester** (vérifier syntaxe/cohérence)
- **Appliquer** (écrire + recharger services)
- Messages derreur 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 dimport
- **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 dune 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 lassistant)
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 derreurs clairs.
4) Indiquer exactement quelles commandes exécuter.
5) Fournir des fichiers prêts à coller :
- Nginx site
- systemd service (optionnel en dev)
- scripts dapplication (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`.

204
specification_technique.md Normal file
View File

@@ -0,0 +1,204 @@
# Spécification technique WebUI Passerelle Réseau (V1)
## 1. Objet du document
Ce document décrit **la spécification technique détaillée** de la WebUI de passerelle réseau basée sur **Debian 13 (Trixie)**.
Il sert de référence pour le développement, larchitecture logicielle et les choix techniques.
---
## 2. Contexte et périmètre
### 2.1 Rôle de la VM
- Passerelle réseau LAN → Internet
- Serveur DHCP principal du réseau local
- Serveur DNS local
- Pare-feu et traduction dadresses (NAT)
- Point central de supervision réseau
### 2.2 Contraintes
- Debian 13 Trixie uniquement
- Dépôts officiels Debian uniquement
- Aucun conteneur
- WebUI accessible uniquement depuis le réseau local
- Architecture modulaire
- Pas dautomatisation dangereuse
---
## 3. Architecture générale
### 3.1 Vue densemble
Navigateur → HTTPS → Nginx → API Backend → Scripts système → Services Debian
### 3.2 Composants
- Frontend : HTML / CSS / JavaScript (léger)
- Serveur Web : Nginx
- Backend : Python (API REST)
- Services système : systemd
- Journalisation : journald
---
## 4. Machine virtuelle (Proxmox)
### 4.1 Ressources
- CPU : 2 à 4 cœurs (type host)
- RAM : 4 Go (ballooning désactivé)
- Disque : 32 Go (VirtIO SCSI)
- Réseau :
- 1 interface WAN
- 1 interface LAN
### 4.2 Règles importantes
- Pare-feu Proxmox désactivé
- Pare-feu unique géré dans la VM
---
## 5. Gestion réseau Debian
### 5.1 Outils retenus
- systemd-networkd : configuration des interfaces
- nftables : pare-feu et NAT
- conntrack : suivi des connexions
### 5.2 Fonctions réseau
- Routage IPv4
- Traduction dadresses (NAT)
- Séparation WAN / LAN
---
## 6. Services réseau (V1)
### 6.1 DHCP
- Service : kea-dhcp4-server
- Fonctions :
- plages dynamiques
- réservations fixes
- options DHCP (routeur, DNS, serveur de temps)
### 6.2 DNS
- Service : unbound
- Fonctions :
- cache DNS
- serveurs amont configurables
- entrées statiques nom → adresse
### 6.3 Pare-feu
- Service : nftables
- Fonctions :
- protection de la VM
- autorisation LAN → Internet
- blocage administration depuis Internet
### 6.4 Services annexes
- chrony : synchronisation de lheure
---
## 7. Backend API
### 7.1 Principes
- Backend non exécuté en root
- Utilisateur système dédié
- Appels système via sudo (phase V1 permissive)
### 7.2 Responsabilités
- Lecture / écriture de la configuration centrale
- Génération des fichiers de configuration système
- Validation avant application
- Application contrôlée des changements
---
## 8. Configuration centrale
### 8.1 Source de vérité
- Fichier unique : /etc/netui/config.yaml
### 8.2 Contenu
- paramètres réseau WAN / LAN
- configuration DHCP
- configuration DNS
- état des services
---
## 9. WebUI
### 9.1 Organisation
- Onglets
- Formulaires simples
- Textes explicatifs sous chaque champ
- Info-bulles détaillées
### 9.2 Pages V1
- Tableau de bord
- Réseau
- Pare-feu / Partage de connexion
- Attribution dadresses (DHCP)
- Noms (DNS)
- Services
- Journaux
- Activité réseau
---
## 10. Import des adresses existantes
### 10.1 Objectif
- Conserver les adresses IP existantes lors du remplacement DHCP
### 10.2 Sources supportées
- OPNsense CSV
- OPNsense XML
- Fichier JSON
### 10.3 Format interne
- Normalisation vers un format JSON canonique
---
## 11. Sécurité
- Accès WebUI limité au LAN
- Authentification locale
- Validation stricte des données
- Aucune application automatique
---
## 12. Évolutions prévues (hors V1)
- VPN WireGuard
- QoS / limitation de débit
- Découverte réseau (mDNS)
- Historique et rollback avancé
---
Fin de la spécification technique

142
todo.md Normal file
View File

@@ -0,0 +1,142 @@
# TODO WebUI Passerelle Réseau (V1)
Ce fichier liste les **tâches à réaliser**, dans lordre recommandé, pour développer la version V1 du projet.
---
## 1. Préparation
- [ ] Créer le dépôt Git du projet
- [ ] Définir larborescence (frontend / backend / deploy)
- [ ] Créer lutilisateur système dédié à lapplication
---
## 2. Infrastructure de base
- [ ] Installer Debian 13 dans la VM
- [ ] Installer Nginx
- [ ] Installer Python et environnement virtuel
- [ ] Configurer Nginx (accès LAN uniquement)
- [ ] Créer le service systemd du backend
---
## 3. Backend Squelette API
- [ ] Créer lAPI (endpoint /health)
- [ ] Mettre en place lauthentification simple
- [ ] Restreindre laccès par adresse IP LAN
- [ ] Mettre en place la lecture des états systemd
---
## 4. Page Services
- [ ] Détection des paquets installés
- [ ] Installation contrôlée via apt (liste blanche)
- [ ] Démarrage / arrêt / activation des services
- [ ] Affichage clair de létat
---
## 5. Journaux
- [ ] Lecture des journaux via journalctl
- [ ] Filtrage par service
- [ ] Filtrage par période
- [ ] Recherche texte
---
## 6. Réseau (lecture seule phase initiale)
- [ ] Afficher interfaces WAN / LAN
- [ ] Afficher adresses IP et routes
- [ ] Vérifier connectivité Internet
---
## 7. Pare-feu et partage de connexion
- [ ] Générer un ruleset nftables minimal
- [ ] Tester la configuration (mode test)
- [ ] Appliquer le pare-feu
- [ ] Activer le NAT LAN → Internet
---
## 8. DHCP (Kea)
- [ ] Générer configuration DHCP minimale
- [ ] Tester la configuration DHCP
- [ ] Activer le service Kea
- [ ] Afficher les baux DHCP actifs
---
## 9. DNS (Unbound)
- [ ] Générer configuration DNS minimale
- [ ] Tester la configuration Unbound
- [ ] Activer le service
- [ ] Lire les journaux DNS
---
## 10. Import des adresses existantes
- [ ] Import CSV OPNsense
- [ ] Import XML OPNsense
- [ ] Import JSON générique
- [ ] Normalisation interne
- [ ] Validation et prévisualisation
- [ ] Génération réservations DHCP
---
## 11. WebUI
- [ ] Créer la structure des onglets
- [ ] Implémenter les formulaires réseau
- [ ] Ajouter textes explicatifs et info-bulles
- [ ] Afficher les messages derreur clairs
---
## 12. Activité réseau
- [ ] Afficher connexions actives (conntrack)
- [ ] Associer connexions aux appareils DHCP
- [ ] Afficher requêtes DNS
- [ ] Afficher événements du pare-feu
---
## 13. Sécurité et validation
- [ ] Vérifier aucune action automatique dangereuse
- [ ] Ajouter confirmations avant application
- [ ] Sauvegarde automatique avant modification
---
## 14. Tests
- [ ] Test en mode passif
- [ ] Test DHCP en fenêtre contrôlée
- [ ] Test remplacement DHCP
- [ ] Test rollback
---
## 15. Documentation
- [ ] Compléter la documentation utilisateur
- [ ] Ajouter captures décran
- [ ] Rédiger guide de migration DHCP
---
Fin du TODO V1