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

Journaux et topologie

Événements de journal et topologie à partir des voisins.

Toutes les pages de documentation

Cette page couvre deux groupes de commandes. Le premier lit les événements de journal d'un équipement ou d'un fichier enregistré. Le second lit les voisins CDP et LLDP des équipements et dessine la topologie qu'ils forment.

Les deux ne font que lire. Un équipement est joint par une session en lecture seule, comme sur la page des équipements. Avec bogo run --replay FOLDER, les sorties enregistrées sont lues et rien ne se connecte (voir les outils).

Événements de journal

Commande Donne
logs(d: Device, zone: str = 'local') list[LogEvent], lu sur l'équipement
read_logs(path: str, zone: str = 'local') list[LogEvent], lu dans un fichier enregistré

logs(d) envoie une commande. Sur un équipement Cisco, c'est show logging. Sur un équipement Junos, c'est show log messages | no-more. Un équipement Junos qui refuse la commande, par exemple parce que l'utilisateur n'a pas le droit de lire le fichier, arrête le programme avec une phrase qui nomme l'équipement et la commande.

read_logs(path) lit un fichier enregistré depuis un équipement ou depuis un serveur syslog. Rien dans le fichier ne lève d'erreur : une ligne qui ne peut pas être lue est ignorée.

Ce qu'une ligne doit contenir

  • Une ligne Cisco n'est un événement que si elle contient un code de message comme %LINK-3-UPDOWN:. Les codes ASA sont lus de la même façon.
  • Une ligne dans la forme syslog habituelle (Nov 18 07:36:33 host program[123]: text) est un événement sans gravité. Un fichier Junos et un fichier Linux ne peuvent pas être distingués, donc les deux sont lus de cette façon. Quand une ligne Junos porte sa priorité (%DAEMON-5-RPD_RT_HWM_NOTICE:), la gravité est lue à partir d'elle.
  • Une ligne last message repeated N times est ignorée.

Le LogEvent

Champ Type Ce qu'il contient
.time Moment \| None L'heure écrite par l'équipement ; None quand la ligne n'en a pas (un horodatage de temps de fonctionnement)
.device str Le nom de l'équipement : celui de logs(d), ou l'hôte écrit sur la ligne d'un fichier de serveur
.facility str Sur Cisco, la partie avant la gravité (LINK) ; sur Junos et Linux, le programme (rpd, sshd)
.severity int \| None De 0 (urgence) à 7 (débogage) ; None quand la ligne ne le dit pas
.mnemonic str La dernière partie du code (UPDOWN)
.code str Le code tel qu'il est écrit, sans le % : LINK-3-UPDOWN, AUTH-6, UI_COMMIT
.message str Le texte après le code
.raw str La ligne entière

Heure et fuseau

