labctl/README.md
GnomeZworc e9a0c19b72
All checks were successful
Tests / test (push) Successful in 3m46s
labctl: segments sur des bridges de l'hôte, routeurs et passerelle VRRP #2
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
2026-10-13 09:57:09 +02:00

6 KiB

labctl

Monte un lab réseau virtuel à partir d'une topologie YAML : des VM QEMU/KVM reliées par des segments L2 (des bridges de l'hôte), des routeurs qui font passerelle — en VRRP quand ils sont plusieurs — 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, les bridges des segments et les taps des nœuds, démarre les nœuds (routeurs d'abord), attend la fin de cloud-init puis vérifie les services de chaque nœud ; down arrête les nœuds et supprime bridges et taps. up et down tournent en root. Un fichier invalide est refusé avec toutes ses erreurs et un code de sortie 1.

Topologie

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

  • images : url et sums (HTTPS).
  • segments : cidr IPv4 (/8 à /30), mtu (9000 par défaut), routers (facultatif, par ordre de priorité : aucun = L2 pur, un = passerelle sur son interface, plusieurs = passerelle en VRRP par FRR). Nom ≤ 12 caractères. Chaque segment est un bridge lb-<segment> de l'hôte.
  • nodes : role (router, rr ou host), image, cpus, memory (Mio), segments, addresses (adresse fixée par segment). Un routeur est un nœud comme les autres, attaché aux segments dont il est routeur. 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 router et rr, vrrpd sur les routeurs en VRRP) ;
    • 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 qui porte la route par défaut : premier segment qui a une passerelle, mgmt0 pour un routeur) et LAB_FILES. Ordre au premier démarrage : service du routeur 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 (s'il a un routeur) ; adresses suivantes dans l'ordre de déclaration des nœuds ; MAC 02:4c:<nœud>:<nœud>:<segment>:00 ; tap lt<i> par port ; SSH d'administration sur 127.0.0.1:<2200 + rang>. Réordonner les nœuds change les adresses. Migration depuis 0.1 (rôle switch) : voir le guide.

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.