Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
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:urletsums(HTTPS).segments:cidrIPv4 (/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 bridgelb-<segment>de l'hôte.nodes:role(router,rrouhost),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 interfacedummylo1;frr— unfrr.confdéposé tel quel ; FRR est installé au premier démarrage (bgpd, etbfddsurrouteretrr,vrrpdsur 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 queupvé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 lancerlab-host.shsousbash -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_hostsjetable). - 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.