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
--dryprints the lines each change would send, and sends none of them. No session is opened for the change and noverifyline is run.--replay savedanswers 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
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
onis aDevice, or a session already open withssh(...). applyandrollbackhold 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,IntforVlanSet. A quantity such as20Mbpsis refused, and so is aSecret.{{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). verifyholds tests, one per line. Each must be true.show(...)there reads the device being changed; anOutputcan be tested within. A#line inverifyis 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
applylines - 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
retryblock: sending a change again is not a way to mend it - a
Secretin 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:
- Dry run. Under
--dry, underbogo test, and in a packed program started with--dry: print the lines, send nothing, stop here. - Backup. Read the running configuration and keep it in a folder
backupsbeside the program, asDEVICE_YYYYMMDDTHHMMSSZ.cfg(UTC time). No file is written under--replay. - Timer. With
revert_after, arm the device's own timer (below). - Apply. Send the
applylines. A device answer ofInvalid input,Incomplete command,Ambiguous command,Unknown commandorUnrecognized commandstops the sending at that line. - Verify. Run each
verifyline. - Confirm. All true: the change is done. With a timer,
configure confirmstops it. - Roll back. A false
verifyline, averifyline that raises an error, a line the device refuses, or a stop from outside (Ctrl+C): send therollbacklines, then raise aChangeError.
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 |
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.
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
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 Nandconfigure confirmis 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:
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:
- Dry run: print the lines, send nothing.
- Backup, with
show configuration. - A plain
configure, thenshow | 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. Thenconfigure exclusive. - The
applylines, one at a time. Thenshow | compare, whose answer is printed after the lineJunos NAME will change:. Thencommit check. commit confirmed N comment "bogolang <UTC time>". N isrevert_afterin whole minutes, and 10 when there is norevert_after.- The
verifylines.show(...)is sent asrun show .... - All true:
commit, which confirms. One false: therollbacklines, thencommit.
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
applyline starts withset,delete,activate,deactivate,rename,insert,copyorannotate, is written with its full path, and holds no|. Arollbackline may also berollback N;rollback 1returns 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 argumentorerror:, or the draft failscommit check, nothing was applied. The draft is emptied (rollback 0) and therollbacklines 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 synchronizeis 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.