Piloter Marionnet par un script ou par une IA

Ce texte fait foi ; la version anglaise en est la traduction.

Depuis 2026, Marionnet peut recevoir ses ordres d’un programme, et non plus seulement de la souris. Un script peut ainsi construire le réseau d’un TP, le démarrer, attendre que les machines soient prêtes, leur faire exécuter des commandes, puis vérifier que le réseau est bien dans l’état voulu ; un agent conversationnel, c’est-à-dire une IA capable d’exécuter des commandes (un assistant de programmation en ligne de commande, par exemple), peut en faire autant à partir d’un énoncé rédigé en langage naturel. Notons que Marionnet n’embarque aucune IA : c’est la vôtre qui le pilote. Pendant tout ce temps, la fenêtre de Marionnet reste à l’écran : vous voyez le réseau se construire et les machines démarrer, et vous pouvez même intervenir à la souris en même temps que le programme.

Quelques usages, pour fixer les idées :

• préparer le projet d’un TP sans cliquer, puis le reconstruire à l’identique d’une année sur l’autre, ou en plusieurs variantes ;
• livrer aux étudiants un projet qui démarre tout seul ;
• vérifier en une commande qu’un réseau répond à l’énoncé (adresses, routes, connectivité), plutôt que d’ouvrir chaque machine l’une après l’autre ;
• faire construire, puis vérifier un TP par une IA, qui pilote Marionnet à votre place.

Ce guide présente ce mode de fonctionnement du point de vue de l’utilisateur. Les détails techniques, qui ne servent que dans des cas particuliers, sont repliés dans des encadrés qui s’ouvrent d’un clic.

1. Lancer Marionnet en mode piloté

Il suffit d’ajouter une option au lancement de Marionnet :

marionnet --control-socket /tmp/marionnet.sock

Le fichier /tmp/marionnet.sock est le point de rendez-vous entre Marionnet et le programme qui le pilote (techniquement, une socket Unix, autrement dit un fichier spécial par lequel deux programmes d’une même machine se parlent). Sans cette option, ce point de rendez-vous n’existe pas, et Marionnet ne peut donc pas être piloté : c’est vous qui décidez, à chaque lancement, s’il accepte des ordres venus d’ailleurs.

Les ordres s’envoient ensuite par mrnctl, le pilote, installé avec Marionnet (son nom complet est marionnet-ctl), auquel on indique une fois pour toutes le point de rendez-vous :

export MARIONNET_CONTROL_SOCKET=/tmp/marionnet.sock

mrnctl new /tmp/tp1.mar
mrnctl add machine m1
mrnctl start m1

Chaque ligne est un ordre, que Marionnet exécute comme s’il venait de la souris : la machine m1 apparaît sur le plan du réseau, puis elle démarre, et son terminal s’ouvre.

La touche TAB complète les ordres, leurs options, et surtout les noms réels du projet ouvert (composants, ports, champs), qu’elle demande au Marionnet en cours d’exécution :

$ mrnctl connect c2 s1:<TAB>
s1:port1  s1:port2  s1:port3  s1:port4

Si vous avez installé Marionnet par un paquet (.deb ou .rpm) ou par son programme d’installation, vous n’avez rien à faire pour en profiter : la complétion est installée avec le logiciel, et le terminal la charge de lui-même, dans tout terminal ouvert après l’installation.

# Debian, Ubuntu :
sudo apt install bash-completion

# Fedora, Rocky Linux, AlmaLinux :
sudo dnf install bash-completion

# openSUSE :
sudo zypper install bash-completion

. bin/scripts/marionnet-completion.bash

mrnctl help > ~/.marionnet-grammar.json
export MARIONNET_CTL_GRAMMAR=~/.marionnet-grammar.json

Seul ou à deux : qui tient les commandes ?

Marionnet ouvre parfois de lui-même une fenêtre : la page de garde au démarrage, un avertissement, le récapitulatif des adaptations faites à un ancien projet, une erreur. Ce qu’il convient de faire de ces fenêtres dépend de qui se trouve devant l’écran, et c’est la première question à vous poser.

