# 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`](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 valide et affiche le plan, sans rien lancer labctl render -key écrit les arguments QEMU et les seeds cloud-init labctl up [-run rép] [-cache rép] [-timeout durée] labctl status | down | ssh [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` — `{: }`, fichiers **ou répertoires** gravés dans un ISO propre au nœud et recopiés dans `/etc/lab/files/` 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::::` ; 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 | 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/'`. 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`.