From ac08803fcce3a9aa182f56571648f42b251fda97 Mon Sep 17 00:00:00 2001 From: GnomeZworc Date: Mon, 12 Oct 2026 21:21:56 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20guide=20de=20r=C3=A9f=C3=A9rence=20repr?= =?UTF-8?q?is=20de=20two?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: GnomeZworc --- README.md | 2 + docs/guide.md | 539 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 541 insertions(+) create mode 100644 docs/guide.md diff --git a/README.md b/README.md index 1efab1f..b8af8b0 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ que l'on veut tester. Le plan est **déterministe** : même fichier, mêmes adre VM). `scripts/lab-host.sh` loue et prépare un tel hôte à l'heure chez Scaleway (Elastic Metal) ; c'est un exemple de fournisseur, pas une dépendance. +Référence détaillée, choix et vérifications : [`docs/guide.md`](docs/guide.md). + ## Installer Depuis une release : télécharger `labctl_linux_amd64` (et `lab-host.sh` si besoin) **et vérifier** diff --git a/docs/guide.md b/docs/guide.md new file mode 100644 index 0000000..ae47090 --- /dev/null +++ b/docs/guide.md @@ -0,0 +1,539 @@ +# 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 +portés par un switch). Exemple livré : [`examples/evpn-2hv/topology.yml`](../examples/evpn-2hv/topology.yml). + +Chaque nœud non-switch est relié au switch de chacun de ses segments par un câble virtuel QEMU ; +le switch met ces câbles dans un bridge et porte la passerelle du segment. + +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`** — `switch` (un nœud de rôle `switch`), `cidr` IPv4 entre `/8` et `/30`, `mtu` +facultatif — 9000 par défaut, entre 1280 et 9000. Nom : 12 caractères au plus, minuscules et +chiffres, parce qu'il devient le nom d'interface dans les VM et, préfixé de `br-`, celui du +bridge (15 caractères au plus sous Linux). + +**`nodes`** — `role` (`switch`, `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 switch ne déclare ni `segments` ni +`addresses` : il porte ceux dont il est le `switch`. 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. Sur un switch, elles vont sur le bridge du segment ; +- `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 de son premier segment, +qui porte la route par défaut) 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 — script du switch 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. + +Ce que l'outil en déduit, de façon déterministe — même fichier, même plan : + +| | | +|---|---| +| Passerelle d'un segment | la première adresse du CIDR, portée par le switch sur `br-` | +| Adresse d'un nœud | les suivantes, **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 | +| Câbles | un par couple (segment, nœud), segments puis nœuds dans l'ordre de déclaration ; le câble *i* utilise les ports UDP `20000 + 2i` (côté nœud) et `20001 + 2i` (côté switch) | +| MAC | `02:4c::::` — préfixe localement administré, rang du nœud sur deux octets, rang du segment, `00` côté nœud et `01` côté switch | +| Interfaces | côté nœud, le nom du segment ; côté switch, `p`, du rang du câble | +| 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 et les +> ports**. C'est assumé pour un lab ; `labctl plan` montre le résultat avant tout lancement. + +Limites : 1000 nœuds, 256 segments, et autant de câbles que la plage UDP le permet (22 768). + +`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 4, segments 1, cables 3 + +nodes + name role image cpus memory ssh + sw1 switch debian12 2 1024 MiB 127.0.0.1:2200 + rr1 rr debian12 1 1024 MiB 127.0.0.1:2201 + hv1 host debian12 2 2048 MiB 127.0.0.1:2202 + hv2 host debian12 2 2048 MiB 127.0.0.1:2203 + +roles + name loopback secondary frr provision post_provision files services + sw1 - underlay 169.254.0.1/28 sw1.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, switch sw1, bridge br-underlay, gateway 192.168.14.1 + node interface address mac udp switch port mac udp + rr1 underlay 192.168.14.2/24 02:4c:00:01:00:00 20000 <-> sw1 p0 02:4c:00:01:00:01 20001 + hv1 underlay 192.168.14.11/24 02:4c:00:02:00:00 20002 <-> sw1 p1 02:4c:00:02:00:01 20003 + hv2 underlay 192.168.14.12/24 02:4c:00:03:00:00 20004 <-> sw1 p2 02:4c:00:03:00:01 20005 +``` + +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 switch +segment underlay: cidr 10.250.0.0/31 prefix length out of range [/8, /30] +node sw1: switch carries no segment +``` + +## 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 le switch et le route reflector —, 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 switch, 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 switch du lab est un routeur 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 — extrait réel, côté réseau : + +```text +-netdev +user,id=mgmt0,restrict=on,ipv6=off,hostfwd=tcp:127.0.0.1:2202-:22 +-device +virtio-net-pci,netdev=mgmt0,mac=02:4d:00:02:00:00,romfile= +-netdev +dgram,id=underlay,local.type=inet,local.host=127.0.0.1,local.port=20002,remote.type=inet,remote.host=127.0.0.1,remote.port=20003 +-device +virtio-net-pci,netdev=underlay,mac=02:4c:00:02: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 le switch** : 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) ; +- **câbles** : `dgram` sur `127.0.0.1`, les deux extrémités d'un câble se répondent (port local + de l'une = port distant de l'autre), `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, `p`), + `dhcp4: false` partout, `mgmt0` en `10.0.2.15/24` **sans passerelle** ; connexion SSH par + clé seulement, utilisateur `debian`, `root` désactivé, mot de passe refusé ; +- **un nœud** : adresse sur chaque segment, MTU du segment, route par défaut et DNS + (`1.1.1.1`, `8.8.8.8`) sur son **premier** segment — la sortie Internet passe par le switch ; +- **le switch** : route par défaut par `mgmt0` ; un service `lab-switch` crée un bridge + `br-` par segment (STP désactivé, MTU du segment), y branche ses ports, porte la + passerelle, active le routage et masque (NAT nftables) les segments vers `mgmt0`. Le service + est rejoué à chaque démarrage. + +### Vérifié sur de vraies VM + +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. démarre les QEMU, **switchs d'abord**, détachés (`-daemonize`) : ils survivent à la session + SSH qui les a lancés ; +6. 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. + +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. + +**`labctl down`** — arrête chaque QEMU par `SIGTERM`, puis `SIGKILL` au bout de 30 s. Les disques +sont conservés jusqu'au prochain `up`, qui les recrée. + +**`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 + +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. +- **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.