• Le programme pilote seul. Personne n’est là pour lire ces fenêtres, ni pour les fermer, et une fenêtre qui attend une réponse bloquerait tout. Marionnet les affiche donc deux secondes, puis les ferme de lui-même, en conservant ce qu’elles disaient, que le programme relit par mrnctl notifications. C’est le comportement par défaut : il n’y a rien à ajouter à la commande de lancement.

• Le programme et un humain pilotent ensemble. Vous construisez par exemple le réseau par un script, mais vous voulez ensuite cliquer vous-même pour l’explorer ; ou bien vous montrez Marionnet à des étudiants pendant qu’un script le fait travailler. Il faut alors que les fenêtres restent à l’écran, comme d’habitude, et c’est le rôle de l’option --keep-dialogs :

  marionnet --control-socket /tmp/marionnet.sock --keep-dialogs
  

  C’est donc l’humain qui lit et ferme les fenêtres, et qui répond aux questions que pose Marionnet, y compris quand un ordre du programme les a provoquées ; le programme attend alors sa réponse. En contrepartie, mrnctl notifications ne recueille plus rien.

Dans les deux cas, l’humain garde la main : rien ne l’empêche de cliquer pendant qu’un programme pilote, et Marionnet ne répond jamais à sa place à une question qu’il a lui-même déclenchée.

Le cas d’une IA se ramène à l’un des deux précédents, selon la façon dont elle agit. Une IA qui exécute des commandes envoie ses ordres par mrnctl, exactement comme un script : elle prend la place du programme, et vous choisissez de la laisser piloter seule ou de piloter avec elle. Mais une IA capable de voir l’écran et de cliquer peut aussi prendre la place de l’humain, et cela sans aucune option, puisque Marionnet la traite alors comme un utilisateur ordinaire. Pour apprendre à une IA à piloter Marionnet, donnez-lui à lire ../marionnet-driving-skill.md, qui a été écrit à son intention : il lui explique comment construire, jouer et vérifier un TP par des commandes. La conception du TP n’est pas son objet, même si l’IA peut bien sûr vous y aider par ailleurs.

2. Un premier réseau piloté

Voici, en entier, un réseau semblable à celui de la page Premiers pas (deux machines reliées par un switch), construit, démarré et enregistré cette fois par un script :

export MARIONNET_CONTROL_SOCKET=/tmp/marionnet.sock

# Lancer Marionnet, puis attendre qu'il réponde :
marionnet --control-socket "$MARIONNET_CONTROL_SOCKET" &
until mrnctl status > /dev/null 2>&1; do sleep 0.5; done

# D'abord un projet, comme à la souris :
mrnctl new /tmp/demo.mar

# Les composants, puis les câbles et leurs deux extrémités :
mrnctl add machine m1
mrnctl add machine m2
mrnctl add switch  s1 --ports=4
mrnctl connect c1 m1:eth0 s1:port1
mrnctl connect c2 m2:eth0 s1:port2

# Les adresses :
mrnctl ifconfig-set m1 eth0 ipv4-address 10.0.0.1/24
mrnctl ifconfig-set m2 eth0 ipv4-address 10.0.0.2/24

# Démarrer, puis attendre que les machines tournent (cf. § 4) :
mrnctl start m1
mrnctl start m2
mrnctl wait m1 --state=on --timeout=120
mrnctl wait m2 --state=on --timeout=120

# Arrêter avant d'enregistrer (cf. § 5), puis quitter :
mrnctl stop m1
mrnctl stop m2
mrnctl wait-all --state=off --timeout=180
mrnctl save-as /tmp/demo.mar
mrnctl quit

On y retrouve, ligne à ligne, ce que l’on ferait à la souris. Les ports se désignent par leur nom, comme dans l’interface : une machine numérote ses cartes réseau à partir de 0 (eth0, eth1), un switch ses ports à partir de 1 (port1, port2). Une fois enregistré, ce projet se rejoue d’une seule ligne, l’option -r démarrant aussitôt tous ses composants :

marionnet --control-socket /tmp/marionnet.sock -r /tmp/demo.mar

Le répertoire examples/ contient des scripts complets de ce genre, prêts à être exécutés.

3. Ce que répond Marionnet

