gilles/netui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
netui/prompt.md

8.1 KiB
Raw Permalink Blame History

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)

{
  "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.
Reference in New Issue View Git Blame Copy Permalink