Skip to content

Version 0.1.0 is a first version, for trial. See what is not proven →

bogolang
FR

← Documentation

Changes: the change block

The change block: apply, rollback, verify, --dry.

All documentation pages

This page covers the one way a Bogolang program changes a device: the change on block, with its apply, rollback and verify sections. It says what happens at each step, what happens when a test fails, and how to try a change with nothing sent.

Example: change_vlan.

Try it first, with nothing sent

Run every new change program like this first:

bogo run --dry --replay saved change_vlan.bogo
  • --dry prints the lines each change would send, and sends none of them. No session is opened for the change and no verify line is run.
  • --replay saved answers every read from saved outputs, so no device is contacted at all, not even for the read-only commands before the change.

--dry alone still opens read-only sessions for the reads the program makes outside the change blocks. --replay alone sends nothing either, but it runs the whole sequence on the saved outputs: see A change under --replay.

From change_vlan, run as above:

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

The block

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}")
  • The target after on is a Device, or a session already open with ssh(...).
  • apply and rollback hold device text: the lines go to the device as written, with their own indentation kept. A line that starts with # is device text there too.
  • {expr} puts a value into a line. It may be text, a whole number, or an address type: IP, Net, IfAddr, MAC, Intf or VlanSet. A quantity such as 20Mbps is refused, and so is a Secret. {{ and }} send a real brace.
  • A value of several lines on a line of its own is sent as several lines. So apply: can hold just {t.fill(d)}, a filled template (see config-audit-templates.md).
  • verify holds tests, one per line. Each must be true. show(...) there reads the device being changed; an Output can be tested with in. A # line in verify is a comment.

What the check refuses

bogo check and bogo run refuse these before the program starts:

  • a change with no rollback, or an empty one
  • a change with no apply lines
  • sections in another order than apply, rollback, verify, or one written twice
  • any other line at the level of the sections
  • a change inside a retry block: sending a change again is not a way to mend it
  • a Secret in device text, a { that is not closed, a } alone, an empty {}
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)

A change with no verify gives a warning and still runs: without a test, a change that went wrong is not noticed and not rolled back.

What happens, step by step

Nothing is sent while the block is read. The change starts when the verify section opens, or at the end of the block when there is none. Then, in this order:

  1. Dry run. Under --dry, under bogo test, and in a packed program started with --dry: print the lines, send nothing, stop here.
  2. Backup. Read the running configuration and keep it in a folder backups beside the program, as DEVICE_YYYYMMDDTHHMMSSZ.cfg (UTC time). No file is written under --replay.
  3. Timer. With revert_after, arm the device's own timer (below).
  4. Apply. Send the apply lines. A device answer of Invalid input, Incomplete command, Ambiguous command, Unknown command or Unrecognized command stops the sending at that line.
  5. Verify. Run each verify line.
  6. Confirm. All true: the change is done. With a timer, configure confirm stops it.
  7. Roll back. A false verify line, a verify line that raises an error, a line the device refuses, or a stop from outside (Ctrl+C): send the rollback lines, then raise a ChangeError.

The order on Junos is different; see Changes on Junos.

When a change fails

A failed change raises ChangeError:

Field Meaning
str(e) What went wrong, and whether the rollback was sent
e.device The name of the device
e.rolled_back True when the rollback lines were sent
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")

The message of a false verify line, from the run under --replay shown further down:

The change on sw1 failed: the verify line `"CAMERAS" in show("vlan brief")` is false. The rollback lines were sent.

When the rollback itself cannot be sent, the message says THE ROLLBACK COULD NOT BE SENT, rolled_back is false, and it tells you whether the device's own timer will take the change back or whether you must check the device by hand.

When one line of several is refused, the run record marks all the apply lines as failed, with the device's answer. It does not show which lines went in before the refused one. The rollback is sent in every case. A warning from the device that is not a refusal is not noticed: the verify lines are the real test.

A change under --replay

With --replay and without --dry, the whole sequence runs on saved outputs and nothing is sent: the lines only go to the run record, and verify reads the saved outputs. The backup step needs a saved show running-config for each device. This tries the verify lines against outputs you wrote by hand. Here the saved show vlan brief has no CAMERAS, so the test is false and the rollback is "sent":

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

