Skip to content

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

bogolang
FR

← Documentation

Devices and sessions

Inventories, read-only sessions, logins, SNMP, backups and snapshots.

All documentation pages

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.

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

  • name and ip are required. platform, role and site are optional; with no platform the device is ios.
  • 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_ios is ios, cisco_xe is iosxe, cisco_asa is asa, cisco_nxos is nxos, cisco_wlc is aireos, juniper_junos and juniper are junos. A device of another maker that the SSH package knows becomes netmiko:NAME, for example arista_eos becomes netmiko:arista_eos.
  • Two columns choose a stored login: login for SSH and snmp for SNMP. With no such column, the profile default is 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.

Bogolang
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, dir or more, written in full: sh run is refused.
  • On Junos a command must start with show, ping, traceroute, file list or file show. After a | only match, except, count, find, last, display and no-more are accepted. A ping that names no count gets count 5, because a Junos ping does not end by itself.
  • A pipe to redirect, tee or append is 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.

Bogolang
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; .text and .lines still hold the answer.
  • A Row can 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.

Bogolang
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

Bogolang
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.
  • break and return are refused by the check. continue skips the current item.
  • An error in one run stops that run only. After the loop, last_failures() gives a Failure for 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 and bogo run ends 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.

Bogolang
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 SnmpValue has .oid, .kind, .text and .number. The kinds are integer, counter, gauge, timeticks, text, bytes, oid and ip. .number on a value that is not a number is an error.
  • snmp_get on an OID the device does not have raises LookupError. snmp_walk gives an empty list.
  • The login comes from bogo login --snmp PROFILE, chosen by the snmp column. 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.

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

Bogolang
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 and load_snapshot(path) reads it back. The file holds the configuration.
  • A SnapshotDiff has routes_added, routes_removed, neighbors_added, neighbors_removed, interfaces_added, interfaces_removed, interfaces_changed (pairs of before and after) and config (a ConfigDiff). 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.

  • backup sends show configuration and keeps the form with braces.
  • snapshot and routes read 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 as Static, Direct or OSPF.
  • The configuration object works on paths (config-audit-templates.md), and the change block 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.