# Guide de labctl Référence détaillée ; le [README](../README.md) en est le résumé. Les sorties citées viennent de campagnes réelles : les dates et versions sont celles de leur relevé. ## Le serveur loué : `scripts/lab-host.sh` Un serveur **Scaleway Elastic Metal**, créé pour une campagne de tests puis supprimé, facturé à l'heure. **Offre.** L'offre par défaut est `EM-B420E-NVME` (AMD EPYC 7272, 12 cœurs, 119 Gio) : son modèle de CPU est exact et atteint **x86-64-v3**, le minimum de RHEL 10 et Rocky 10. Les offres « Xeon … or equivalent » ne garantissent rien : `EM-B212X-SSD` (« E5-2620 v4 or equivalent ») a livré un E5-2640 v3 une fois, un E5-2670 de 2012 (x86-64-v2, sur lequel Rocky 10 ne démarre pas) une autre. `prepare` refuse donc un serveur sans x86-64-v3 — dans une `session`, il est aussitôt supprimé. Relever `lscpu` au début de chaque campagne. ### Prérequis côté Scaleway 1. **Un projet dédié au lab**, séparé de toute autre ressource. `lab-host.sh down` supprime tout serveur de lab du projet : il ne doit rien y avoir d'autre. 2. **Une clé d'API limitée à ce projet**, avec les droits Elastic Metal et la lecture des clés SSH du projet. Rien d'autre. 3. **Les clés SSH publiques enregistrées dans le projet**, injectées à l'installation : sans elles, le serveur serait facturé sans que personne puisse s'y connecter, et `plan` refuse de continuer. 4. **Le quota Elastic Metal.** Il exige un compte dont le moyen de paiement *et* l'identité sont validés. Vérifier dans la console : Organisation → Quotas → Elastic Metal. Voir [les quotas Scaleway](https://www.scaleway.com/en/docs/organizations-and-projects/organization/organization-quotas/). ### Fichiers locaux Tout ce dont le script a besoin vit sous `~/.config/labctl/`, hors du dépôt. **`~/.config/labctl/scaleway.env`** — identifiants Scaleway, une ligne `CLÉ=valeur` chacun : ```bash SCW_SECRET_KEY= SCW_DEFAULT_PROJECT_ID= SCW_DEFAULT_ZONE=fr-par-1 ``` - le fichier doit être en `0600` : le script refuse de s'en servir s'il est lisible par d'autres que son propriétaire ; - il est **lu, jamais exécuté** — pas de `source` ; seules ces trois clés sont reconnues ; - une variable d'environnement du même nom l'emporte sur le fichier ; - la clé d'accès (`SCW…`) n'est pas nécessaire : l'API REST n'authentifie que par la clé secrète, dans l'en-tête `X-Auth-Token`. Pour changer de clé, remplacer la ligne `SCW_SECRET_KEY=` ; rien d'autre à modifier. **`~/.config/labctl/ssh/lab_ed25519`** — clé SSH dédiée au lab, **sans phrase de passe**, pour que les sessions tournent sans intervention. Sa partie publique doit être enregistrée dans le projet. Quand elle existe, le script l'utilise **seule** (`IdentitiesOnly`, agent désactivé) ; sinon il retombe sur l'agent SSH. Elle ne doit ouvrir que les serveurs éphémères du projet de lab : **ne jamais l'installer sur une machine durable**. En cas de doute, la retirer du projet et en générer une autre : ```bash mkdir -p ~/.config/labctl/ssh && chmod 700 ~/.config/labctl ~/.config/labctl/ssh ssh-keygen -t ed25519 -N '' -C lab-automation -f ~/.config/labctl/ssh/lab_ed25519 ``` **`~/.cache/labctl/`** — état de la session en cours : adresse et utilisateur du serveur, `known_hosts` dédié. Vidé par `down`. ### Commandes ```text usage: lab-host.sh [arguments] plan résout l'offre horaire, l'OS et les clés SSH, affiche la requête de création et le prix ; ne crée rien up crée le serveur de lab, attend la fin de son installation et son SSH, puis le prépare (voir prepare) status liste les serveurs de lab du projet, dans toutes les zones candidates ssh [commande] se connecte au serveur de lab ; avec une commande, un terminal n'est demandé que si l'entrée standard en est un prepare installe sur le serveur ce dont labctl a besoin (qemu, genisoimage), vérifie /dev/kvm, la virtualisation imbriquée et un CPU x86-64-v3 ; lancé aussi par up push compile cmd/labctl pour linux/amd64 et dépose sur le serveur ~/labctl et le répertoire de la topologie dans ~/topology/ (avec les fichiers qu'elle référence) ; ensuite : ssh './labctl up topology/' down supprime tous les serveurs de lab du projet, dans toutes les zones candidates, et attend leur disparition session [cmd] up, puis la commande distante (ou un shell), puis down quoi qu'il arrive ``` `plan` et `status` sont **gratuits** ; `up` et `session` **créent un serveur facturé**. Toujours commencer par `plan`. Il valide la clé d'API, le quota d'offre, l'OS et les clés SSH, et montre exactement ce qui serait commandé : ```text $ scripts/lab-host.sh plan !! fr-par-1 : offre EM-B420E-NVME en rupture de stock en fr-par-1 !! fr-par-2 : offre EM-B420E-NVME en rupture de stock en fr-par-2 !! nl-ams-1 : offre horaire EM-B420E-NVME : 0 correspondance(s) en nl-ams-1, une seule attendue == zone : nl-ams-2 == offre : EM-B420E-NVME (d14eef5e-3279-42db-bb57-bb2bbe6a5b28), AMD EPYC 7272, facturation hourly, stock available == prix : 0.444 EUR HT par heure, frais de mise en service 0 EUR == os : Debian 12 (Bookworm) (83640d93-a0b8-45ad-9c9f-30cae48380a4), utilisateur root == clés : 2 clé(s) SSH du projet == requête : POST /baremetal/v1/zones/nl-ams-2/servers ``` **Zone.** Elle n'est pas imposée : `plan` et `up` prennent la première zone de `LAB_ZONES` (par défaut toutes les zones Elastic Metal) où l'offre est en stock, `SCW_DEFAULT_ZONE` passant en tête ; `status` et `down` couvrent toutes ces zones. Une zone dont la liste échoue est signalée sans masquer les autres : `status` affiche ce qui a répondu, `down` supprime les serveurs listés, et tous deux sortent en erreur ; `up` refuse de créer tant qu'une zone reste inconnue. **`session`** est la forme la plus sûre : le serveur est supprimé à la fin, que la commande réussisse, échoue, ou que la session soit interrompue (Ctrl-C, `TERM`, fermeture du terminal). Son code de sortie est celui de la commande distante. `up`, `ssh` et `down` séparément servent aux campagnes longues et au debug interactif — et laissent la suppression à la charge de l'utilisateur. Compter **environ 15 minutes** entre la création et le SSH disponible : l'installation de Debian par Scaleway en prend une dizaine, et SSH ne répond pas tout de suite après — d'où l'attente intégrée à `up`. Une campagne enchaîne ces commandes depuis le poste ; `labctl` s'exécute sur le serveur (voir [Lancement des VM](#lancement-des-vm)) : ```text scripts/lab-host.sh up scripts/lab-host.sh push examples/evpn-2hv/topology.yml scripts/lab-host.sh ssh './labctl up topology/topology.yml' scripts/lab-host.sh ssh './labctl ssh hv1' # shell interactif sur hv1 scripts/lab-host.sh ssh './labctl ssh hv1 ip -br a' # commande, code de retour propagé scripts/lab-host.sh down ``` `push` transfère par la connexion SSH du script — mêmes options, même clé, même `known_hosts` que `ssh` : le binaire par `cat`, le répertoire de la topologie par `tar` (sans les métadonnées macOS), chacun renommé une fois complet. Tout le répertoire part, pour que les fichiers que la topologie référence arrivent avec elle. Avec `LABCTL_BIN`, `push` envoie ce binaire (par exemple celui d'une release, vérifié) au lieu de compiler. ## Topologie Un lab est décrit par un fichier YAML : des **nœuds** (les VM) et des **segments** (des réseaux L2). Exemple livré : [`examples/evpn-2hv/topology.yml`](../examples/evpn-2hv/topology.yml) — deux routeurs en VRRP, un route reflector et deux hôtes en EVPN. Chaque segment est un **bridge Linux sur l'hôte du lab** (`lb-`), et chaque nœud qui y est attaché y branche une carte par un tap (`lt`). Le L2 ne dépend donc d'aucune VM : la perte d'un routeur ne coupe pas le trafic direct entre les autres nœuds du segment. Un **routeur** est un nœud comme les autres, qui porte en plus la passerelle et le NAT des segments dont il est routeur. Ce que le fichier déclare : **`images`** — `url` de l'image qcow2 et `sums` du fichier de sommes à vérifier, tous deux en `https://`. **`segments`** — `cidr` IPv4 entre `/8` et `/30`, `mtu` facultatif — 9000 par défaut, entre 1280 et 9000 —, et `routers`, facultatif : les nœuds de rôle `router` qui portent la passerelle du segment, **dans l'ordre de priorité**. Sans routeur, le segment est un L2 pur (lien entre VM, lien inter-cluster) : pas de passerelle, pas de NAT. Nom : 12 caractères au plus, minuscules et chiffres, parce qu'il devient le nom d'interface dans les VM et, préfixé de `lb-`, celui du bridge sur l'hôte (15 caractères au plus sous Linux). **`nodes`** — `role` (`router`, `rr` ou `host`), `image`, `cpus`, `memory` en Mio (256 au moins), `segments` auxquels le nœud est relié, et `addresses` pour fixer l'adresse d'un nœud sur un segment (`addresses: {underlay: 192.168.14.50}`). Un routeur listé dans `segments..routers` doit être attaché à ``. Champs facultatifs : - `secondary` — des adresses supplémentaires par segment, avec leur longueur de préfixe (`secondary: {underlay: [169.254.0.3/28]}`), posées sur la même interface que l'adresse principale : même L2, même MAC. Elles doivent être **hors** du CIDR du segment, pour ne jamais croiser l'attribution automatique ; - `loopback` — une adresse sur une interface `dummy` nommée `lo1` (`loopback: 10.255.255.1/32`) ; - `frr` — le chemin d'un `frr.conf`, relatif au fichier de topologie : FRR est installé au démarrage et la configuration déposée **telle quelle** (voir [FRR](#frr)) ; - `provision` — le chemin d'un script, relatif au fichier de topologie, exécuté au premier démarrage **avant** FRR ; - `post_provision` — un second script, exécuté **après** FRR ; - `files` — des fichiers **ou répertoires** déposés dans `/etc/lab/files/` avant les scripts, sous la forme `{: }` (`files: {motd: motd}`). Ils voyagent dans un `files.iso` propre au nœud (volume `LABFILES`), attaché comme second lecteur et recopié au premier démarrage : la taille n'est pas limitée par cloud-init, et un binaire de plusieurs dizaines de Mio passe ; - `services` — les unités systemd que `labctl up` vérifie actives sur le nœud. Les scripts reçoivent `LAB_NODE` (nom du nœud), `LAB_UPLINK` (interface qui porte la route par défaut : celle du premier segment du nœud qui a une passerelle, `mgmt0` pour un routeur) et `LAB_FILES` (`/etc/lab/files`). L'outil ne sait rien de ce qu'ils installent. **Un seul script de provisionnement par nœud.** cloud-init exécute `runcmd` comme un script `sh` sans `set -e` : seule la dernière commande compterait, et une provision en échec suivie d'un FRR installé avec succès passerait pour un démarrage réussi. Chaque nœud reçoit donc `/usr/local/sbin/lab-provision`, en `set -eu`, qui enchaîne ses étapes — service du routeur ou de la loopback, `provision`, FRR, `post_provision` ; `runcmd` n'appelle que lui, et la première étape en échec met cloud-init en erreur. `mgmt0` et `lo1` sont réservés : aucun segment ne peut porter ces noms. ### Passerelle et routeurs | Routeurs du segment | Passerelle | |---|---| | aucun | aucune : les nœuds n'y ont pas de route par défaut | | un | la première adresse du CIDR, posée sur l'interface du routeur, en plus de la sienne | | deux ou plus | la première adresse du CIDR, **virtuelle**, portée en VRRP v3 par `vrrpd` de FRR | Avec plusieurs routeurs, `labctl` prépare tout sur chacun : interface `macvlan` `vr` avec la MAC VRRP (`00:00:5e:00:01:`) et la passerelle, créée **coupée** (`protodown on`) : seul `vrrpd` la rétablit, quand il devient maître ; `arp_ignore=1` et `arp_announce=2` sur l'interface du segment (sans quoi elle répondrait aux ARP de la passerelle avec sa propre MAC), FRR installé avec `vrrpd`, et la configuration VRRP **ajoutée** à la fin de son `frr.conf` (ou d'un `frr.conf` minimal s'il n'en déclare pas) : ```text interface underlay vrrp 1 version 3 vrrp 1 priority 200 no vrrp 1 preempt vrrp 1 ip 192.168.14.1 exit ``` Le VRID est le rang du segment plus un (d'où au plus 255 segments à plusieurs routeurs, parmi les premiers) ; la priorité vaut 200 pour le premier routeur de la liste, puis 10 de moins pour chacun des suivants. **Pas de préemption** : un routeur qui revient reste en attente, plutôt que de reprendre la passerelle avant d'avoir ses routes BGP — un prétest l'a montré, la préemption coupait les sessions qui passaient par lui. Conséquence : le maître est le premier routeur dont VRRP démarre, la priorité ne départageant que des démarrages simultanés ; un scénario qui arrête « le maître » doit le demander (`vtysh -c 'show vrrp'`), pas le supposer. Bascule mesurée en prétest : environ 2,6 s de perte (trois annonces manquées à une seconde d'intervalle). Chaque routeur masque (NAT nftables) vers `mgmt0` les segments dont il est routeur, et sort par le NAT de QEMU. Un nœud qui n'est pas routeur prend sa route par défaut et ses DNS (`1.1.1.1`, `8.8.8.8`) sur le premier de ses segments qui a une passerelle. ### Plan déterministe Ce que l'outil déduit du fichier — même fichier, même plan : | | | |---|---| | Passerelle d'un segment | la première adresse du CIDR, si le segment a au moins un routeur | | Adresse d'un nœud | les suivantes (dès la première sans routeur), **dans l'ordre de déclaration des nœuds** ; une adresse fixée par `addresses` est réservée d'abord et sautée par l'attribution automatique | | Bridge | `lb-` sur l'hôte du lab | | Ports | un par couple (segment, nœud), segments puis nœuds dans l'ordre de déclaration ; le port *i* est le tap `lt` | | MAC | `02:4c::::00` — préfixe localement administré, rang du nœud sur deux octets, rang du segment | | Interfaces | dans la VM, le nom du segment | | SSH d'administration | `127.0.0.1:<2200 + rang du nœud>` sur l'hôte du lab | > [!WARNING] > Réordonner les nœuds ou les segments dans le fichier **change les adresses, les MAC, les taps et > les ports**. C'est assumé pour un lab ; `labctl plan` montre le résultat avant tout lancement. Limites : 1000 nœuds, 256 segments. `labctl plan` valide le fichier et affiche le plan, sans rien lancer : ```text $ go run ./cmd/labctl plan examples/evpn-2hv/topology.yml lab evpn-2hv: nodes 5, segments 1, ports 5 nodes name role image cpus memory ssh r1 router debian12 1 1024 MiB 127.0.0.1:2200 r2 router debian12 1 1024 MiB 127.0.0.1:2201 rr1 rr debian12 1 1024 MiB 127.0.0.1:2202 hv1 host debian12 2 2048 MiB 127.0.0.1:2203 hv2 host debian12 2 2048 MiB 127.0.0.1:2204 roles name loopback secondary frr provision post_provision files services r1 - underlay 169.254.0.1/28 r1.conf - - - - r2 - underlay 169.254.0.2/28 r2.conf - - - - rr1 lo1 10.255.255.1/32 underlay 169.254.0.3/28 rr1.conf - - - - hv1 - - hv1.conf host.sh - motd - hv2 - - hv2.conf host.sh - motd - segment underlay: 192.168.14.0/24, mtu 9000, bridge lb-underlay, gateway 192.168.14.1 by vrrp 1 on r1, r2 node interface address mac tap r1 underlay 192.168.14.252/24 02:4c:00:00:00:00 lt0 r2 underlay 192.168.14.253/24 02:4c:00:01:00:00 lt1 rr1 underlay 192.168.14.2/24 02:4c:00:02:00:00 lt2 hv1 underlay 192.168.14.11/24 02:4c:00:03:00:00 lt3 hv2 underlay 192.168.14.12/24 02:4c:00:04:00:00 lt4 ``` Un fichier invalide est refusé avec **toutes** ses erreurs à la fois, et un code de sortie 1. Les champs inconnus et les clés en double sont refusés aussi : ```text $ labctl plan cassee.yml labctl: cassee.yml: segment underlay: rr1 is a rr, not a router segment underlay: router r9 is not a declared node segment underlay: cidr 10.250.0.0/31 prefix length out of range [/8, /30] node r1: must be attached to at least one segment ``` ### Migration depuis 0.1 Le rôle `switch` et le champ `segments..switch` n'existent plus : `labctl` les refuse avec un message qui dit quoi faire. Pour une topologie 0.1 : 1. `role: switch` devient `role: router` ; 2. le routeur déclare `segments: []` et, de préférence, une adresse fixée (`addresses`) — en 0.1, le switch n'avait que la passerelle ; 3. `segments..switch: ` devient `segments..routers: []` ; 4. ses `secondary` restent valables : elles vont désormais sur son interface du segment, et non plus sur un bridge interne. ## FRR Au premier démarrage, cloud-init installe FRR (`frr-stable` de `deb.frrouting.org`, sans les paquets recommandés), active `bgpd` — et `bfdd` sur les routeurs et les route reflectors, `vrrpd` sur les routeurs d'un segment en VRRP —, puis dépose le `frr.conf` du nœud et redémarre FRR. La mise à jour des index de paquets est réessayée pendant cinq minutes : un nœud peut démarrer avant que le routeur, par lequel il sort, n'ait posé son NAT. La **clé du dépôt FRR** n'est pas téléchargée au démarrage : elle est enregistrée dans `labctl` (`internal/render/frrouting.gpg`) et déposée par cloud-init. Elle a été récupérée le 2026-10-04 sur `deb.frrouting.org` ; les empreintes de ses clés primaires sont publiées sous la même valeur sur `keys.openpgp.org` et `keyserver.ubuntu.com` : ```text 3D99 68AC 9AE7 BE11 6928 8DDB 1FD5 8398 95F5 7FDA David Lamparter 4A56 C773 8BB3 F815 95A8 05D2 A832 7699 08F1 3ED1 FRRouting Debian Repository A90F C36D 9429 4097 98E9 C2D8 74DE ED43 AB19 4DBF Jafar Al-Gharaibeh ``` Une clé renouvelée par FRR fera échouer l'installation (signature inconnue) : remplacer le fichier après avoir vérifié les nouvelles empreintes. **Ce que vérifie** `labctl up`, une fois cloud-init terminé sans erreur : les `services` déclarés par chaque nœud, et `frr` sur chaque nœud qui en a un. Ce contrôle couvre ce que cloud-init ne voit pas — une provision qui arme un redémarrage, par exemple : la VM redémarrée ne rejoue pas `runcmd`. > [!NOTE] > **Le routeur du lab est un Linux avec FRR, par choix.** Il joue le rôle générique de > routeur de cluster : passerelle des nœuds et, dans l'exemple, session eBGP avec BFD vers le > route reflector, dont il n'accepte que la loopback. L'équipement réel d'une infrastructure > (MikroTik, Cisco, Juniper, Arista…) n'a besoin que de BGP et d'EVPN ; sa configuration propre > au constructeur n'a pas sa place dans le lab. ## Rendu des VM `labctl render` produit, pour chaque nœud, ce qu'il faut pour démarrer sa VM — sans rien lancer : ```text $ go run ./cmd/labctl render -key ~/.config/labctl/ssh/lab_ed25519.pub examples/evpn-2hv/topology.yml ``` `//` reçoit : - **`qemu.args`** — les arguments de `qemu-system-x86_64`, **un par ligne** : rien à échapper, rien à interpréter par un shell ; - **`meta-data`, `user-data`, `network-config`** — les trois fichiers NoCloud de cloud-init, à mettre dans une image de volume `cidata`. Les chemins de la VM (`disk.qcow2`, `seed.iso`, `console.log`, `qmp.sock`, `qemu.pid`) sont ceux du répertoire du nœud ; `-key` peut être répété, et accepte un fichier `authorized_keys` (lignes vides et commentaires ignorés). Les fichiers sont créés en `0600`. Ce que contiennent les arguments QEMU d'un nœud — côté réseau : ```text -netdev user,id=mgmt0,restrict=on,ipv6=off,hostfwd=tcp:127.0.0.1:2203-:22 -device virtio-net-pci,netdev=mgmt0,mac=02:4d:00:03:00:00,romfile= -netdev tap,id=underlay,ifname=lt3,script=no,downscript=no -device virtio-net-pci,netdev=underlay,mac=02:4c:00:03:00:00,host_mtu=9000,romfile= ``` Les choix qui s'y lisent : - **machine** `q35`, `-accel kvm -cpu host` — le KVM imbriqué des nœuds en dépend ; `-nodefaults` pour qu'aucun périphérique implicite ne s'ajoute ; - **administration** (`mgmt0`) : le NAT de QEMU, MAC `02:4d:::00:00`, SSH redirigé sur la boucle locale de l'hôte. `restrict=on` pour tous les nœuds **sauf les routeurs** : un nœud isolé ne joint ni l'hôte ni l'extérieur par là, seule la redirection SSH passe. `ipv6=off` partout (voir plus bas) ; - **segments** : un tap créé par `labctl up` (`script=no` : QEMU ne lance aucun script), branché sur le bridge du segment ; `host_mtu` annonce le MTU du segment au guest ; - `romfile=` vide sur toutes les cartes : pas de ROM de démarrage réseau, donc pas de repli sur un démarrage PXE si le firmware ne trouve pas le disque. Pendant les premiers essais, une VM restée bloquée sans rien écrire sur sa console, CPU au repos, avait toutes les apparences de ce repli ; la cause n'a pas été isolée, l'option est une précaution. Ce que fait cloud-init : - **toutes les VM** : interfaces nommées d'après leur MAC (`mgmt0`, nom du segment), `dhcp4: false` partout, `mgmt0` en `10.0.2.15/24` ; connexion SSH par clé seulement, utilisateur `debian`, `root` désactivé, mot de passe refusé ; - **un nœud** : adresse et `secondary` sur chaque segment, MTU du segment, route par défaut et DNS sur le premier de ses segments qui a une passerelle ; `mgmt0` **sans passerelle** ; - **un routeur** : mêmes adresses, route par défaut par `mgmt0` ; un service `lab-router` active le routage, pose les passerelles (adresse ou `macvlan` VRRP, voir [Passerelle et routeurs](#passerelle-et-routeurs)) et le NAT nftables. Le service est rejoué à chaque démarrage. ### Vérifié sur de vraies VM Relevés faits avec le modèle 0.1 — le switch portait alors le bridge du segment, relié aux nœuds par des câbles UDP ; ce qui touche au L2 et à la passerelle est à revérifier avec les bridges de l'hôte. Le switch et le route reflector n'ont pas besoin de KVM imbriqué : `sw1` et `rr1` ont été démarrés **sur un Mac**, en émulation (TCG), avec Debian 12 `generic` et les fichiers produits par `labctl render`. | Vérification | Résultat | |---|---| | interfaces nommées et adressées, bridge `br-underlay` en `10.250.0.1/24` | conforme | | service `lab-switch` actif, y compris après redémarrage | conforme | | `ping -M do -s 8972` de `rr1` vers le switch (MTU 9000, sans fragmentation) | passe | | `ping -M do -s 8973` (MTU 9001) | refusé : `message too long, mtu=9000` | | Internet depuis `rr1` en IPv4 | passe, par `10.250.0.1` | | `rr1` vers un service TCP de l'hôte par `mgmt0` — le switch, témoin, y parvient | bloqué | | `rr1` vers Internet par `mgmt0` | bloqué | Un défaut trouvé par cet essai, et corrigé : sans `ipv6=off`, le NAT de QEMU annonce un préfixe IPv6 et `mgmt0` reçoit une **route IPv6 par défaut** — vers une impasse, puisque `restrict=on` bloque tout. Pas de fuite, mais chaque programme qui tente l'IPv6 d'abord (le DNS renvoie d'abord des adresses IPv6) attend un délai avant de se rabattre sur l'IPv4. > [!NOTE] > Un `ping` vers `10.0.2.2` n'est pas un test d'isolation : c'est la passerelle virtuelle de QEMU > qui répond elle-même, `restrict=on` ou non. Seule une connexion vers un vrai service de l'hôte, > avec un témoin qui y parvient, le prouve. ## Lancement des VM `labctl` s'exécute **sur l'hôte du lab**. Il garde l'état du lab dans un répertoire (`-run`, par défaut `~/lab-run`) : `status`, `down` et `ssh` n'ont donc pas besoin de la topologie. ```text labctl up [-run dir] [-cache dir] [-timeout 20m] labctl status [-run dir] labctl down [-run dir] labctl ssh [-run dir] [commande…] ``` **`labctl up`** 1. refuse de continuer si un lab tourne déjà dans le répertoire ; 2. télécharge chaque image dans le cache (`-cache`, par défaut `~/.cache/labctl`) et la vérifie contre `SHA512SUMS` ; une image déjà présente et toujours conforme n'est pas retéléchargée, la liste des sommes est relue à chaque fois ; 3. génère une paire de clés SSH dans le répertoire du lab, si elle n'existe pas encore ; 4. pour chaque nœud : fichiers de `labctl render`, disque **neuf** en overlay qcow2 sur l'image (`qemu-img create -b`, 20 Gio annoncés), image `cidata` et `files.iso` (`genisoimage`) ; 5. crée les bridges des segments et les taps des nœuds (voir [Réseau de l'hôte](#réseau-de-lhôte)), et refuse de continuer si l'un d'eux existe déjà ; 6. démarre les QEMU, **routeurs d'abord**, détachés (`-daemonize`) : ils survivent à la session SSH qui les a lancés ; 7. attend sur chaque nœud la fin de cloud-init (`cloud-init status --wait` par SSH), jusqu'au délai `-timeout`, puis vérifie ses services (`frr` compris quand il est installé). La topologie est copiée dans `/topology.yml`. Un échec laisse les nœuds démarrés en place : `labctl status`, puis `labctl down`. **`labctl status`** — pour chaque nœud : rôle, état du processus QEMU, PID, port SSH sur la boucle locale ; pour chaque segment : bridge présent ou absent, passerelle. **`labctl down`** — arrête chaque QEMU par `SIGTERM`, puis `SIGKILL` au bout de 30 s, puis supprime les taps et les bridges du lab. Les disques sont conservés jusqu'au prochain `up`, qui les recrée. `up` et `down` doivent tourner **en root** : ils créent et suppriment des interfaces de l'hôte. ### Réseau de l'hôte Pour chaque segment, `labctl up` exécute : ```text ip link add name lb- type bridge stp_state 0 mcast_snooping 0 ip link set dev lb- addrgenmode none ip tuntap add dev lt mode tap # pour chaque port du segment ip link set dev lt addrgenmode none ip link set dev lt mtu master lb- up ip link set dev lb- mtu up ``` - **Aucune adresse côté hôte**, IPv4 ni IPv6 (`addrgenmode none` : pas même de lien local) : l'hôte n'est pas joignable depuis un segment, et ne route rien entre eux. - **Pas de STP ni de surveillance IGMP** : le bridge se comporte comme un switch simple, et les annonces VRRP (`224.0.0.18`) circulent sans dépendre d'un querier. - Si `br_netfilter` est chargé sur l'hôte, `bridge-nf-call-iptables` est mis à 0 : le pare-feu de l'hôte ne filtre pas le trafic des segments. - Un lab par hôte : les noms `lb-*` et `lt*` ne sont pas propres à un répertoire `-run`. **`labctl ssh`** — ouvre un shell sur un nœud, ou y exécute une commande, avec la clé générée par `up`. `labctl` cède la place à `ssh`, dont le code de retour est donc celui de la commande. Un terminal n'est demandé (`-t`) que si l'entrée de `labctl` en est un : depuis un script, ni pseudo-terminal ni `\r\n` dans la sortie. Comme `ssh`, `labctl ssh` recolle ses arguments par des espaces et les confie à un shell distant — et depuis le poste, il y en a **deux** : celui du serveur, puis celui de la VM. Une commande qui contient elle-même des guillemets se passe en une seule chaîne : ```text $ echo | scripts/lab-host.sh ssh './labctl ssh hv1 sh -c "exit 42"'; echo "rc 42=$?" rc 42=0 $ echo | scripts/lab-host.sh ssh "./labctl ssh hv1 'sh -c \"exit 42\"'"; echo "rc 42=$?" rc 42=42 ``` Dans le premier cas, la VM reçoit `sh -c exit 42` : `exit` sans argument, `42` en `$0`. Pour plus d'une commande, passer un script sur l'entrée standard : `scripts/lab-host.sh ssh "./labctl ssh hv1 'sudo bash -s'" < script.sh`. Un processus n'est tenu pour celui d'un nœud que si son PID, lu dans `qemu.pid`, désigne un processus vivant dont la ligne de commande (`/proc//cmdline`) contient `-name `. Un PID réutilisé par un autre programme n'est donc jamais signalé. > [!WARNING] > Le cache range une image sous son nom de fichier, et l'URL de Debian est `latest` : une > nouvelle publication remplace le fichier, et les overlays existants pointeraient sur une base > différente. `up` recrée toujours les disques, ce qui suffit avec un lab par serveur ; **ne pas > relancer un QEMU à la main** à partir d'un `qemu.args` après un `up` ultérieur. ### Vérifié sur le serveur de lab Avec le modèle 0.1 (voir la remarque précédente). Le 2026-10-04, sur un Xeon E5-2640 v3, Debian 12 et QEMU 7.2 sur le serveur, topologie à deux hôtes : | Vérification | Résultat | |---|---| | `ping -M do -s 8972` de hv1 à hv2 à travers le switch | passe | | `ping -M do -s 8973` | refusé : `message too long, mtu=9000` | | sortie Internet de hv1 | par le switch, HTTPS 200 ; aucune route IPv6 globale | | hv1 vers un service TCP du serveur par `mgmt0` — sw1, témoin, y parvient (200) | refusé | | hv1 vers Internet par `mgmt0`, route forcée via `10.0.2.2` — sw1 y parvient | refusé | | `/dev/kvm` et `nested` dans hv1 | présent, `Y` | | racine de hv1 (overlay de 20 Gio) | 20 Go : `growpart` agrandit la partition au premier démarrage | | code de retour à travers `lab-host.sh ssh` et `labctl ssh`, sans terminal | propagé jusqu'au poste | | `scripts/lab-host.sh ssh './labctl ssh hv1'` depuis un terminal | shell interactif | | `labctl down` puis `labctl up` d'une autre topologie | conforme | `labctl up` d'une topologie sans provision prend moins d'une minute, téléchargement et vérification de l'image (427 Mio) compris : l'essentiel du temps d'une campagne est la livraison du serveur et ce que les provisions installent. ## Facturation > [!WARNING] > Un serveur Elastic Metal est facturé **de sa création à sa suppression, éteint compris**. > Éteindre ne suffit pas : il faut supprimer. La granularité n'est pas documentée par Scaleway — > compter chaque heure entamée comme une heure pleine. Ce que le script garantit : - il ne commande **jamais** d'offre mensuelle : il exige une seule offre au nom demandé, en facturation horaire, en stock et sans frais de mise en service, sinon il refuse avant toute création. La CLI `scw` n'est pas utilisée pour cette raison : son `server create type=…` choisit l'offre par son seul nom et peut tomber sur la mensuelle, qui engage un mois ; - il refuse de créer un second serveur si un serveur de lab existe déjà ; - `down` agit sur **tous** les serveurs portant le tag `labctl` dans le projet, et `session` y ajoute l'identifiant reçu à la création : un serveur créé juste avant une interruption est rattrapé ; - une suppression refusée pendant la livraison ou l'installation est réessayée tant qu'elle dure, dans la limite du délai d'installation augmenté du délai de suppression ; - le serveur n'est déclaré supprimé qu'au 404 de l'API, jamais sur une erreur passagère ; - un échec de suppression se termine par `SERVEUR(S) DE LAB TOUJOURS FACTURÉ(S)` et un code d'erreur. Ce qu'il ne peut pas garantir : un `SIGKILL`, une coupure de courant ou une mise en veille du poste qui lance la session. En cas de doute, toujours : ```bash scripts/lab-host.sh status scripts/lab-host.sh down ``` ## Diagnostic **`aucune clé SSH active dans le projet`** — aucune clé SSH n'est enregistrée dans le projet de lab. En ajouter une dans la console (projet → Clés SSH). **`offre horaire EM-B420E-NVME : 0 correspondance(s)`** — l'offre n'existe pas dans la zone en facturation horaire. Sans conséquence si une autre zone candidate la propose ; sinon, vérifier `LAB_ZONES` et `LAB_OFFER`. **`création incertaine`** — la création a échoué ou n'a pas rendu d'identifiant. Le serveur a pu être créé malgré tout — cas typique : le quota (identité non validée), ou une réponse perdue. Le script indique s'il voit un serveur de lab ; dans tous les cas, lancer `status` puis `down`. **`SSH injoignable`** — l'installation est terminée mais SSH ne répond pas après 10 minutes. Avec une clé matérielle (Yubikey), chaque connexion demande un PIN ou un toucher : utiliser la clé dédiée du lab. Le serveur est toujours facturé : `down`. **`SERVEUR(S) DE LAB TOUJOURS FACTURÉ(S)`** — la suppression n'a pas abouti dans les délais. Relancer `down` ; si l'erreur persiste, supprimer depuis la console Scaleway. **`HTTP 403 insufficient permissions`** — la clé d'API est authentifiée mais n'a pas le droit demandé — en général la lecture des clés SSH du projet. Compléter la politique de la clé, limitée au projet. ## Sécurité - La clé secrète n'apparaît ni dans les arguments des processus (elle est passée à `curl` par un descripteur de fichier), ni dans les journaux, ni dans l'environnement de `ssh`. - **Ne jamais lancer le script sous** `bash -x` : la trace afficherait la clé. - Le serveur n'expose que SSH, par clé. - Une clé secrète qui a circulé ailleurs que dans `scaleway.env` (conversation, terminal partagé, capture d'écran) se régénère. - **Clé SSH des VM** : générée par `labctl up` sur le serveur, c'est la seule clé autorisée dans les VM. Elle ne quitte jamais le serveur, n'ouvre que les VM du lab — qui n'écoutent qu'en boucle locale — et disparaît avec lui. La clé publique du poste n'est jamais envoyée aux VM. - **Segments isolés de l'hôte** : bridges et taps sans adresse (voir [Réseau de l'hôte](#réseau-de-lhôte)) ; seuls les routeurs sortent, par le NAT de QEMU. - **Clés d'hôte des VM non vérifiées** par `labctl ssh` (`known_hosts` jetable) : elles changent à chaque `up`. Acceptable uniquement parce que la connexion reste sur la boucle locale d'un serveur auquel on s'est authentifié. - **Image** : `SHA512SUMS` vient de la même origine que l'image, en HTTPS. La vérification protège contre la corruption, pas contre une origine compromise ; la signature GPG de Debian (`SHA512SUMS.sign`) n'est pas encore vérifiée. ## Tests ```bash go test ./... bash scripts/lab-host_test.sh ``` Environ une minute et demie, sans réseau : la suite remplace `curl` par une fausse API Scaleway qui se place dans le pire cas (offre mensuelle listée avant l'horaire, serveurs d'autres projets, suppressions refusées, erreurs 503, serveur qui tarde à disparaître) et `ssh` par un faux client. Elle tourne sous bash 5 comme sous le bash 3.2 de macOS.