All checks were successful
Tests / test (push) Successful in 3m46s
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
115 lines
6 KiB
Markdown
115 lines
6 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 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`](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`.
|