Un équipement n'écrit souvent ni l'année ni le fuseau.

  • Le fuseau est celui donné avec zone=. Il accepte "local" (le fuseau de l'ordinateur), "UTC" ou un nom complet comme "America/Bogota". Un nom faux arrête le programme avant que quoi que ce soit soit contacté.
  • Un fuseau écrit sur la ligne est utilisé quand Bogolang le connaît. Sinon, le fuseau donné est utilisé.
  • Un horodatage sans année prend l'année en cours, ou l'année d'avant quand l'année en cours placerait l'événement plus d'un jour dans le futur.
  • Dans un fichier d'un serveur syslog, l'heure propre de l'équipement est utilisée quand la ligne en a une, sinon celle du serveur.

Un équipement peut écrire les heures de son journal en UTC alors que son horloge affiche l'heure locale. Bogolang ne peut pas le voir à partir des lignes, car elles ne portent pas de fuseau. Dans ce cas, logs(d, zone="UTC") est le bon appel. Sur IOS, la ligne service timestamps log datetime localtime show-timezone sur l'équipement lève le doute.

Un exemple

Un fichier enregistré depuis un serveur syslog :

Nov 18 07:30:02 192.0.2.1 120: Nov 18 07:30:01.512: %LINK-3-UPDOWN: Interface GigabitEthernet1/0/24, changed state to down
Nov 18 07:30:03 192.0.2.1 121: Nov 18 07:30:02.514: %LINEPROTO-5-UPDOWN: Line protocol on Interface GigabitEthernet1/0/24, changed state to down
Nov 18 07:31:10 192.0.2.2 88: Nov 18 07:31:09: %SYS-5-CONFIG_I: Configured from console by admin on vty0 (198.51.100.7)
Nov 18 07:36:33 edge-fw1 sshd[812]: Accepted publickey for admin from 198.51.100.7 port 51515
this line is not a log event
Bogolang
events: list[LogEvent] = read_logs("syslog.log", zone="UTC")
for e in events:
    print(e.time, e.device, e.code, e.severity, e.message)
table(events, ["time", "device", "code", "message"])

La sortie :

2026-11-18 07:30:01 UTC 192.0.2.1 LINK-3-UPDOWN 3 Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:30:02 UTC 192.0.2.1 LINEPROTO-5-UPDOWN 5 Line protocol on Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:31:09 UTC 192.0.2.2 SYS-5-CONFIG_I 5 Configured from console by admin on vty0 (198.51.100.7)
2026-11-18 07:36:33 UTC edge-fw1  None Accepted publickey for admin from 198.51.100.7 port 51515
time                     device     code                message
-----------------------  ---------  ------------------  -----------------------------------------------------------------------
2026-11-18 07:30:01 UTC  192.0.2.1  LINK-3-UPDOWN       Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:30:02 UTC  192.0.2.1  LINEPROTO-5-UPDOWN  Line protocol on Interface GigabitEthernet1/0/24, changed state to down
2026-11-18 07:31:09 UTC  192.0.2.2  SYS-5-CONFIG_I      Configured from console by admin on vty0 (198.51.100.7)
2026-11-18 07:36:33 UTC  edge-fw1                       Accepted publickey for admin from 198.51.100.7 port 51515

La quatrième ligne n'a pas de code Cisco. C'est un événement sans gravité, et sa facility est sshd. La cinquième ligne est ignorée.

Filtrer et compter

Le filtrage se fait en Bogolang ordinaire. Comme .severity peut valoir None, la vérification refuse e.severity <= 3 tant que le programme ne dit pas ce que signifie une gravité inconnue :

Bogolang
events: list[LogEvent] = read_logs("syslog.log")
serious: list[LogEvent] = [e for e in events if e.severity is not None and e.severity <= 3]
flaps: list[LogEvent] = [e for e in events if e.mnemonic == "UPDOWN"]
print(len(serious), "serious,", len(flaps), "up or down")

Dans un bloc on syslog, la gravité est toujours un nombre : un paquet syslog en porte toujours une. Ce bloc reçoit un SyslogEvent, décrit sur la page surveiller et écouter.

SyslogEvent

Un SyslogEvent est un LogEvent avec deux champs de plus, tous deux toujours connus :

Champ Type Ce qu'il contient
.source IP L'adresse d'où vient le paquet
.received Moment Quand il est arrivé, selon l'horloge de cet ordinateur

Un événement lu dans un fichier ou dans show logging est un simple LogEvent. Ainsi, un tableau de tels événements garde ses huit colonnes.

Voisins

Commande Donne
neighbors(d: Device) list[Neighbor], une entrée par voisin et par port local, triée par port local

Elle ouvre une session et envoie les commandes CDP et LLDP que la plateforme possède :

Plateforme Commandes
ios, iosxe, nxos show cdp neighbors detail, show lldp neighbors detail
aireos show cdp neighbors detail
junos show lldp neighbors detail \| display xml
asa aucune : neighbors refuse l'équipement avec une phrase qui nomme les plateformes qui fonctionnent

Un voisin vu par les deux protocoles est listé une seule fois. Sa source est alors "cdp+lldp" : les valeurs CDP passent d'abord et LLDP comble les manques. Un protocole désactivé sur l'équipement ne donne aucun voisin. Ce n'est pas une erreur.

Champ Type Ce qu'il contient
.device str L'équipement local
.local_port Intf Le port local
.name str Le nom du voisin, tel qu'il l'annonce
.port str Le port du voisin, tel qu'il l'annonce
.platform str La plateforme du voisin, quand elle est annoncée
.ip IP \| None Son adresse de gestion, quand elle est annoncée
.source str "cdp", "lldp" ou "cdp+lldp"
Bogolang
sw1: Device = Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")
for n in neighbors(sw1):
    print(n.local_port, n.name, n.port, n.platform, n.ip, n.source)

Lancé avec --replay sur des sorties enregistrées, il a affiché :

Gi1/0/1 access-sw2.example.net GigabitEthernet1/0/49 cisco C9300-48P 192.0.2.2 cdp
Gi1/0/48 edge-rt1 GigabitEthernet0/0/0 cisco ISR4331/K9 192.0.2.254 cdp+lldp

Un voisin LLDP qui n'annonce pas de nom de système est ignoré. Un port local dont Bogolang ne peut pas lire le nom est ignoré aussi.

Topologie

Commande Donne
topology(devices: list[Device], parallel: int = 10) Topology

topology lit les voisins de chaque équipement, parallel à la fois. Un équipement qui échoue n'arrête pas les autres : il va dans .failed avec la raison.

Membre Ce qu'il donne
.nodes list[str] : chaque nom vu, les équipements de l'inventaire et les voisins hors de celui-ci
.links list[Link] : chacun avec .a, .a_port, .b, .b_port
.failed list[tuple[str, str]] : le nom et la raison de chaque équipement qui n'a pas pu être lu
.neighbors_of(name: str) list[str] : les noms à un câble de distance
.path(a: str, b: str) list[str] : les noms de a à b avec le moins de sauts, les deux extrémités comprises ; [] quand il n'y a pas de chemin
.save(path: str) écrit .json, .csv ou .dot, choisi selon la fin du nom de fichier

Comment les liens sont construits :

  • Un câble vu depuis ses deux extrémités est un seul lien. Deux câbles entre les deux mêmes équipements sont deux liens.
  • Un nom de voisin est rapproché d'un nom de l'inventaire sans sa partie domaine et sans tenir compte des majuscules : access-sw2.example.net est access-sw2.
  • Quand un voisin annonce son port sous une forme que Bogolang ne peut pas lire, les deux extrémités restent deux liens à un seul côté.
  • Un nom demandé à .path ou .neighbors_of qui n'est pas un nœud arrête le programme avec une erreur.
Bogolang
sw1: Device = Device(name="core-sw1", ip=192.0.2.1, platform="iosxe")
sw2: Device = Device(name="access-sw2", ip=192.0.2.2, platform="iosxe")
t: Topology = topology([sw1, sw2])
print(t)
for k in t.links:
    print(k.a, k.a_port, "--", k.b, k.b_port)
print(t.path("access-sw2", "edge-rt1"))
print(t.failed)
t.save("topology.dot")

Sur les mêmes sorties enregistrées :

Topology(3 nodes, 2 links, 0 failed)
access-sw2 Gi1/0/49 -- core-sw1 Gi1/0/1
core-sw1 Gi1/0/48 -- edge-rt1 Gi0/0/0
['access-sw2', 'core-sw1', 'edge-rt1']
[]

edge-rt1 n'est pas dans la liste donnée à topology. C'est un nœud parce que core-sw1 le voit. Le fichier topology.dot :

graph topology {
  "access-sw2";
  "core-sw1";
  "edge-rt1";
  "access-sw2" -- "core-sw1" [taillabel="Gi1/0/49", headlabel="Gi1/0/1"];
  "core-sw1" -- "edge-rt1" [taillabel="Gi1/0/48", headlabel="Gi0/0/0"];
}

Un fichier .dot s'ouvre dans Graphviz et dans plusieurs outils de dessin. Bogolang ne dessine pas l'image lui-même.

.path compte les sauts dans ce que CDP et LLDP voient : des câbles, pas le routage. Ce n'est pas le chemin que prend un paquet. Pour cela, voir la recherche de route sur la page planification, routes et listes d'accès.

Limites

  • Les événements de journal, les voisins et la topologie ont lu un commutateur IOS-XE et deux commutateurs Junos virtuels. D'autres versions et plateformes peuvent écrire les horodatages et les noms de ports sous des formes que les tests n'ont pas.
  • Les équipements NX-OS et AireOS n'ont jamais été lus pour de vrai. Leurs sorties dans les tests ont été écrites pour les tests. Voir non prouvé.
  • Un voisin NX-OS porte souvent un numéro de série dans son nom. Un tel nom ne correspond pas à l'inventaire et devient un nœud en plus.