Téléverser les fichiers vers "/"

specification_technique.md

@@ -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, l’architecture 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 d’adresses (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 d’automatisation dangereuse
+
+---
+
+## 3. Architecture générale
+
+### 3.1 Vue d’ensemble
+
+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 d’adresses (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 l’heure
+
+---
+
+## 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 d’adresses (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
+