labctl/README.md
GnomeZworc ac08803fcc
All checks were successful
Tests / test (push) Successful in 3m28s
docs: guide de référence repris de two
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-12 21:21:56 +02:00

5.4 KiB

labctl

Monte un lab réseau virtuel à partir d'une topologie YAML : des VM QEMU/KVM reliées par des segments L2, des switchs qui font passerelle et NAT, FRR installé et configuré sur les nœuds qui le demandent, et une provision libre (scripts, fichiers, services à vérifier) pour installer ce que l'on veut tester. Le plan est déterministe : même fichier, mêmes adresses, MAC et ports.

labctl tourne sur tout hôte Linux avec KVM (virtualisation imbriquée si l'hôte est lui-même une 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.

Installer

Depuis une release : télécharger labctl_linux_amd64 (et lab-host.sh si besoin) et vérifier leur somme dans SHA256SUMS. Ou compiler :

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o labctl ./cmd/labctl

Sur l'hôte : qemu-system-x86_64, qemu-img, genisoimage, ssh-keygen, et /dev/kvm.

Commandes

labctl plan <topologie.yml>                   valide et affiche le plan, sans rien lancer
labctl render -key <clé.pub> <topologie.yml> <rép>  écrit les arguments QEMU et les seeds cloud-init
labctl up [-run rép] [-cache rép] [-timeout durée] <topologie.yml>
labctl status | down | ssh <nœud> [commande]  [-run rép]

Par défaut : -run ~/lab-run, -cache ~/.cache/labctl, -timeout 20m. up télécharge et vérifie les images (SHA512SUMS), crée des disques neufs, démarre les nœuds (switchs d'abord), attend la fin de cloud-init puis vérifie les services de chaque nœud. Un fichier invalide est refusé avec toutes ses erreurs et un code de sortie 1.

Topologie

Voir examples/evpn-2hv/ : un switch, un route reflector et deux hôtes en EVPN.

  • images : url et sums (HTTPS).
  • segments : switch, cidr IPv4 (/8 à /30), mtu (9000 par défaut). Nom ≤ 12 caractères.
  • nodes : role (switch, rr ou host), image, cpus, memory (Mio), segments, addresses (adresse fixée par segment). Champs facultatifs :
    • secondary — adresses supplémentaires hors du CIDR du segment ;
    • loopback — adresse sur une interface dummy lo1 ;
    • frr — un frr.conf déposé tel quel ; FRR est installé au premier démarrage (bgpd, et bfdd sur switch et rr) ;
    • provision / post_provision — scripts exécutés avant / après FRR ;
    • files — {<nom>: <chemin>}, fichiers ou répertoires gravés dans un ISO propre au nœud et recopiés dans /etc/lab/files/<nom> avant les scripts (aucune limite de taille cloud-init) ;
    • services — unités systemd que up vérifie actives.

Les chemins sont relatifs au fichier de topologie. Les scripts reçoivent LAB_NODE, LAB_UPLINK (interface du premier segment, qui porte la route par défaut) et LAB_FILES. Ordre au premier démarrage : script du switch ou de la loopback, provision, FRR, post_provision — dans un seul script en set -eu, la première étape en échec met cloud-init en erreur.

Déduit de façon déterministe : passerelle d'un segment = première adresse (portée par le switch) ; adresses suivantes dans l'ordre de déclaration des nœuds ; MAC 02:4c:<nœud>:<nœud>:<segment>:<côté> ; SSH d'administration sur 127.0.0.1:<2200 + rang>. Réordonner les nœuds change les adresses.

Hôte loué chez Scaleway : scripts/lab-host.sh

lab-host.sh plan | up | status | ssh [cmd] | prepare | push <topologie> | down | session [cmd]

plan et status sont gratuits ; up et session créent un serveur facturé à l'heure (chaque heure entamée est due). Toujours commencer par plan. push dépose labctl (compilé depuis ce dépôt, ou celui de LABCTL_BIN) et le répertoire de la topologie ; ensuite lab-host.sh ssh './labctl up topology/<topologie>'.

Prérequis : un projet Scaleway dédié (down supprime tous les serveurs portant le tag labctl), une clé d'API limitée à ce projet, des clés SSH publiques enregistrées dans le projet. Fichiers locaux : ~/.config/labctl/scaleway.env (0600, SCW_SECRET_KEY, SCW_DEFAULT_PROJECT_ID), ~/.config/labctl/ssh/lab_ed25519 (clé dédiée facultative), état sous ~/.cache/labctl/. Tout se surcharge par variable d'environnement (lab-host.sh sans argument).

Garanties : jamais d'offre mensuelle ni de frais de mise en service, pas de second serveur, suppression réessayée et vérifiée jusqu'au 404, échec signalé par SERVEUR(S) DE LAB TOUJOURS FACTURÉ(S). Pas de garantie face à un SIGKILL ou une coupure du poste : en cas de doute, status puis down.

Sécurité

  • La clé secrète Scaleway n'apparaît ni dans les arguments de processus, ni dans les journaux, ni dans l'environnement de ssh. Ne jamais lancer lab-host.sh sous bash -x.
  • La clé SSH des VM est générée sur l'hôte et ne le quitte pas ; les VM n'écoutent qu'en boucle locale. Leurs clés d'hôte ne sont pas vérifiées (known_hosts jetable).
  • Les images sont vérifiées par SHA512SUMS, servi par la même origine : cela protège de la corruption, pas d'une origine compromise.

Tests

go test ./...
bash scripts/lab-host_test.sh

Sans réseau : curl et ssh sont remplacés par de faux clients (API Scaleway dans le pire cas).

Licence

PolyForm Noncommercial 1.0.0 — voir LICENSE.