Chaque ordre reçoit une réponse d’une ligne. Quand l’ordre est accepté, elle commence par "ok":true ; quand il est refusé, par "ok":false, suivi d’un code et d’une explication en clair, ici « “m1” cannot start from state “on” » (la machine m1 est déjà allumée) :

{"ok":false,"error":"forbidden_transition","detail":"…"}

Un script n’a d’ailleurs pas besoin de lire la réponse pour savoir si l’ordre a réussi : comme toute commande Unix, mrnctl rend le code 0 en cas de succès, ce qui permet d’écrire mrnctl start m1 && echo démarrée.

Deux règles simples évitent la plupart des refus.

• Un programme ne peut faire que ce que permet l’interface graphique. Une machine allumée ne se supprime pas plus par un ordre que par la souris, et une machine déjà démarrée ne se démarre pas une seconde fois. Pour savoir ce qui est permis sur un composant à un instant donné, il suffit de le demander. Pour une machine éteinte, par exemple :

  mrnctl can m1
  # {"ok":true,"name":"m1","kind":"machine","state":"off",
  #  "can":["set","del","start"],"beyond_gui":[]}
  

  Le champ can donne les actions permises en ce moment : modifier la machine (set), la supprimer (del) ou la démarrer (start). Une fois allumée, elle ne pourra plus être supprimée, mais elle pourra être arrêtée (stop). Le champ beyond_gui signale, parmi les actions permises, celles qui n’ont pas de bouton dans l’interface, comme l’extinction brutale d’une seule machine (poweroff). Les câbles, eux, se modifient et se suppriment même quand le réseau fonctionne, comme dans l’interface graphique, et pour la même raison : on peut débrancher un câble réel et le rebrancher ailleurs sans rien éteindre.

• La liste des ordres se demande à Marionnet. mrnctl help donne tous les ordres avec leur syntaxe, et mrnctl help connect celle d’un seul. Cette liste s’enrichit d’une version à l’autre, de sorte que c’est la réponse du Marionnet que vous pilotez qui fait foi ; les deux encadrés qui suivent en donnent toutefois un aperçu.

mrnctl -q '.commands[].syntax' help

help [<command>]
status
ls [--kind=<kind>] [--can=<action>]
can [<component>]
add <kind> <name> [--ports=<n>] [--<field>=<value>]…
del <component>
get <component> [<field>]
set <component> <field> <value>
rename <component> <new name>
connect <cable> <node>:<port> <node>:<port> [--crossover]
rc-get <component> [<field>|--field=<field>]
rc-set <component> [<one-line content>]
    [--from=<absolute path>] [--enable|--disable]
    [--select|--unselect] [--terminal|--no-terminal]
    [--field=<field>]
ifconfig [<node>]
defects [<node>]
history [<node>]
documents
ifconfig-set <node> <port> <field> [<value>]
    [--restart|--no-restart]
defects-set <node> <port> <inward|outward> <field> [<value>]
    [--restart|--no-restart]
defects-set <cable> <leftward|rightward> <field> [<value>]
history-start <cow file>
history-del <cow file> [--except]
history-set <cow file> <field> [<value>]
history-export <cow file> <variant name> [--force]
open <absolute path>
new <absolute path> [--save|--no-save]
save
save-as <absolute path>
close [--save|--no-save]
notifications [--since=<n>] [--clear]
log <component> [<file>|--file=<file>] [--tail=<n>]
switch-info <switch> [<table>|--table=<table>]
report <component> [--timeout=<s>]
exec <component> <command-line> [--timeout=<s>]
wait <component> (--state=on|off|sleeping | --ready)
    [--timeout=<s>]
wait-all --state=on|off|sleeping [--timeout=<s>]
quit
start <component>
stop <component>
suspend <component>
resume <component>
poweroff <component>
restart <component>
start-all
shutdown-all
poweroff-all

mrnctl --pretty status

# Le nom de chaque composant :
mrnctl -q '.nodes[].name' ls

# true si m1 peut être supprimée :
mrnctl -q '.can | index("del") != null' can m1

4. Attendre qu’une machine soit prête

