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

Équipements et sessions

Inventaires, sessions en lecture seule, identifiants, SNMP, sauvegardes et instantanés.

Toutes les pages de documentation

Cette page explique comment un programme lit des équipements réseau : l'inventaire, les identifiants enregistrés, les sessions SSH en lecture seule et leurs tableaux, les boucles sur de nombreux équipements, SNMP, les sauvegardes, les instantanés, le journal d'exécution, et les sorties enregistrées pour --replay. Elle se termine par le tableau de ce qui fonctionne sur quelle plateforme.

Exemples : 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)

Un équipement est un nom, une adresse et un mot de plateforme. Chaque champ est donné par son nom. Deux équipements de même nom sont le même équipement.

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]

Lit une liste d'équipements depuis un fichier .csv, .xlsx (sa première feuille), .yaml ou .yml.

  • name et ip sont obligatoires. platform, role et site sont facultatifs ; sans plateforme, l'équipement est ios.
  • Chaque autre colonne va dans d.extra, sous forme de texte : d.extra["trunk"].
  • Les noms de colonnes sont lus en minuscules. Les lignes vides sont ignorées.
  • Un mot de plateforme écrit par d'autres outils est compris : cisco_ios est ios, cisco_xe est iosxe, cisco_asa est asa, cisco_nxos est nxos, cisco_wlc est aireos, juniper_junos et juniper sont junos. Un équipement d'un autre fabricant que le paquet SSH connaît devient netmiko:NAME, par exemple arista_eos devient netmiko:arista_eos.
  • Deux colonnes choisissent des identifiants enregistrés : login pour SSH et snmp pour SNMP. Sans une telle colonne, le profil default est utilisé.
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

Un fichier YAML est une liste d'équipements (- name: core-sw1 puis ip: 192.0.2.11 à la ligne suivante), ou un dictionnaire dont la clé devices contient cette liste.

Une erreur nomme le fichier, la ligne et la colonne : un nom vide, un nom utilisé deux fois, une ip qui n'est pas une adresse, une colonne name ou ip manquante, un fichier sans équipements.

Identifiants

Des identifiants ne sont jamais écrits dans un programme ni dans un fichier. Ils sont conservés dans le magasin protégé du système d'exploitation, sous un nom de profil, par la commande 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 demande l'utilisateur, le mot de passe et l'enable secret (vide quand il n'y en a pas). Un équipement utilise le profil nommé dans sa colonne login. Quand aucun identifiant n'est enregistré et qu'une personne est au clavier, le programme demande une fois par profil et garde la réponse pour le reste de l'exécution. Sans clavier, il s'arrête et indique quel bogo login exécuter.

Dans un programme, un mot de passe est un Secret : il s'affiche <secret>, ne peut pas être placé dans un texte d'équipement ni dans un modèle, et seul .reveal() donne le texte.

Sessions

ssh(d: Device, via: Device | None = None) -> Session

ssh(d) ouvre une session en lecture seule. Utilisez-la dans un bloc with, pour qu'elle soit toujours fermée.

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")
Sur une Session Résultat
s.show(command) Output. Le mot show est ajouté quand il manque : s.show("version") envoie show version
s.run(command) Output. La commande est envoyée telle qu'elle est écrite
Sur un Output Résultat
.text La réponse sous forme d'un seul texte. str(out) est équivalent
.lines La réponse sous forme d'une liste de lignes
.table() list[Row], la réponse lue comme un tableau
text in out Vrai quand la réponse contient ce texte

Les sessions sont en lecture seule

Une session refuse toute commande qui pourrait modifier l'équipement, avec une PermissionError qui dit pourquoi :

  • Sur toutes les plateformes sauf Junos, une commande doit commencer par show, ping, traceroute, dir ou more, écrit en entier : sh run est refusé.
  • Sur Junos, une commande doit commencer par show, ping, traceroute, file list ou file show. Après un |, seuls match, except, count, find, last, display et no-more sont acceptés. Un ping qui ne précise pas de count reçoit count 5, car un ping Junos ne s'arrête pas de lui-même.
  • Une redirection vers redirect, tee ou append est refusée : elle écrit un fichier sur l'équipement.
  • Une commande avec un saut de ligne est refusée : elle pourrait cacher une seconde commande.

Un changement a sa place dans un bloc change, voir changes.md.

Ces règles évitent les accidents. Elles ne sont pas une barrière de sécurité : la vraie limite est ce que le compte de l'équipement a le droit de faire.

Tableaux et lignes

.table() lit la réponse avec les modèles TextFSM publics (ntc_templates) de la plateforme de l'équipement. Chaque ligne est une Row. row.version et row["version"] donnent le même texte. row.columns liste les noms de colonnes.

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)
  • Un nom de colonne que le tableau n'a pas est une erreur à l'exécution du programme, et le message liste les colonnes qui existent.
  • Une commande sans mise en forme connue donne une ValueError ; .text et .lines contiennent toujours la réponse.
  • Une Row peut être créée à la main pour un test : Row({"vlan_id": "10", "status": "active"}).

