Aller au contenu

La version 0.1.0 est une première version, à l'essai. Voir ce qui n'est pas prouvé →

bogolang
EN

← Documentation

Changements : le bloc change

Le bloc change : apply, rollback, verify, --dry.

Toutes les pages de documentation

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
  • --dry affiche les lignes que chaque changement enverrait, et n'en envoie aucune. Aucune session n'est ouverte pour le changement et aucune ligne verify n'est exécutée.
  • --replay saved ré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

Bogolang
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 on est un Device, ou une session déjà ouverte avec ssh(...).
  • apply et rollback contiennent 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, Intf ou VlanSet. Une quantité comme 20Mbps est refusée, de même qu'un Secret. {{ 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).
  • verify contient des tests, un par ligne. Chacun doit être vrai. show(...) y lit l'équipement en cours de changement ; un Output peut être testé avec in. Une ligne # dans verify est 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 un rollback vide
  • 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 Secret dans 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 :

  1. Essai à blanc. Sous --dry, sous bogo test, et dans un programme empaqueté lancé avec --dry : afficher les lignes, ne rien envoyer, s'arrêter ici.
  2. Sauvegarde. Lire la configuration en cours et la garder dans un dossier backups à côté du programme, sous la forme DEVICE_YYYYMMDDTHHMMSSZ.cfg (heure UTC). Aucun fichier n'est écrit sous --replay.
  3. Minuterie. Avec revert_after, armer la minuterie propre à l'équipement (voir plus bas).
  4. Application. Envoyer les lignes apply. Une réponse de l'équipement Invalid input, Incomplete command, Ambiguous command, Unknown command ou Unrecognized command arrête l'envoi à cette ligne.
  5. Vérification. Exécuter chaque ligne verify.
  6. Confirmation. Tout est vrai : le changement est fait. Avec une minuterie, configure confirm l'arrête.
  7. Retour arrière. Une ligne verify fausse, une ligne verify qui lève une erreur, une ligne que l'équipement refuse, ou un arrêt venu de l'extérieur (Ctrl+C) : envoyer les lignes rollback, puis lever une ChangeError.

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
Bogolang
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.

Bogolang
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

Bogolang
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 N et configure confirm est 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 :

Bogolang
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 :

  1. Essai à blanc : afficher les lignes, ne rien envoyer.
  2. Sauvegarde, avec show configuration.
  3. Un simple configure, puis show | 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. Ensuite configure exclusive.
  4. Les lignes apply, une à la fois. Puis show | compare, dont la réponse est affichée après la ligne Junos NAME will change:. Puis commit check.
  5. commit confirmed N comment "bogolang <UTC time>". N est revert_after en minutes entières, et 10 quand il n'y a pas de revert_after.
  6. Les lignes verify. show(...) est envoyé sous la forme run show ....
  7. Tout est vrai : commit, qui confirme. Une ligne fausse : les lignes rollback, puis commit.
Bogolang
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 apply commence par set, delete, activate, deactivate, rename, insert, copy ou annotate, est écrite avec son chemin complet, et ne contient pas de |. Une ligne rollback peut aussi être rollback N ; rollback 1 revient à 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 argument ou error:, ou que le brouillon échoue à commit check, rien n'a été appliqué. Le brouillon est vidé (rollback 0) et les lignes rollback ne 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 synchronize n'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.