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.
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.
nameetipsont obligatoires.platform,roleetsitesont facultatifs ; sans plateforme, l'équipement estios.- 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_iosestios,cisco_xeestiosxe,cisco_asaestasa,cisco_nxosestnxos,cisco_wlcestaireos,juniper_junosetjunipersontjunos. Un équipement d'un autre fabricant que le paquet SSH connaît devientnetmiko:NAME, par exemplearista_eosdevientnetmiko:arista_eos. - Deux colonnes choisissent des identifiants enregistrés :
loginpour SSH etsnmppour SNMP. Sans une telle colonne, le profildefaultest 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.
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,diroumore, écrit en entier :sh runest refusé. - Sur Junos, une commande doit commencer par
show,ping,traceroute,file listoufile show. Après un|, seulsmatch,except,count,find,last,displayetno-moresont acceptés. Unpingqui ne précise pas decountreçoitcount 5, car un ping Junos ne s'arrête pas de lui-même. - Une redirection vers
redirect,teeouappendest 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.
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;.textet.linescontiennent toujours la réponse. - Une
Rowpeut ê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.
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
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.
breaketreturnsont refusés par la vérification.continuesaute 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 unFailurepour 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 etbogo runse 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.
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
SnmpValuea.oid,.kind,.textet.number. Les sortes sontinteger,counter,gauge,timeticks,text,bytes,oidetip..numbersur une valeur qui n'est pas un nombre est une erreur. snmp_getsur un OID que l'équipement n'a pas lèveLookupError.snmp_walkdonne une liste vide.- Les identifiants viennent de
bogo login --snmp PROFILE, choisis par la colonnesnmp. 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.
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.
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 etload_snapshot(path)le relit. Le fichier contient la configuration. - Un
SnapshotDiffaroutes_added,routes_removed,neighbors_added,neighbors_removed,interfaces_added,interfaces_removed,interfaces_changed(des paires avant et après) etconfig(unConfigDiff). 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.
backupenvoieshow configurationet garde la forme avec accolades.snapshotetrouteslisent 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, commeStatic,DirectouOSPF.- L'objet de configuration fonctionne sur des chemins (config-audit-templates.md),
et le bloc
changesur 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.