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

108 lines
5.4 KiB
Markdown

# 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 <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`.