# 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