Cette page présente la seule façon dont un programme Bogolang modifie un équipement : le bloc change on,
avec ses sections apply, rollback et verify. Elle dit ce qui se passe à chaque étape, ce qui se passe
quand un test échoue, et comment essayer un changement sans rien envoyer.
Exemple : change_vlan.
Essayez d'abord, sans rien envoyer
Lancez d'abord chaque nouveau programme de changement ainsi :
bogo run --dry --replay saved change_vlan.bogo
--dryaffiche les lignes que chaque changement enverrait, et n'en envoie aucune. Aucune session n'est ouverte pour le changement et aucune ligneverifyn'est exécutée.--replay savedrépond à chaque lecture à partir des sorties enregistrées, si bien qu'aucun équipement n'est contacté, pas même pour les commandes en lecture seule avant le changement.
--dry seul ouvre quand même des sessions en lecture seule pour les lectures que le programme fait en dehors des
blocs change. --replay seul n'envoie rien non plus, mais il exécute toute la séquence sur les
sorties enregistrées : voir Un changement sous --replay.
Avec change_vlan, lancé comme ci-dessus :
DRY RUN: change on core-sw1. Nothing is sent.
apply:
vlan 30
name CAMERAS
interface GigabitEthernet1/0/2
switchport trunk allowed vlan add 30
rollback:
interface GigabitEthernet1/0/2
switchport trunk allowed vlan remove 30
no vlan 30
core-sw1: VLAN 30 would be added, nothing was sent
access-sw3: VLAN 30 is already there, nothing to do
Le bloc
edition 2027
class AddVlan:
"""Adds one VLAN to one switch and allows it on the uplink."""
@staticmethod
def main(args: list[str]) -> None:
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
vid: int = 30
trunk: Intf = Intf("Gi1/0/2")
change on sw:
apply:
vlan {vid}
name CAMERAS
interface {trunk}
switchport trunk allowed vlan add {vid}
rollback:
interface {trunk}
switchport trunk allowed vlan remove {vid}
no vlan {vid}
verify:
"CAMERAS" in show("vlan brief")
str(vid) in show(f"interfaces {trunk} trunk")
word: str = "would be added" if dry_run() else "added"
print(f"{sw.name}: VLAN {vid} {word}")
- La cible après
onest unDevice, ou une session déjà ouverte avecssh(...). applyetrollbackcontiennent du texte d'équipement : les lignes partent vers l'équipement telles qu'elles sont écrites, avec leur propre indentation conservée. Une ligne qui commence par#y est aussi du texte d'équipement.{expr}insère une valeur dans une ligne. Ce peut être du texte, un nombre entier ou un type d'adresse :IP,Net,IfAddr,MAC,IntfouVlanSet. Une quantité comme20Mbpsest refusée, de même qu'unSecret.{{et}}envoient une vraie accolade.- Une valeur de plusieurs lignes, placée seule sur sa ligne, est envoyée comme plusieurs lignes. Ainsi
apply:peut contenir seulement{t.fill(d)}, un modèle rempli (voir config-audit-templates.md). verifycontient des tests, un par ligne. Chacun doit être vrai.show(...)y lit l'équipement en cours de changement ; unOutputpeut être testé avecin. Une ligne#dansverifyest un commentaire.
Ce que la vérification refuse
bogo check et bogo run refusent ceci avant le démarrage du programme :
- un changement sans
rollback, ou avec unrollbackvide - un changement sans lignes
apply - des sections dans un autre ordre que
apply,rollback,verify, ou une section écrite deux fois - toute autre ligne au niveau des sections
- un changement à l'intérieur d'un bloc
retry: renvoyer un changement n'est pas une façon de le réparer - un
Secretdans le texte d'équipement, une{non fermée, une}seule, un{}vide
norb.bogo:8:9: error: this change has no rollback
change on sw:
^^^^^^^^^^^^^
A change is refused unless it says how to undo it.
Write it as:
change on d:
apply:
(device lines)
rollback:
(device lines)
verify:
(tests, one per line)
Un changement sans verify donne un avertissement et s'exécute quand même : sans test, un changement qui a mal
tourné n'est pas remarqué et ne fait pas l'objet d'un retour arrière.
Ce qui se passe, étape par étape
Rien n'est envoyé pendant la lecture du bloc. Le changement commence quand la section verify s'ouvre,
ou à la fin du bloc s'il n'y en a pas. Ensuite, dans cet ordre :
- Essai à blanc. Sous
--dry, sousbogo test, et dans un programme empaqueté lancé avec--dry: afficher les lignes, ne rien envoyer, s'arrêter ici. - Sauvegarde. Lire la configuration en cours et la garder dans un dossier
backupsà côté du programme, sous la formeDEVICE_YYYYMMDDTHHMMSSZ.cfg(heure UTC). Aucun fichier n'est écrit sous--replay. - Minuterie. Avec
revert_after, armer la minuterie propre à l'équipement (voir plus bas). - Application. Envoyer les lignes
apply. Une réponse de l'équipementInvalid input,Incomplete command,Ambiguous command,Unknown commandouUnrecognized commandarrête l'envoi à cette ligne. - Vérification. Exécuter chaque ligne
verify. - Confirmation. Tout est vrai : le changement est fait. Avec une minuterie,
configure confirml'arrête. - Retour arrière. Une ligne
verifyfausse, une ligneverifyqui lève une erreur, une ligne que l'équipement refuse, ou un arrêt venu de l'extérieur (Ctrl+C) : envoyer les lignesrollback, puis lever uneChangeError.
L'ordre sur Junos est différent ; voir Changements sur Junos.
Quand un changement échoue
Un changement qui échoue lève ChangeError :
| Champ | Signification |
|---|---|
str(e) |
Ce qui a mal tourné, et si le retour arrière a été envoyé |
e.device |
Le nom de l'équipement |
e.rolled_back |
Vrai quand les lignes de retour arrière ont été envoyées |
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
try:
change on sw:
apply:
vlan 30
name CAMERAS
rollback:
no vlan 30
verify:
"CAMERAS" in show("vlan brief")
except ChangeError as e:
print(e)
if not e.rolled_back:
print(f"check {e.device} by hand now")
Le message d'une ligne verify fausse, tiré de l'exécution sous --replay montrée plus bas :
The change on sw1 failed: the verify line `"CAMERAS" in show("vlan brief")` is false. The rollback lines were sent.
Quand le retour arrière lui-même ne peut pas être envoyé, le message dit THE ROLLBACK COULD NOT BE SENT,
rolled_back est faux, et il vous indique si la minuterie propre à l'équipement annulera le changement
ou si vous devez vérifier l'équipement à la main.
Quand une ligne parmi plusieurs est refusée, le journal d'exécution marque toutes les lignes apply comme échouées, avec
la réponse de l'équipement. Il ne montre pas quelles lignes sont passées avant celle qui a été refusée. Le retour arrière
est envoyé dans tous les cas. Un avertissement de l'équipement qui n'est pas un refus n'est pas remarqué : les
lignes verify sont le vrai test.
Un changement sous --replay
Avec --replay et sans --dry, toute la séquence s'exécute sur des sorties enregistrées et rien n'est
envoyé : les lignes vont seulement dans le journal d'exécution, et verify lit les sorties enregistrées. L'étape de
sauvegarde a besoin d'un show running-config enregistré pour chaque équipement. Cela permet d'essayer les lignes verify
sur des sorties que vous avez écrites à la main. Ici le show vlan brief enregistré n'a pas de CAMERAS, donc le
test est faux et le retour arrière est « envoyé » :
bogo run --replay saved --record chg.bogo
device command start_local start_utc seconds ok error
sw1 show running-config 2026-11-20T18:05:22+01:00 2026-11-20T17:05:22+00:00 0.00 True
sw1 [apply] vlan 30 2026-11-20T18:05:22+01:00 2026-11-20T17:05:22+00:00 0.00 True
sw1 [apply] name CAMERAS 2026-11-20T18:05:22+01:00 2026-11-20T17:05:22+00:00 0.00 True
sw1 show vlan brief 2026-11-20T18:05:22+01:00 2026-11-20T17:05:22+00:00 0.00 True
sw1 [rollback] no vlan 30 2026-11-20T18:05:22+01:00 2026-11-20T17:05:22+00:00 0.00 True
ChangeError: The change on sw1 failed: the verify line `"CAMERAS" in show("vlan brief")` is false. The rollback lines were sent.
rolled back: True
Chaque ligne envoyée est une ligne du journal d'exécution, marquée [apply], [rollback] ou [confirm].
Voir devices.md.
dry_run, confirm et --yes
dry_run() -> bool
confirm(question: str) -> bool
dry_run() est vrai sous bogo run --dry, sous bogo test, et dans un programme empaqueté
lancé avec --dry. Un programme l'interroge pour dire « would add » et non « added », comme dans le bloc
ci-dessus.
confirm(question) pose une question oui ou non au clavier. Sans clavier, la réponse est non.
bogo run --yes, et bogo test, répondent oui.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
if confirm(f"Shut the spare port Gi1/0/48 on {sw.name}?"):
change on sw:
apply:
interface Gi1/0/48
shutdown
rollback:
interface Gi1/0/48
no shutdown
verify:
"administratively down" in show("interfaces Gi1/0/48")
La minuterie de l'équipement : revert_after
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
change on sw revert_after 5min:
apply:
interface Gi1/0/48
description spare
rollback:
interface Gi1/0/48
no description
verify:
"spare" in show("interfaces Gi1/0/48 description")
Avec revert_after, l'équipement annule lui-même le changement si Bogolang ne peut pas terminer, par
exemple quand la session est perdue.
- Sur IOS et IOS-XE, le mode configuration est ouvert avec
configure terminal revert timer Netconfigure confirmest envoyé après un succès, et après un retour arrière qui a fonctionné. N est en minutes entières, arrondi au-dessus ; moins d'une minute est refusé. L'équipement doit avoir son archive de configuration en place, sinon il refuse la minuterie ; rien n'a été envoyé à ce moment-là. - Sur Junos, chaque changement a la minuterie derrière lui (voir plus bas).
- Les autres plateformes refusent
revert_after.
Ces deux commandes IOS n'ont jamais été acceptées par un vrai équipement. Vérifiez-les sur la version
exacte de votre équipement avant de faire confiance à revert_after sur celui-ci.
Plages horaires
Un changement peut être limité à ses heures avec only between :
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
only between time"22:00" and time"02:00" UTC:
change on sw:
apply:
ntp server 198.51.100.41
rollback:
no ntp server 198.51.100.41
verify:
"198.51.100.41" in show("running-config | include ntp")
En dehors de ses heures, le bloc ne s'exécute pas et le programme s'arrête avec une erreur :
BogoWindowError: this block may only run between 22:00 and 02:00 UTC. It is now 17:14 UTC.
Sous --dry, il est sauté avec la ligne
DRY RUN: outside the window 22:00 to 02:00 UTC. The block is skipped. Une plage peut passer
minuit. Le fuseau est un nom court comme UTC ou un nom complet comme
Europe/Paris.
Changements sur Junos
Junos n'applique pas une ligne au moment où elle est tapée : les lignes vont dans un brouillon, et commit applique le
brouillon d'un seul bloc. Le bloc change suit ce modèle :
- Essai à blanc : afficher les lignes, ne rien envoyer.
- Sauvegarde, avec
show configuration. - Un simple
configure, puisshow | compare. Si l'équipement contient déjà des changements qui n'ont pas été validés, c'est le travail de quelqu'un d'autre : le changement s'arrête ici et les laisse tels quels. Ensuiteconfigure exclusive. - Les lignes
apply, une à la fois. Puisshow | compare, dont la réponse est affichée après la ligneJunos NAME will change:. Puiscommit check. commit confirmed N comment "bogolang <UTC time>". N estrevert_afteren minutes entières, et 10 quand il n'y a pas derevert_after.- Les lignes
verify.show(...)est envoyé sous la formerun show .... - Tout est vrai :
commit, qui confirme. Une ligne fausse : les lignesrollback, puiscommit.
sw: Device = Device(name="edge-sw2", ip=192.0.2.21, platform="junos")
change on sw revert_after 5min:
apply:
set interfaces ge-0/0/5 description spare
rollback:
rollback 1
verify:
"spare" in show("interfaces ge-0/0/5 descriptions")
- Quelles lignes peuvent être envoyées. Une ligne
applycommence parset,delete,activate,deactivate,rename,insert,copyouannotate, est écrite avec son chemin complet, et ne contient pas de|. Une lignerollbackpeut aussi êtrerollback N;rollback 1revient à la configuration d'avant le commit. Toute autre ligne est refusée avant que quoi que ce soit soit envoyé, dans un essai à blanc aussi. - Une ligne refusée ne coûte rien. Quand l'équipement répond
syntax error,unknown command,missing argumentouerror:, ou que le brouillon échoue àcommit check, rien n'a été appliqué. Le brouillon est vidé (rollback 0) et les lignesrollbackne sont pas envoyées. - La minuterie ne doit pas gagner la course. Quand il reste moins de 30 secondes avant la minuterie de l'équipement, le changement n'est pas confirmé. L'erreur dit que l'équipement l'annule de lui-même.
- Une session perdue : la minuterie de l'équipement fait le retour arrière.
commit synchronizen'est pas envoyé : sur un équipement à deux moteurs de routage, le commit n'est pas copié sur le second, sauf si l'équipement est réglé pour le faire.- Le journal d'exécution marque chaque ligne :
[enter],[apply],[compare],[check],[commit],[verify],[confirm],[rollback],[leave].
Essayé sur un commutateur Junos virtuel (26.2R1.7) : un essai à blanc, un changement qui réussit avec
revert_after 2min, une ligne verify fausse, une ligne que le commutateur refuse, et un brouillon laissé par
une autre connexion. La garde de 30 secondes, une session perdue et Ctrl+C ont été essayés dans les tests seulement.
Plateformes
Un bloc change fonctionne sur ios, iosxe, asa, nxos et junos. Les autres plateformes sont refusées
avant que quoi que ce soit soit envoyé. Voir devices.md.
Non prouvé
Un seul vrai changement a été fait sur un commutateur IOS-XE : une description sur un port inutilisé, avec une ligne
verify fausse exprès, puis ajoutée et retirée. Les instantanés d'avant et d'après se sont comparés en No
difference.. Pas essayé sur du vrai matériel : un équipement qui refuse une ligne, une session perdue, un
Ctrl+C, la minuterie d'équipement IOS, ASA et NX-OS. Voir not-proven.md.
Les règles du bloc évitent les accidents. Elles ne sont pas un mur de sécurité : un programme peut encore atteindre
un équipement avec un paquet Python et le modifier en dehors d'un bloc change. La vraie limite est ce que
le compte de l'équipement a le droit de faire.