This page covers how a program reads network devices: the inventory, stored logins, read-only
SSH sessions and their tables, loops over many devices, SNMP, backups, snapshots, the run
record, and saved outputs for --replay. It ends with the table of what works on which
platform.
Examples: device_table, backup_diff,
snapshot_compare.
Device
class Device(*, name: str, ip: IP, platform: str = 'ios', role: str = '', site: str = '', extra: dict[str, str] | None = None)
A device is a name, an address and a platform word. Every field is given by name. Two devices with the same name are the same device.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe", role="core", site="north")
print(sw.name, sw.ip, sw.platform, sw.extra.get("trunk", ""))
inventory
inventory(path: str) -> list[Device]
Reads a device list from a .csv, an .xlsx (its first sheet), a .yaml or a .yml file.
nameandipare required.platform,roleandsiteare optional; with no platform the device isios.- Every other column goes to
d.extra, as text:d.extra["trunk"]. - Column names are read in small letters. Empty rows are skipped.
- A platform word that other tools write is understood:
cisco_iosisios,cisco_xeisiosxe,cisco_asaisasa,cisco_nxosisnxos,cisco_wlcisaireos,juniper_junosandjuniperarejunos. A device of another maker that the SSH package knows becomesnetmiko:NAME, for examplearista_eosbecomesnetmiko:arista_eos. - Two columns choose a stored login:
loginfor SSH andsnmpfor SNMP. With no such column, the profiledefaultis used.
name,ip,platform,role,site,login
core-sw1,192.0.2.11,iosxe,core,north,
edge-rt2,192.0.2.12,iosxe,router,north,
access-sw3,198.51.100.23,ios,access,south,branch
A YAML file is a list of devices (- name: core-sw1 then ip: 192.0.2.11 on the next line),
or a mapping whose devices key holds that list.
A mistake names the file, the row and the column: an empty name, a name used twice, an ip
that is not an address, a missing name or ip column, a file with no devices.
Logins
A login is never written in a program or in a file. It is kept in the protected store of the
operating system, under a profile name, by the command bogo login:
bogo login the profile "default"
bogo login branch the profile "branch"
bogo login --snmp default an SNMP login: version 2c with a community, or 3 with user, auth and priv
bogo logout branch remove it
bogo login asks for the user, the password and the enable secret (empty when there is none).
A device uses the profile named in its login column. When no login is stored and a person is
at the keyboard, the program asks once per profile and keeps the answer for the rest of the
run. With no keyboard it stops and says which bogo login to run.
In a program a password is a Secret: it prints as <secret>, cannot be put in device text
or a template, and only .reveal() gives the text.
Sessions
ssh(d: Device, via: Device | None = None) -> Session
ssh(d) opens a read-only session. Use it in a with block, so it is always closed.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
with ssh(sw) as s:
out: Output = s.show("version")
print(out.lines[0])
if "uptime" in out:
print("the answer holds an uptime")
On a Session |
Result |
|---|---|
s.show(command) |
Output. The word show is added when it is missing: s.show("version") sends show version |
s.run(command) |
Output. The command is sent as written |
On an Output |
Result |
|---|---|
.text |
The answer as one text. str(out) is the same |
.lines |
The answer as a list of lines |
.table() |
list[Row], the answer read as a table |
text in out |
True when the answer holds this text |
Sessions are read-only
A session refuses every command that could change the device, with a PermissionError that
says why:
- On every platform but Junos a command must start with
show,ping,traceroute,dirormore, written in full:sh runis refused. - On Junos a command must start with
show,ping,traceroute,file listorfile show. After a|onlymatch,except,count,find,last,displayandno-moreare accepted. Apingthat names nocountgetscount 5, because a Junos ping does not end by itself. - A pipe to
redirect,teeorappendis refused: it writes a file on the device. - A command with a line break is refused: it could hide a second command.
A change belongs in a change block, see changes.md.
These rules stop accidents. They are not a security wall: the real limit is what the device account may do.
Tables and rows
.table() reads the answer with the public TextFSM templates (ntc_templates) for the
platform of the device. Each row is a Row. row.version and row["version"] give the same
text. row.columns lists the column names.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
with ssh(sw) as s:
v: Row = s.show("version").table()[0]
print(v.hardware, v.version, v.uptime_days)
- A column name that the table does not have is an error when the program runs, and the message lists the columns that exist.
- A command with no known layout gives a
ValueError;.textand.linesstill hold the answer. - A
Rowcan be made by hand for a test:Row({"vlan_id": "10", "status": "active"}).
The jump host
ssh(d, via=jump) logs in to the jump host with its own login, then opens the session to the
device through it.
jump: Device = Device(name="jump1", ip=198.51.100.5, extra={"login": "jump"})
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
with ssh(sw, via=jump) as s:
print(s.show("clock").text)
The jump host must be an SSH server that allows forwarding: a Linux server does, a Cisco
device does not, and the error says so. An unknown host key is accepted, for the jump host as
for the device. With --replay it is not contacted. It was never tried on a real jump host.
The console port
serial(port_name, speed=9600, platform="ios", login="default") gives the same read-only
Session over a console port, such as COM3 or /dev/ttyUSB0. It works on ios and
iosxe: the SSH package has no console driver for the other platforms. A console that asks
for no login works. It was never tried on a real console.
Many devices: for ... parallel
devices: list[Device] = inventory("devices.csv")
for d in devices where d.role != "router" parallel 10:
with ssh(d) as s:
print(f"{d.name}: {s.show('clock').text.strip()}")
for f in last_failures():
print(f"{f.item} failed: {f.kind}: {f.error}")
where skips the items for which its test is false. parallel 10 runs the block for up to ten
items at the same time.
- What one run prints is held and shown as one piece, in the order of the list.
- A variable given a value inside the block belongs to that one run. A list from outside can be added to.
breakandreturnare refused by the check.continueskips the current item.- An error in one run stops that run only. After the loop,
last_failures()gives aFailurefor each item that failed, with.item,.kind(the kind of error) and.error(its text). - When the program never calls
last_failures(), the failures are printed at the end andbogo runends with a failure code. Here under--replay, with no saved output for one of two switches:
1 item(s) of a parallel loop failed:
sw2: RuntimeError: Replay mode has no saved output for 'show vlan brief'. The file needed is ...\saved\sw2\show_vlan_brief.txt.
Call last_failures() after the loop to handle them in the program.
SNMP
snmp_get(d: Device, oid: str, timeout: Duration = 2s) -> SnmpValue
snmp_walk(d: Device, oid: str, timeout: Duration = 2s) -> list[SnmpValue]
Read-only. An OID is written in numbers; a MIB name is refused with an example.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, extra={"snmp": "monitor"})
name: SnmpValue = snmp_get(sw, "1.3.6.1.2.1.1.5.0")
states: list[SnmpValue] = snmp_walk(sw, "1.3.6.1.2.1.2.2.1.8")
up: int = sum(1 for v in states if v.number == 1)
print(f"{name.text}: {up} of {len(states)} interfaces up")
- An
SnmpValuehas.oid,.kind,.textand.number. The kinds areinteger,counter,gauge,timeticks,text,bytes,oidandip..numberon a value that is not a number is an error. snmp_geton an OID the device does not have raisesLookupError.snmp_walkgives an empty list.- The login comes from
bogo login --snmp PROFILE, chosen by thesnmpcolumn. Version 3 passwords shorter than 8 characters are refused. A community or a password never appears in a message or in the run record.
Tried on a real device: version 3 with SHA and AES. Version 2c was not tried.
Backup and diff
backup(d: Device) -> Config
load_config(path: str, platform: str = 'ios') -> Config
diff(a: Config, b: Config) -> ConfigDiff
backup(d) reads the configuration with the command of the platform (show running-config,
show run-config commands on AireOS, show configuration on Junos) and gives a Config.
cfg.save(path) writes it to a file, and load_config reads a saved file back with no device.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
fresh: Config = backup(sw)
old: Config = load_config("backups/core-sw1.cfg", platform="iosxe")
changes: ConfigDiff = diff(old, fresh)
if changes:
print(changes)
fresh.save("backups/core-sw1.cfg")
diff compares section by section. Each line is shown with its section in front, - for a
removed line and + for an added one. A section that only moved is not reported, and neither
are the ! lines and the byte count IOS writes on top. On two Junos configurations it compares
their set lines. With no change, a ConfigDiff is false and prints No difference..
From backup_diff, run with bogo run --replay saved
backup_diff.bogo:
core-sw1: 4 lines removed, 7 added, in 5 sections
- interface GigabitEthernet1/0/2 / switchport trunk allowed vlan 10,20
- interface GigabitEthernet1/0/3 / description spare
- interface GigabitEthernet1/0/3 / shutdown
- ip http server
+ vlan 30
+ vlan 30 / name CAMERAS
+ interface GigabitEthernet1/0/2 / switchport trunk allowed vlan 10,20,30
+ interface GigabitEthernet1/0/3 / description camera recorder
+ interface GigabitEthernet1/0/3 / switchport access vlan 30
+ interface GigabitEthernet1/0/3 / switchport mode access
+ ntp server 198.51.100.11
edge-rt2: no change
A backup holds the secrets of the device. Keep the files as carefully as the devices. What a
Config can do beyond this is on config-audit-templates.md.
Snapshot and compare
snapshot(d: Device) -> Snapshot
compare(a: Snapshot, b: Snapshot) -> SnapshotDiff
load_snapshot(path: str) -> Snapshot
snapshot(d) opens one session and reads the routes, the neighbours, the interfaces and the
configuration. Take one before a piece of work and one after, then compare them.
sw: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe")
before: Snapshot = snapshot(sw)
before.save("core-sw1-before.json")
old: Snapshot = load_snapshot("core-sw1-before.json")
moved: SnapshotDiff = compare(old, snapshot(sw))
print(moved)
print(len(moved.routes_added), len(moved.interfaces_changed))
- The work between the two often outlasts one run, so
s.save(path)writes a snapshot to a JSON file andload_snapshot(path)reads it back. The file holds the configuration. - A
SnapshotDiffhasroutes_added,routes_removed,neighbors_added,neighbors_removed,interfaces_added,interfaces_removed,interfaces_changed(pairs of before and after) andconfig(aConfigDiff). It is false when nothing moved. - What changes by itself is not compared: route age, hold times, metrics, uptimes. A route is the same route when its VRF, protocol, network, prefix length and next hop are the same.
- A thing the platform does not have is an empty list: no routes on AireOS, no neighbours on an ASA. Neighbours come from CDP, and from LLDP on Junos. The routes are those of the global table.
- Two snapshots of two different devices are refused.
The output of snapshot_compare under --replay lists each
route, neighbour, interface and configuration line that moved, by section, and No difference.
for a device where nothing moved.
The run record
Every command sent to a device is one line of the run record: SSH commands, SNMP calls, the lines of a change block, and the reach commands of reach.md. Each line holds the device, the command, the start time in local time and in UTC, how long it took, whether it worked, and the error. Secrets never enter it.
bogo run --record device_table.bogo print it on standard error at the end
bogo run --record-file run.csv device_table.bogo write it to a CSV file with a header
From device_table under --replay saved --record:
device command start_local start_utc seconds ok error
core-sw1 show version 2026-11-20T18:04:33+01:00 2026-11-20T17:04:33+00:00 0.00 True
edge-rt2 show version 2026-11-20T18:04:33+01:00 2026-11-20T17:04:33+00:00 0.00 True
access-sw3 show version 2026-11-20T18:04:33+01:00 2026-11-20T17:04:33+00:00 0.00 True
Saved outputs: --replay and --save-replay
bogo run --save-replay FOLDER keeps each answer of a device in a file.
bogo run --replay FOLDER reads those files back and connects to nothing: no SSH session, no
SNMP packet, no jump host. bogo test does the same with the folder replay beside the file
(or tests/replay in a project), or saved when there is no replay.
| What | File |
|---|---|
| A session command | FOLDER/DEVICE/COMMAND.txt, the command in small letters with each run of other signs written _: show running-config is show_running_config.txt |
| SNMP values | FOLDER/DEVICE/snmp.txt, one value per line: OID, kind and text, separated by tabs |
| Reach commands | FOLDER/reach/..., see reach.md |
The files are plain text, so a test can use an output written by hand. A missing file stops the command and names the file needed:
RuntimeError: Replay mode has no saved output for 'show running-config'. The file needed is ...\saved\core-sw1\show_running_config.txt.
Junos
The platform word is junos; an inventory may write juniper_junos or juniper. A line
written netmiko:juniper_junos keeps sessions only.
backupsendsshow configurationand keeps the form with braces.snapshotandroutesread the XML answers of Junos (| display xml), not text columns. Neighbours come from LLDP: Junos has no CDP. A route protocol is the word Junos writes, such asStatic,DirectorOSPF.- The configuration object works on paths (config-audit-templates.md),
and the
changeblock on the commit model of Junos (changes.md).
The readers were built against the answers of a virtual Junos switch of one release
(26.2R1.7), and the change block was tried on such a switch. No physical Junos device was
used. optics was not tried: it needs a device with a transceiver.
What works on which platform
The one table is bogolang/platforms.py. A function used on a platform that does not have it
is refused with one sentence that lists the platforms that do.
ios |
iosxe |
asa |
nxos |
aireos |
junos |
netmiko:NAME |
|
|---|---|---|---|---|---|---|---|
ssh, show, run, saved outputs |
yes | yes | yes | yes | yes | yes | yes |
serial |
yes | yes | |||||
backup |
yes | yes | yes | yes | yes | yes | |
snapshot |
yes | yes | yes, no neighbours | yes | yes, no routes | yes | |
routes |
yes | yes | yes, no vrf |
yes | yes | ||
| Neighbours by CDP | yes | yes | yes | yes | |||
| Neighbours by LLDP | yes | yes | yes | yes | |||
optics |
yes | yes | yes | ||||
Configuration object, audit |
yes | yes | yes | yes | yes | ||
acl test |
yes | yes | yes | ||||
change block |
yes | yes | yes | yes | yes | ||
Device timer (revert_after) |
yes | yes | yes |
netmiko:NAME is a device of another maker, named as the SSH package (netmiko) names it, such
as netmiko:arista_eos. It gets sessions, show, run and saved outputs, and nothing else.
Neighbours and optics are on logs-topology.md and
telecom-optics.md.
Not proven
Tried on real devices: one IOS-XE switch for show version, SNMPv3, snapshots, and the
route, log and neighbour readings; a virtual Junos switch for Junos. Never tried on real
equipment: the jump host, the console port, NX-OS, AireOS and ASA devices, and optics. The
outputs of NX-OS and AireOS in the tests were written by hand. See
not-proven.md.