L'hôte de rebond

ssh(d, via=jump) se connecte à l'hôte de rebond avec ses propres identifiants, puis ouvre la session vers l'équipement à travers lui.

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)

L'hôte de rebond doit être un serveur SSH qui autorise le transfert : un serveur Linux le fait, un équipement Cisco non, et l'erreur le dit. Une clé d'hôte inconnue est acceptée, pour l'hôte de rebond comme pour l'équipement. Avec --replay, il n'est pas contacté. Cela n'a jamais été essayé sur un vrai hôte de rebond.

Le port console

serial(port_name, speed=9600, platform="ios", login="default") donne la même Session en lecture seule sur un port console, comme COM3 ou /dev/ttyUSB0. Cela fonctionne sur ios et iosxe : le paquet SSH n'a pas de pilote console pour les autres plateformes. Une console qui ne demande aucun identifiant fonctionne. Cela n'a jamais été essayé sur une vraie console.

Plusieurs équipements : 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 saute les éléments pour lesquels son test est faux. parallel 10 exécute le bloc pour dix éléments au plus en même temps.

  • Ce qu'une exécution affiche est retenu et montré d'un seul tenant, dans l'ordre de la liste.
  • Une variable qui reçoit une valeur à l'intérieur du bloc appartient à cette seule exécution. Une liste venant de l'extérieur peut recevoir des ajouts.
  • break et return sont refusés par la vérification. continue saute l'élément en cours.
  • Une erreur dans une exécution n'arrête que cette exécution. Après la boucle, last_failures() donne un Failure pour chaque élément qui a échoué, avec .item, .kind (la sorte d'erreur) et .error (son texte).
  • Quand le programme n'appelle jamais last_failures(), les échecs sont affichés à la fin et bogo run se termine avec un code d'échec. Ici sous --replay, sans sortie enregistrée pour l'un des deux commutateurs :
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]

En lecture seule. Un OID s'écrit en chiffres ; un nom de MIB est refusé, avec un exemple.

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")
  • Une SnmpValue a .oid, .kind, .text et .number. Les sortes sont integer, counter, gauge, timeticks, text, bytes, oid et ip. .number sur une valeur qui n'est pas un nombre est une erreur.
  • snmp_get sur un OID que l'équipement n'a pas lève LookupError. snmp_walk donne une liste vide.
  • Les identifiants viennent de bogo login --snmp PROFILE, choisis par la colonne snmp. Les mots de passe de version 3 de moins de 8 caractères sont refusés. Une communauté ou un mot de passe n'apparaît jamais dans un message ni dans le journal d'exécution.

Essayé sur un vrai équipement : version 3 avec SHA et AES. La version 2c n'a pas été essayée.

Sauvegarde et diff

backup(d: Device) -> Config
load_config(path: str, platform: str = 'ios') -> Config
diff(a: Config, b: Config) -> ConfigDiff

backup(d) lit la configuration avec la commande de la plateforme (show running-config, show run-config commands sur AireOS, show configuration sur Junos) et donne une Config. cfg.save(path) l'écrit dans un fichier, et load_config relit un fichier enregistré sans équipement.

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 compare section par section. Chaque ligne est affichée précédée de sa section, - pour une ligne supprimée et + pour une ligne ajoutée. Une section qui a seulement été déplacée n'est pas signalée, pas plus que les lignes ! et le nombre d'octets qu'IOS écrit en tête. Sur deux configurations Junos, il compare leurs lignes set. Sans changement, un ConfigDiff est faux et affiche No difference..

Tiré de backup_diff, exécuté avec 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

Une sauvegarde contient les secrets de l'équipement. Gardez les fichiers avec autant de soin que les équipements. Ce qu'une Config peut faire de plus se trouve sur config-audit-templates.md.

Instantané et comparaison

snapshot(d: Device) -> Snapshot
compare(a: Snapshot, b: Snapshot) -> SnapshotDiff
load_snapshot(path: str) -> Snapshot

snapshot(d) ouvre une session et lit les routes, les voisins, les interfaces et la configuration. Prenez-en un avant un travail et un après, puis comparez-les.

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))
  • Le travail entre les deux dure souvent plus longtemps qu'une exécution, donc s.save(path) écrit un instantané dans un fichier JSON et load_snapshot(path) le relit. Le fichier contient la configuration.
  • Un SnapshotDiff a routes_added, routes_removed, neighbors_added, neighbors_removed, interfaces_added, interfaces_removed, interfaces_changed (des paires avant et après) et config (un ConfigDiff). Il est faux quand rien n'a bougé.
  • Ce qui change de lui-même n'est pas comparé : l'âge des routes, les temps de maintien, les métriques, les durées de fonctionnement. Une route est la même route quand sa VRF, son protocole, son réseau, sa longueur de préfixe et son prochain saut sont les mêmes.
  • Une chose que la plateforme n'a pas est une liste vide : pas de routes sur AireOS, pas de voisins sur un ASA. Les voisins viennent de CDP, et de LLDP sur Junos. Les routes sont celles de la table globale.
  • Deux instantanés de deux équipements différents sont refusés.