Every line sent is a line of the run record, marked [apply], [rollback] or [confirm]. See devices.md.

dry_run, confirm and --yes

dry_run() -> bool
confirm(question: str) -> bool

dry_run() is true under bogo run --dry, under bogo test, and in a packed program started with --dry. A program asks it to say "would add" and not "added", as in the block above.

confirm(question) asks yes or no at the keyboard. With no keyboard the answer is no. bogo run --yes, and bogo test, answer yes.

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")

The device timer: 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")

With revert_after, the device itself takes the change back if Bogolang cannot finish, for example when the session is lost.

  • On IOS and IOS-XE, configuration mode is opened with configure terminal revert timer N and configure confirm is sent after a success, and after a rollback that worked. N is in whole minutes, rounded up; less than one minute is refused. The device needs its configuration archive set up, or it refuses the timer; nothing has been sent at that point.
  • On Junos every change has the timer behind it (below).
  • Other platforms refuse revert_after.

These two IOS commands have never been accepted by a real device. Check them on the exact release of your device before you trust revert_after there.

Time windows

A change can be kept to its hours with 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")

Outside its hours the block does not run and the program stops with an error:

BogoWindowError: this block may only run between 22:00 and 02:00 UTC. It is now 17:14 UTC.

Under --dry it is skipped with the line DRY RUN: outside the window 22:00 to 02:00 UTC. The block is skipped. A window may cross midnight. The zone is a short name such as UTC or a full name such as Europe/Paris.

Changes on Junos

Junos does not apply a line when it is typed: lines go into a draft, and commit applies the draft as one piece. The block uses that model:

  1. Dry run: print the lines, send nothing.
  2. Backup, with show configuration.
  3. A plain configure, then show | compare. If the device already holds changes that were not committed, they are somebody else's work: the change stops here and leaves them as they are. Then configure exclusive.
  4. The apply lines, one at a time. Then show | compare, whose answer is printed after the line Junos NAME will change:. Then commit check.
  5. commit confirmed N comment "bogolang <UTC time>". N is revert_after in whole minutes, and 10 when there is no revert_after.
  6. The verify lines. show(...) is sent as run show ....
  7. All true: commit, which confirms. One false: the rollback lines, then 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")
  • Which lines may be sent. An apply line starts with set, delete, activate, deactivate, rename, insert, copy or annotate, is written with its full path, and holds no |. A rollback line may also be rollback N; rollback 1 returns to the configuration before the commit. Any other line is refused before anything is sent, in a dry run too.
  • A refused line costs nothing. When the device answers syntax error, unknown command, missing argument or error:, or the draft fails commit check, nothing was applied. The draft is emptied (rollback 0) and the rollback lines are not sent.
  • The timer must not win the race. When less than 30 seconds are left before the device's timer, the change is not confirmed. The error says that the device takes it back by itself.
  • A lost session: the device's timer does the rollback.
  • commit synchronize is not sent: on a device with two routing engines, the commit is not copied to the second one unless the device is set to do so.
  • The run record marks each line: [enter], [apply], [compare], [check], [commit], [verify], [confirm], [rollback], [leave].

Tried on a virtual Junos switch (26.2R1.7): a dry run, a change that succeeds with revert_after 2min, a false verify line, a line the switch refuses, and a draft left by another login. The 30 second guard, a lost session and Ctrl+C were tried in the tests only.

Platforms

A change block works on ios, iosxe, asa, nxos and junos. Other platforms are refused before anything is sent. See devices.md.

Not proven

One real change was made on an IOS-XE switch: a description on an unused port, with a false verify line on purpose, then added and removed. Snapshots before and after compared as No difference.. Not tried on real equipment: a device that refuses a line, a lost session, a Ctrl+C, the IOS device timer, ASA and NX-OS. See not-proven.md.

The rules of the block stop accidents. They are not a security wall: a program can still reach a device with a Python package and change it outside a change block. The real limit is what the device account may do.