# Bael Serveur DHCP intégré, en coexistence avec dnsmasq ; routage inter-subnet entre hyperviseurs par L3VNI, avec une configuration BGP pilotée par l'agent ; documentation du projet. ## Fonctionnalités **Serveur DHCP intégré** - Nouveau binaire `dhcp`, une instance par subnet lancée dans le netns du VPC par l'unit `dhcp@_`. Il reçoit son bridge et ses deux chemins de fichiers en paramètres : il ne compose aucun chemin et ignore le netns dans lequel il tourne - Piloté par l'agent sur une **socket Unix** `/run/two/dhcp/_.sock`, en JSON par ligne. Ordres idempotents en remplacement intégral : configuration du subnet à sa création, une réservation par interface à chaque création ou suppression de VM - **Réservations statiques uniquement**, pas de baux : une MAC inconnue n'obtient rien, et le serveur reste silencieux plutôt que de répondre par un refus. Aucun `DHCPNAK` n'est émis - État auto-persisté dans `/run/two/dhcp/_.state`, en écriture atomique et lisible par le seul `root`. Le fichier appartient au processus, qui le relit à son démarrage ; l'agent ne l'écrit jamais et se borne à le supprimer — à la création du subnet pour écarter un résidu, à sa suppression après avoir arrêté l'unit - La route par défaut est décidée **par interface** et non plus par subnet, ce qui permet de ne l'annoncer que sur une interface d'une VM multi-réseaux - L'encodage RFC 3442 de l'option 121 est délégué à `github.com/insomniacslk/dhcp` **Coexistence avec dnsmasq** - Nouvelle clé `dhcp.backend`, `dnsmasq` ou `two`, qui choisit le serveur des subnets **créés par cet agent**. Le défaut est `two` (#85) ; `dnsmasq` reste disponible jusqu'à son retrait (#49) - La bascule est une **opération manuelle** sur un hyperviseur vide — l'option ne migre rien, un subnet déjà créé reste servi par le serveur qui l'a été. La procédure est documentée - Toute valeur autre que `dnsmasq` ou `two` fait échouer le démarrage de l'agent **Routage inter-subnet entre hyperviseurs : L3VNI (#41)** - Nouveau champ facultatif `l3vni` sur `POST /vpcs` (1 à 65535, sauf 253-255 : c'est aussi l'identifiant de la table de routage, et le numéro du RD `:`, sur 16 bits). Absent, le VPC se comporte comme avant. Une L3VNI déjà portée par un VPC de l'agent est refusée (409), comme un `l3vni` demandé sans section `bgp` - Pour un VPC routé, l'agent pose sur l'hyperviseur une VRF (table = L3VNI), un bridge à la MAC de routeur `02:02:`, le VXLAN de la L3VNI, un lien de transit `169.254.0.1/30` ↔ `169.254.0.2/30` vers le netns et la route du `cidr` du VPC dans le netns ; FRR reçoit la VRF, sa `vni`, une instance `router bgp … vrf` (RD `:`, RT `:`) et l'export des routes du `cidr`. Un hyperviseur n'a plus besoin de porter un subnet pour joindre ses VM - Routes annoncées : le `/24` de chaque subnet `vxlan` à sa création, le `/32` de chaque interface de VM juste avant son passage en `running` ; retirés en premier à la suppression - La suppression d'un VPC routé retire la configuration de routage de FRR, puis les interfaces, puis la VRF de FRR — dans cet ordre, faute de quoi `bgpd` plante (FRR 10.7.1) **Configuration BGP pilotée par l'agent** - Nouvelle section facultative `bgp` (`asn`, `route_reflectors`). Présente, l'agent applique à chaque démarrage, par `vtysh`, la base BGP de l'hyperviseur (router-id = VTEP, peer-group `fabric` vers les route reflectors, EVPN, `advertise-all-vni`) et l'enregistre : `/etc/frr/frr.conf` devient un fichier généré. Un route reflector retiré de la liste est retiré de FRR. Absente, l'agent ne touche pas à FRR - Le démarrage échoue si la section est incomplète, si FRR tourne déjà sous un autre AS ou si `vtysh` ne répond pas **Gateway anycast des subnets `vxlan` (#57)** - La gateway et l'adresse d'émission sont **calculées** par l'agent : avant-dernière adresse du `cidr` (`.254` en `/24`) pour la gateway, exposée comme `interface_ip`, et celle d'avant (`.253`) pour l'adresse d'émission, exposée comme nouveau champ `relay_ip`. Le `cidr` doit être sans bits d'hôte et faire au plus `/29` - La gateway est portée par un macvlan `gw-` à **MAC anycast** `02:01:00:`, identique sur tous les hôtes qui portent le subnet : une VM résout toujours sa gateway vers son hôte. Le bridge garde une MAC propre à l'hôte, `02:03:`, et porte l'adresse d'émission, d'où partent les requêtes ARP du netns - Une VM qui reçoit la requête ARP d'un autre hôte ne change plus de gateway : jusqu'ici, elle envoyait pendant quelques secondes son trafic à cet hôte, coupant métadonnées, renouvellement DHCP et sessions depuis le netns. Mesuré en lab : aucune perte pendant cette fenêtre - La MAC anycast est confinée au netns — règles ebtables sur le veth du subnet et entrée FDB locale dans le bridge — et n'apparaît jamais en EVPN. Le DHCP écoute sur `gw-` ; la route du subnet a la gateway pour source - Une VM ne peut prendre ni la gateway, ni l'adresse d'émission, ni la `gateway` explicite, ni l'adresse de réseau ou de broadcast du subnet, ni une adresse hors de son `cidr` (422) - Le watchdog contrôle le macvlan, sa MAC, les deux adresses et l'entrée FDB **MAC des VM fournie à la création (#62)** - Champ `mac` obligatoire par interface dans `POST /vms`, rendu par `GET /vms/{name}`. Il est passé tel quel à QEMU et à la réservation DHCP ; son format et son unicité relèvent de l'appelant - Fin de la table `subnet//dhcp/`, qui préchargeait une MAC par adresse du `cidr` : la MAC dérivée du rang de l'IP donnait la même MAC à deux interfaces d'une VM de même rang dans leurs subnets (VM injoignable), et n'était pas tenable en IPv6 - Migration au démarrage : les VM existantes gardent leur MAC, recopiée sur chaque interface **Disques : `vda` pour la racine, `xvdX` pour les autres (#74)** - `dev` accepte désormais `vda`, le disque racine virtio, et `xvda` à `xvdz` pour les disques additionnels, sur la cible SCSI de même rang (`xvda` → 0). Toute autre valeur est refusée (400), `sdX` compris - Chaque disque reçoit le numéro de série ``. Le noyau de l'invité nomme les disques SCSI `/dev/sdY` dans l'ordre de détection, qui change d'un démarrage à l'autre (mesuré en lab : `sda` et `sdb` inversés 4 démarrages sur 6). Le nom stable est `/dev/xvdX`, créé par une règle udev de l'image (exigence décrite dans la documentation de construction d'image), et toujours `/dev/disk/by-id/scsi-0QEMU_QEMU_HARDDISK_xvdX` - Migration au démarrage : les clés `vm//disk/sdX` deviennent `vm//disk/xvdX` **MTU unique du cluster (#56)** - Nouvelle section `network` de la configuration de l'agent. `mtu_vm` (1500 par défaut, 1500 au plus) fixe le MTU de toutes les VM et de tous les bridges, veth, taps et interfaces VXLAN que l'agent crée, jusque-là figé à 1500. Il doit être identique sur tous les hyperviseurs. Sous 1500, il faut `allow_mtu_vm_below_1500`, et jamais sous 1280 ; une valeur hors bornes fait échouer le démarrage - Le MTU est annoncé aux VM par l'option DHCP 26 (serveur intégré et dnsmasq) et par `host_mtu` sur leur interface virtio. `probe` l'affiche - L'underlay est attendu à exactement 9000 : un subnet `vxlan` dont l'interface n'y est pas est refusé (422), comme un VPC avec `l3vni` si `default_interface` n'y est pas (409), sauf avec `allow_mtu_underlay_below_9000`. Dans tous les cas l'underlay doit porter `mtu_vm` + 50 octets d'en-tête VXLAN. Un subnet `bridge` est refusé si son bridge est sous `mtu_vm` **Exploitation** - Le watchdog contrôle aussi, avec une section `bgp` : les sessions vers les route reflectors ; pour chaque VPC routé, les interfaces de la VRF et l'état de la L3VNI dans FRR (type, état, MAC de routeur) ; la cohérence entre routes exportées et ressources `running` — une route exportée sans propriétaire est signalée comme **trou noir**, une route attendue absente comme manquante - Le watchdog interroge le serveur DHCP intégré et compare les réservations servies à celles que la base implique. Il nomme ce qui diverge — ordre perdu à la création, ordre perdu à la suppression, adresse ou route par défaut divergente — et reste en lecture seule. Une VM en `creating`, `deleting` ou `error` n'est pas comparée : sa réservation peut être présente ou absente sans alerte, le temps que la création ou la suppression aboutisse (#78) - La socket de contrôle répond à `get-state` et à `probe`, ce dernier montrant sans effet de bord ce qui serait envoyé à une MAC donnée : adresse, masque, routeur, DNS et routes - `bootstrap_kvm.sh` installe les paquets KVM sans les paquets recommandés et demande `qemu-utils` explicitement : l'installation, rejouée à chaque démarrage, passe d'environ 270 à 65 Mo (#64) - Documentation Sphinx du projet : concepts, architecture, déploiement et exploitation ## Correctifs - **Suppression d'un subnet refusée tant qu'une VM non supprimée l'utilise** (409, avec la liste des VM), pour tous les subnets : garantit qu'une route `/32` est retirée avant le `/24` de son subnet, ce qui évite un trou noir partiel mesuré en lab - **Un fichier de configuration présent mais invalide fait désormais échouer le démarrage.** Jusqu'en 0.1.0 l'erreur de lecture était ignorée : l'agent tournait alors entièrement sur ses valeurs par défaut sans le dire, ce qui rendait indétectable une simple tabulation d'indentation - **Réponses de l'API des subnets alignées sur la spécification** : `gateway` est rendu aussi par `GET /subnets` et par la réponse 202 de `POST /subnets`, plus seulement par `GET /subnets/{name}` ; `vxlan_id` est omis hors mode `vxlan` au lieu de valoir 0 (#80) - `probe` annonce explicitement `"served": false` pour une MAC non réservée, au lieu d'omettre le champ et de le rendre indistinguable d'une réponse tronquée - **Le serveur DHCP intégré s'arrête proprement** sur `SIGTERM` et `SIGINT` : il ferme sa socket de contrôle et sa socket UDP avant de sortir. Il mourait jusque-là sans nettoyer, et laissait `/run/two/dhcp/_.sock` après la suppression du subnet. L'agent supprime aussi cette socket avec le fichier d'état, ce qui couvre une mort brutale du processus (#77) - **Les VXLAN portent l'adresse VTEP locale (#51).** Créés sans adresse source, ils laissaient FRR sans VTEP local : aucune route EVPN annoncée, et les VM d'un même subnet `vxlan` ne se joignaient pas d'un hyperviseur à l'autre - **VM multi-NIC : les interfaces secondaires obtiennent leur bail (#73).** Le `network-config` servi par le serveur de metadata ne déclarait que `eth0` ; il déclare désormais une entrée par interface, reconnue par sa MAC. L'image doit en outre lancer DHCP sur toutes ses interfaces `en*` : voir la documentation de l'image - **Mode `bridge` sur plusieurs hôtes : `interface_ip` confinée à son hôte (#75).** Chaque hôte portant la même `interface_ip`, une VM obtenait parfois l'ARP, les métadonnées ou le DHCP d'un autre hôte : en lab, une VM ne recevait ses propres métadonnées que 3 à 4 fois sur 5. L'agent bloque désormais vers le segment les requêtes ARP vers `interface_ip`, l'ARP émis depuis elle et le DHCP émis depuis elle, y compris par le serveur local (chaîne `OUTPUT`, que la règle précédente ne couvrait pas). Le watchdog signale une règle manquante ; la suppression d'un subnet ne retire que les règles présentes ## Changements internes - Nouveaux paquets `internal/frr` (seul point d'appel à `vtysh` : génération des commandes, démontage ordonné, relecture de la configuration après démontage) et `internal/sysctl` ; une remarque de `vtysh` (« Configuration applied with notes ») n'est pas une erreur, et la suppression d'une instance BGP de VRF est réessayée tant que `bgpd` n'a pas libéré la L3VNI - Les tests du dispatcher arrêtent les workers avant de fermer la base (#47), ceux du watchdog attendent la fin de `Run` avant de la fermer (#83) - **Lab de test** : labctl, qui monte un lab virtuel (hyperviseurs en KVM imbriqué, route reflectors, switchs L3), vit dans son propre dépôt (#50, #55) ; la suite `test/e2e` reste dans two, refondue par fonctionnalité dans un ordre fixe (#70), sur un plan de contrôle redondant — deux route reflectors, deux switchs (#54). L'image Rocky 10 des VM de test se construit de façon reproductible dans `syonad/two-images` (#53) - Le module passe à **Go 1.25**, exigé par la bibliothèque DHCP retenue. La version de Go du workflow de build, restée à 1.21 alors que le module en demandait davantage, est alignée - Nouveau paquet `pkg/db/statefile` : persistance générique d'un état de composant dans un fichier, en écriture atomique. Badger a été écarté pour cet usage — une instance par subnet coûterait une memtable de 64 Mio et quatre goroutines de compaction pour environ un kilo-octet d'état, dans un `tmpfs`, et laisserait un verrou résiduel après un arrêt brutal - `internal/subnet` et `internal/vm` ne parlent plus à dnsmasq en direct mais à une interface `Backend` à deux implémentations ## Périmètre et limites connues Celles de la 0.1.0 restent valables, sauf mention contraire ci-dessus. S'y ajoutent : - **L3VNI** : pas de migration à chaud ; la gateway anycast (#57) la prépare côté réseau. Le transit `169.254.0.0/30` étant identique sur tous les hôtes, les ICMP des sauts distants sont rejetés comme « martiens » (traceroute partiel) - Avec une section `bgp`, l'agent ne démarre pas sans FRR et `agent.service` ne le relance pas : au démarrage, l'ordre est migration réseau, puis FRR, puis l'agent (#52) - `bootstrap_kvm.sh` active `net.ipv4.ip_forward` en global ; le forwarding que l'agent active sur les seules interfaces de la VRF n'en restreint donc pas la portée - **dnsmasq n'est pas retiré** et reste un paquet requis : il sert les hyperviseurs qui déclarent `dhcp.backend: dnsmasq`, dont ceux mis à jour avec des subnets existants, et le retour arrière suppose dnsmasq installé. Son retrait est prévu en 0.4.0 (#49) - Pas de DNS, pas de pool dynamique, pas de PXE, pas de DHCPv6 dans le serveur intégré - La comparaison faite par le watchdog porte sur les **réservations** et non sur la configuration du subnet : celle-ci dépend de la route par défaut de l'host, dont la lecture au moment du contrôle produirait de faux écarts. Un serveur dépourvu de configuration est en revanche signalé - L'option 249 (routes classless de Microsoft) n'est pas émise, comme dnsmasq ne l'émet pas - Le serveur intégré écoute UDP/67 sans authentification, comme tout serveur DHCP : l'isolation entre locataires d'un même subnet repose sur les règles ebtables anti-usurpation, inchangées - `internal/dhcpbackend` n'est testé sous Linux que pour ses appels systemd ; le reste, y compris le dialogue avec le serveur intégré, est couvert sur toute plateforme ## Mise à jour depuis la 0.1.0 ```bash curl -O https://git.g3e.fr/syonad/two/raw/branch/main/scripts/deploy.sh bash ./deploy.sh -t 0.2.0 ``` Sans `bgp` dans `/etc/two/agent.yml`, le comportement est celui de la 0.1.0, à six exceptions près ; les quatre premières touchent les appelants de l'API : - **`interface_ip` ne se fournit plus pour un subnet `vxlan`** : il est refusé (400), l'agent le calcule. Le retirer des appels de création, et ne plus placer de VM sur les deux dernières adresses utilisables du subnet. Il reste obligatoire en `bridge` et `public_ip` - **un subnet encore utilisé par une VM ne se supprime plus** : supprimer les VM d'abord - **chaque interface d'une VM doit porter sa `mac`** (400 sinon) : l'appelant la choisit et en garantit l'unicité. Les VM existantes gardent la leur, recopiée au premier démarrage de l'agent - **les disques additionnels s'appellent `xvdX`** : `sdX` est refusé (400). Les VM existantes sont migrées ; leurs disques prennent le numéro de série `xvdX` au prochain lancement, et une image qui les montait par `/dev/sdY` doit passer à `/dev/xvdX` - **l'underlay doit être à 9000** : sur un hyperviseur dont `default_interface` (ou l'interface d'un `iface_type`) est à un autre MTU, la création d'un subnet `vxlan` est refusée. Passer l'underlay à 9000, ou poser `network.allow_mtu_underlay_below_9000: true` — sous 1550, il faut aussi abaisser `network.mtu_vm` avec `allow_mtu_vm_below_1500`. Les subnets existants gardent leurs interfaces à 1500 jusqu'à leur recréation - **le DHCP passe par défaut au serveur intégré** (`dhcp.backend: two`) : sur un hyperviseur qui a déjà des subnets, ajouter `dhcp.backend: dnsmasq` à `/etc/two/agent.yml` **avant** `deploy.sh -t 0.2.0`. Sinon ses subnets restent servis par dnsmasq pendant que l'agent s'adresse au serveur intégré : les VM existantes continuent, les nouvelles n'obtiennent pas d'adresse. Un hyperviseur vide n'a rien à faire Les subnets `vxlan` existants gardent leur adressage et le modèle précédent (gateway sur le bridge) jusqu'à leur recréation. Les subnets `bridge` existants restent sans le confinement de `interface_ip` (#75) jusqu'à leur recréation ; le watchdog les signale. Pour router entre hyperviseurs : ajouter la section `bgp`, réduire `frr.conf` à `hostname` et `log` (l'agent pose le reste), puis créer les VPC avec `l3vni`. Pour passer au serveur intégré, suivre la procédure de bascule dans la documentation d'exploitation — elle suppose un hyperviseur vidé.