La sortie de snapshot_compare sous --replay liste chaque route, voisin, interface et ligne de configuration qui a bougé, par section, et No difference. pour un équipement où rien n'a bougé.

Le journal d'exécution

Chaque commande envoyée à un équipement est une ligne du journal d'exécution : les commandes SSH, les appels SNMP, les lignes d'un bloc change, et les commandes de joignabilité de reach.md. Chaque ligne contient l'équipement, la commande, l'heure de début en heure locale et en UTC, la durée, la réussite ou non, et l'erreur. Les secrets n'y entrent jamais.

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

Tiré de device_table sous --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

Sorties enregistrées : --replay et --save-replay

bogo run --save-replay FOLDER conserve chaque réponse d'un équipement dans un fichier. bogo run --replay FOLDER relit ces fichiers et ne se connecte à rien : pas de session SSH, pas de paquet SNMP, pas d'hôte de rebond. bogo test fait de même avec le dossier replay à côté du fichier (ou tests/replay dans un projet), ou saved quand il n'y a pas de replay.

Quoi Fichier
Une commande de session FOLDER/DEVICE/COMMAND.txt, la commande en minuscules, chaque suite d'autres signes étant écrite _ : show running-config devient show_running_config.txt
Valeurs SNMP FOLDER/DEVICE/snmp.txt, une valeur par ligne : OID, sorte et texte, séparés par des tabulations
Commandes de joignabilité FOLDER/reach/..., voir reach.md

Les fichiers sont en texte brut, donc un test peut utiliser une sortie écrite à la main. Un fichier manquant arrête la commande et nomme le fichier nécessaire :

RuntimeError: Replay mode has no saved output for 'show running-config'. The file needed is ...\saved\core-sw1\show_running_config.txt.

Junos

Le mot de plateforme est junos ; un inventaire peut écrire juniper_junos ou juniper. Une ligne écrite netmiko:juniper_junos ne garde que les sessions.

  • backup envoie show configuration et garde la forme avec accolades.
  • snapshot et routes lisent les réponses XML de Junos (| display xml), pas des colonnes de texte. Les voisins viennent de LLDP : Junos n'a pas CDP. Un protocole de route est le mot que Junos écrit, comme Static, Direct ou OSPF.
  • L'objet de configuration fonctionne sur des chemins (config-audit-templates.md), et le bloc change sur le modèle de commit de Junos (changes.md).

Les lecteurs ont été construits à partir des réponses d'un commutateur Junos virtuel d'une seule version (26.2R1.7), et le bloc change a été essayé sur un tel commutateur. Aucun équipement Junos physique n'a été utilisé. optics n'a pas été essayé : il demande un équipement avec un émetteur-récepteur.

Ce qui fonctionne sur quelle plateforme

Le tableau unique est bogolang/platforms.py. Une fonction utilisée sur une plateforme qui ne l'a pas est refusée avec une phrase qui liste les plateformes qui l'ont.

ios iosxe asa nxos aireos junos netmiko:NAME
ssh, show, run, sorties enregistrées oui oui oui oui oui oui oui
serial oui oui
backup oui oui oui oui oui oui
snapshot oui oui oui, sans voisins oui oui, sans routes oui
routes oui oui oui, sans vrf oui oui
Voisins par CDP oui oui oui oui
Voisins par LLDP oui oui oui oui
optics oui oui oui
Objet de configuration, audit oui oui oui oui oui
Test acl oui oui oui
Bloc change oui oui oui oui oui
Minuteur de l'équipement (revert_after) oui oui oui

netmiko:NAME est un équipement d'un autre fabricant, nommé comme le paquet SSH (netmiko) le nomme, par exemple netmiko:arista_eos. Il obtient les sessions, show, run et les sorties enregistrées, et rien d'autre. Les voisins et les optiques sont sur logs-topology.md et telecom-optics.md.

Non prouvé

Essayé sur de vrais équipements : un commutateur IOS-XE pour show version, SNMPv3, les instantanés, et les lectures de routes, de journaux et de voisins ; un commutateur Junos virtuel pour Junos. Jamais essayé sur du vrai matériel : l'hôte de rebond, le port console, les équipements NX-OS, AireOS et ASA, et optics. Les sorties NX-OS et AireOS des tests ont été écrites à la main. Voir not-proven.md.