Démarrer une machine, c’est démarrer un véritable noyau Linux, ce qui prend quelques secondes. Or mrnctl start m1 répond tout de suite, car sa réponse signifie que l’ordre a été accepté, et non que la machine a fini de démarrer. Un script qui enchaînerait sans attendre s’adresserait donc à une machine qui n’est pas encore là. Il y a deux façons d’attendre, selon ce dont on a besoin.

• Attendre que la machine tourne, c’est-à-dire que son processus existe :

  mrnctl wait m1 --state=on --timeout=120
  

  L’attente est brève (moins d’une seconde), mais le système de la machine n’est pas encore utilisable : sur une Debian, il lui faut encore environ cinq secondes.

• Attendre que la machine se dise prête. Marionnet ne peut pas savoir quand une machine est prête pour le TP, c’est-à-dire quand elle a fini ce qu’on attend d’elle (poser ses adresses, lancer ses services…) : seule sa configuration de démarrage le sait (cf. § 6). C’est donc à celle-ci de le signaler, par sa dernière ligne, en créant un fichier convenu (un fichier témoin) dans /mnt/hostfs, un répertoire que Marionnet monte dans chaque machine et qu’il surveille depuis l’hôte :

  echo ready > /mnt/hostfs/marionnet-guest-ready
  

  Du côté du pilote, il ne reste alors qu’à attendre ce fichier témoin :

  mrnctl wait m1 --ready --timeout=300
  

  Le nom du fichier doit être recopié exactement, puisque c’est lui que Marionnet guette. Il est en revanche inutile de l’effacer d’une séance à l’autre : Marionnet ne tient compte que du fichier écrit pendant le démarrage en cours. Enfin, une machine sans configuration de démarrage n’écrit jamais ce fichier, et --ready attendrait donc jusqu’à l’expiration du délai : il faut alors s’en tenir à --state=on.

R="ping KO"
ping -c 3 10.0.0.2 > /dev/null && R="ping ok"
echo "$R" > /mnt/hostfs/marionnet-guest-ready

mrnctl -q .line wait m1 --ready --timeout=300
# ping ok

marionnet --control-socket "$MARIONNET_CONTROL_SOCKET" &
pid=$!
# … la session …
mrnctl quit
wait "$pid"

pid=$(mrnctl -q .pid quit)
while kill -0 "$pid" 2>/dev/null; do sleep 0.05; done

5. Construire et enregistrer un TP

Le § 2 a montré l’essentiel. Voici les ordres qui servent le plus souvent, avec leur équivalent à la souris :

Deux précautions s’imposent, qui sont aussi celles de l’interface graphique.

• Marionnet ne perd jamais votre travail sans qu’on le lui dise. Si le projet en cours a été modifié, new et close attendent que vous précisiez --save (enregistrer d’abord) ou --no-save (abandonner les modifications), là où l’interface vous poserait la question.
• Un réseau en marche ne s’enregistre pas, de même que l’interface grise ses entrées d’enregistrement tant qu’une machine tourne. Arrêtez donc d’abord les machines, ou bien utilisez close --save, qui arrête tout, attend que tout soit arrêté, puis enregistre (comptez alors quelques dizaines de secondes).

mrnctl -q '.slugs[]' ifconfig m1
# mac-address
# mtu
# ipv4-address
# …

mrnctl ifconfig-set m1 eth0 ipv4-address 10.0.0.1/24
mrnctl defects-set  m1 eth0 inward loss 5 --no-restart
mrnctl defects-set  c1 rightward maximum-delay-ms 50

6. Faire travailler les machines

Les ordres de Marionnet agissent sur le réseau, vu de l’extérieur. Pour ce qui se passe à l’intérieur d’une machine, il existe deux moyens.

• La configuration de démarrage, la fonctionnalité que l’interface graphique propose sous ce nom, est un petit script bash que la machine exécute à la fin de son démarrage. Il peut configurer la machine, jouer sa part du TP (lancer un ping, par exemple), écrire des résultats, puis signaler que la machine est prête :

  mrnctl rc-set m1 --from=/tmp/scenario.sh --enable
  mrnctl start m1
  mrnctl wait  m1 --ready --timeout=300
  

  Ce script étant lu au démarrage, il ne prend effet qu’au prochain démarrage de la machine.

• L’ordre exec fait exécuter une commande à une machine déjà en marche, et rend sa sortie :

  mrnctl exec m1 uname -r
  mrnctl -q .output exec m1 -- ping -c 1 -W 2 10.0.0.2
  

  Le -- isolé sépare les options du pilote de celles de la commande : sans lui, une option comme --all serait prise par le pilote pour l’une des siennes.

Pour récupérer ce qu’une machine a produit, le plus simple est qu’elle l’écrive dans /mnt/hostfs. Ce répertoire de la machine virtuelle est en réalité un répertoire de l’hôte, que votre script lit directement ; mrnctl rc-get m1 en donne le chemin, dans le champ hostfs.

# Le script que m1 exécutera à la fin de son démarrage,
# écrit ici sur l'hôte :
cat > /tmp/scenario.sh <<'EOF'
ip addr add 10.0.0.1/24 dev eth0 2>/dev/null
ip link set eth0 up
ping -c 3 10.0.0.2 > /mnt/hostfs/ping.log 2>&1
echo "$?" > /mnt/hostfs/ping.status
# Dernière ligne : signaler que la machine est prête.
echo ready > /mnt/hostfs/marionnet-guest-ready
EOF

# Le confier à m1, la démarrer, attendre qu'elle soit prête :
mrnctl rc-set m1 --from=/tmp/scenario.sh --enable
mrnctl start m1
mrnctl wait  m1 --ready --timeout=300

# Lire, depuis l'hôte, ce que la machine a écrit :
hostfs=$(mrnctl -q '.hostfs' rc-get m1)
cat "$hostfs/ping.log"

mrnctl rc-set m1 'echo bonjour'

mrnctl -q '.available | join(" ")' rc-get r1
# rc_config_unix zebra rip ripng ospf bgp ospf6 isis

mrnctl rc-set r1 --from=/tmp/zebra.conf --field=zebra

# Ce démon-ci ne démarrera pas :
mrnctl rc-set r1 --field=ospf --unselect

# Ouvrir le terminal de zebra, à la CISCO-IOS :
mrnctl rc-set r1 --field=zebra --terminal

# CORRECT : la machine reçoit  sh -c 'exit 7'  (code 7).
mrnctl exec m1 "sh -c 'exit 7'"

# ERREUR : votre shell a retiré les guillemets,
# la machine reçoit  sh -c exit 7  (code 0).
mrnctl exec m1 -- sh -c 'exit 7'

7. Savoir ce qui s’est passé

Marionnet sait ce qu’il a construit, et les machines savent ce qui s’est passé en elles ; les uns comme les autres s’interrogent :

# Les composants et leur état, puis les adresses de m1 :
mrnctl ls
mrnctl ifconfig m1

# Ce qu'a fait la configuration de démarrage de m1 :
mrnctl log m1

# Ce qui a été tapé dans son terminal :
mrnctl log m1 commands

# Lui demander un rapport sur son état, puis le lire :
mrnctl report m1
mrnctl log m1 report

Le rapport mérite une explication. Les journaux sont des traces : ils disent quelles commandes ont été lancées, mais pas toujours l’état qui en résulte. Supposons par exemple que la configuration de démarrage d’une machine contienne la ligne suivante :

echo 1 > /proc/sys/net/ipv4/ip_forward

Le transfert de paquets est alors bien activé, mais le journal de la configuration de démarrage n’en garde que echo 1, car sa trace ne note pas les redirections. Le rapport, lui, est une photographie de la machine à un instant donné (ses adresses réelles, ses routes, ses voisins, son pare-feu) : c’est donc sur lui qu’il faut s’appuyer pour savoir si une machine est dans l’état voulu.

Enfin, l’onglet Historique se pilote lui aussi : mrnctl history m1 liste les états de disque d’une machine, et history-start redémarre la machine depuis l’un d’eux, comme l’entrée Démarrer dans cet état de l’interface, ce qui permet de rejouer un TP à partir d’un point connu.

8. Écrire les ordres dans un fichier

Plutôt qu’un script shell, un TP peut s’écrire comme une simple liste d’ordres, un par ligne, dans un fichier .mrn :

cat > tp.mrn <<'EOF'
new /tmp/tp.mar
add machine m1
add machine m2
add switch s1 --ports=4
connect c1 m1:eth0 s1:port1
connect c2 m2:eth0 s1:port2
save-as /tmp/tp.mar
EOF

mrnctl -f tp.mrn

Le fichier s’exécute ligne à ligne, et s’arrête au premier refus (--keep-going permet de continuer). Notons qu’un échec au milieu du fichier laisse le projet dans l’état où l’ont mis les lignes précédentes, puisque rien n’est annulé ; d’où l’intérêt de vérifier le fichier avant de l’envoyer, ce que fait mrn-check (installé, comme les deux outils qui suivent, avec Marionnet), sans rien envoyer à Marionnet :

mrn-check tp.mrn
# tp.mrn: 9 request(s), no error

Il signale les ordres inconnus, les ports qui ne peuvent pas exister (port0 sur un switch), les composants utilisés avant d’avoir été ajoutés, ou encore les ports déjà occupés.

Enfin, quand un TP a besoin de plus qu’une liste d’ordres (attendre une machine, lire un résultat, répéter une opération sur chaque machine), mrn2sh traduit le fichier en un script shell ordinaire, que vous complétez ensuite à la main :

mrn2sh tp.mrn > tp.sh

mrnctl help > grammar.json
mrn-check --grammar=grammar.json tp.mrn

./tp.sh /tmp/autre.mar

9. Vérifier un TP

Un fichier .mrn dit de quoi un réseau est fait ; un fichier .mrv dit ce qui doit en être vrai, à raison d’une affirmation par ligne, et mrn-verify le confronte à la session en cours :

cat > tp.mrv <<'EOF'
state m1 is on
cable c1 m1:eth0 s1:port1
journal m1 rc_config ok
report m1 says ~ net[.]ipv4[.]ip_forward *= *1
reaches m1 m2
EOF

mrn-verify tp.mrv
# PASS  state m1 is on
# PASS  cable c1 m1:eth0 s1:port1
# …

Chaque ligne reçoit l’un de trois verdicts : PASS si l’affirmation est vraie, FAIL si elle est fausse, et SKIP quand Marionnet n’offre aucun moyen de le savoir, par exemple pour un ping vers une machine éteinte, dont l’adresse ne peut pas être lue. Notons que reaches m1 m2 lance un ping depuis m1 vers l’adresse de m2, lue dans le rapport de m2 : un pare-feu qui bloque ICMP donne donc FAIL, comme le ferait un ping tapé à la main. Ce troisième verdict a son importance, car un vérificateur qui répondrait FAIL dans ce cas sanctionnerait un étudiant pour une limite de l’outil ; l’option --strict permet toutefois de compter un SKIP comme un échec. La liste des affirmations possibles (neuf formes) est donnée par mrn-verify --help, et la vérification ne modifie rien dans le projet. Enfin, un motif précédé de ~, comme dans la ligne report de l’exemple, est une expression régulière étendue (celle de grep -E) ; sans ~, le motif est un texte cherché tel quel.

state <component> is on|off|sleeping
field <component> <field> is <value>
cable <cable> <node>:<port> <node>:<port>
switch <switch> <table> has <key>=<value> [<key>=<value>]…
journal <component> <journal> contains|lacks <pattern>
journal <component> <journal> ok
documents <component> has <pattern>
report <component> says|lacks <pattern>
reaches <component> <component>|<address>

journal m1 rc_config contains ip_forward
report  m1 says     ~ net[.]ipv4[.]ip_forward *= *1

10. Quand ça ne marche pas

11. Pour aller plus loin

• mrnctl help donne tous les ordres, toujours à jour.
• mrnctl --help, mrn-check --help et mrn-verify --help donnent les options de chaque outil.
• examples/ contient des scripts complets, prêts à être exécutés.
• ../teacher-guide.FR.md présente le pilotage vu depuis une salle de TP (préparer un TP, mener la séance, corriger), avec un TP complet dans ../labs/session-7/.
• ../exam-mode.FR.md décrit le mode examen.
• ../marionnet-driving-skill.md est le guide à donner à une IA pour qu’elle pilote Marionnet, c’est-à-dire pour qu’elle construise, vérifie et note un TP par des commandes.