Cette page présente ce qu'un programme peut faire d'une configuration d'équipement une fois qu'il en a une : la lire
comme un objet, en comparer deux, la vérifier par rapport aux règles maison avec rule et audit, et
écrire des lignes d'équipement à partir de modèles. Rien de tout cela ne modifie un équipement.
Exemples : audit_rules, backup_diff.
D'où vient une configuration
| Appel | Résultat |
|---|---|
backup(d) |
La configuration en cours, lue sur l'équipement (voir devices.md) |
load_config(path, platform="ios") |
Un fichier enregistré, comme une sauvegarde de nuit. Ne lit aucun équipement |
Config(device, text, taken) |
Une configuration faite à partir d'un texte, comme dans un test |
snapshot(d).config |
La configuration contenue dans un instantané |
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
print(cfg.hostname, len(cfg.lines))
load_config nomme l'équipement d'après la ligne hostname du fichier, ou d'après le nom du fichier
quand il n'y en a pas. Le mot platform décide de la façon dont le fichier est lu : junos lit les formes
Junos (voir plus bas), tout autre mot lit les blocs par indentation, comme IOS, IOS-XE, ASA et NX-OS
les écrivent. L'objet configuration fonctionne sur ios, iosxe, asa, nxos et junos ; sur
aireos, il est refusé.
La configuration comme objet
Sur une Config |
Résultat |
|---|---|
.text, .lines |
Le texte entier, et ses lignes |
.hostname |
str, tiré de la ligne hostname |
.find(start) |
list[str] : chaque ligne qui commence par ce texte, à n'importe quelle profondeur |
.has(start) |
bool : existe-t-il une telle ligne |
.section(start) |
list[Section] : chaque bloc dont la première ligne commence par ce texte |
.interfaces |
list[InterfaceConfig] : un par bloc interface |
.save(path) |
Écrit le texte dans un fichier |
.warnings |
list[str] : ce qu'un lecteur de cette configuration doit savoir. Vide dans la plupart des cas |
Une Section est un bloc : .line est sa première ligne, .lines les lignes en dessous, sans
l'indentation propre au bloc, et elle a ses propres .find, .has et .section pour les
blocs qu'elle contient.
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
for vty in cfg.section("line vty"):
if vty.find("transport input") != ["transport input ssh"]:
print(f"{vty.line}: {vty.lines}")
print(cfg.has("service password-encryption"))
Sur un fichier avec deux blocs line vty, dont le second autorise telnet, ceci affiche :
line vty 5 15: ['transport input ssh telnet']
True
Comment les lignes sont reconnues :
- Une correspondance regarde le début d'une ligne, après les espaces du début. Les majuscules comptent telles qu'elles sont écrites.
findetsectioncherchent à toutes les profondeurs.cfg.section("address-family")trouve aussi les blocs sousrouter bgp.- Les lignes qui commencent par
!, les lignes vides, et les deux lignes qu'IOS écrit en tête deshow running-configne sont pas du contenu. - Le texte d'une bannière est gardé sous sa ligne de bannière et n'est jamais fouillé, donc une bannière qui contient des lignes ressemblant à de la configuration ne donne pas de fausse correspondance.
- Une interface n'est jamais lue comme faisant partie d'une autre interface, même là où IOS-XE en écrit une décalée d'un espace.
Interfaces
Une InterfaceConfig est une Section avec ces champs, lus une seule fois :
| Champ | Type | Signification |
|---|---|---|
.name |
Intf |
Gi1/0/1 et GigabitEthernet1/0/1 sont le même nom |
.description |
str |
Vide quand il n'y en a pas |
.shutdown |
bool |
|
.address |
IfAddr ou None |
L'adresse IPv4 principale. Pas une secondary, pas dhcp |
.mode |
str |
"access", "trunk", "routed" ou vide |
.access_vlan |
int ou None |
|
.trunk_vlans |
VlanSet ou None |
None quand il n'y a pas de ligne allowed vlan, ce qui sur IOS veut dire tous les VLAN. Les lignes add, remove et except sont suivies |
cfg: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
for i in cfg.interfaces:
if not i.shutdown and i.description == "":
print(f"{i.name}: no description, mode {i.mode or 'not set'}")
Lu sur un petit fichier :
Gi1/0/1 'uplink to edge-rt1' False None 'trunk' None 10,20
Gi1/0/2 '' False None 'access' 10 None
Gi1/0/3 '' True None '' None None
Vl10 '' False 192.0.2.1/24 'routed' None None
(nom, description, shutdown, adresse, mode, VLAN d'accès, VLAN du trunk). Une interface dont
le nom ne peut pas être lu est laissée hors de .interfaces ; cfg.section("interface ...") la trouve
quand même. Une ligne d'une interface qui ne peut pas être lue laisse son champ vide.
diff
diff(a: Config, b: Config) -> ConfigDiff
diff compare deux configurations section par section. Un ConfigDiff a .removed et
.added, chacun une liste de lignes écrites avec leur section devant :
interface GigabitEthernet1/0/3 / shutdown. Une ligne qui a seulement changé de place, les lignes ! et le
nombre d'octets en tête ne sont pas des changements. Il est faux quand rien n'a changé, et s'affiche sous forme de lignes - et
+, ou No difference..
old: Config = load_config("backups/core-sw1.cfg", platform="iosxe")
new: Config = load_config("configs/core-sw1.cfg", platform="iosxe")
changes: ConfigDiff = diff(old, new)
print(f"{len(changes.removed)} removed, {len(changes.added)} added")
print(changes)
La sortie de backup_diff se trouve sur devices.md.
Configurations Junos
Junos écrit sa configuration avec des accolades ou sous forme de lignes set. load_config(path,
platform="junos") lit l'une ou l'autre forme et reconnaît de lui-même laquelle c'est. backup(d) sur Junos
garde la forme avec accolades.
L'objet travaille sur des chemins : chaque instruction est un chemin de mots, comme dans la forme set sans
le mot set. Une recherche peut commencer à n'importe quel niveau, et les mots sont comparés en entier.
Sur une Config Junos |
Résultat |
|---|---|
.has("system services telnet") |
Existe-t-il une instruction dont le chemin commence par ces mots |
.find("system services") |
Les instructions dont le chemin commence ainsi, sous forme de chemins complets |
.section("interfaces ge-0/0/1") |
Les blocs à ce chemin, sous forme de Section |
.hostname |
Tiré de system host-name |
.set_lines |
Toute la configuration sous la forme set |
.inactive |
Les instructions désactivées |
.interfaces |
Une par interface et une par unité, comme ge-0/0/0.0 |
j: Config = load_config("edge-sw2.conf", platform="junos")
print(j.hostname, j.has("system services telnet"), j.inactive)
Sur un fichier avec set system services telnet et deactivate system services telnet, ceci
affiche edge-sw2 False ['system services telnet'].
- Une instruction désactivée n'est pas en vigueur.
has,findetsectionla laissent de côté ; elle figure dans.inactive. Une règle d'audit ne réussit jamais sur une ligne que l'équipement ignore. - Les instructions sous
groupssont des motifs, pas en vigueur : une recherche les laisse de côté, sauf si elle commence par le motgroups. - Groupes. Un fichier enregistré montre
apply-groupsmais pas ce dont l'équipement hérite. Quand un fichier l'utilise,.warningsdit que les instructions héritées ne sont pas comptées, et chaque ligneauditde cet équipement porte la même phrase. Unauditen direct litshow configuration | display inheritance no-comments, qui les montre. - Une ligne que le lecteur ne peut pas transformer en chemin l'arrête avec une erreur qui désigne la ligne par son numéro et ne montre jamais la ligne, car une configuration contient des secrets.
diffde deux configurations Junos compare leurs lignesset.- Sur les interfaces,
.shutdownest vrai pourdisable;.modevient de la famille de commutation, ou vaut"routed"quand l'unité a une adresse. Les VLAN désignés par leur nom sont retrouvés par le blocvlans; quand un nom n'est pas trouvé,.trunk_vlansest vide.
.set_lines et .inactive sur une configuration d'une autre plateforme sont refusés.
Règles d'audit
Une rule est une liste de tests, un par ligne, chacun vrai ou faux. audit(devices) exécute chaque
règle sur chaque équipement qu'elle concerne et donne une ligne par équipement et par règle.
edition 2027
class HouseRules:
rule "vty takes ssh only" for d:
config.section("line vty") != []
all(v.find("transport input") == ["transport input ssh"] for v in config.section("line vty"))
rule "passwords are encrypted" for d:
config.has("service password-encryption")
rule "clock from ntp" for d where d.role != "lab":
config.has("ntp server") # every device but the lab ones
@staticmethod
def main(args: list[str]) -> None:
devices: list[Device] = inventory("devices.csv")
result: AuditResult = audit(devices, configs="configs")
print(result)
for row in result.failed:
print(f"{row.device} fails '{row.rule}': {row.detail}")
- Dans une règle, trois noms existent : l'équipement (
dici, le mot aprèsfor),config(sa configuration, lue une fois par équipement) etshow(...), qui lit l'équipement en direct. wheredit quels équipements une règle concerne. Unwherequi lève une erreur donne une ligne en échec pour cet équipement et cette règle.- Un équipement échoue à une règle dès son premier test faux. Ce test est le détail de la ligne.
- Un test qui lève une erreur compte comme échoué, avec l'erreur comme détail. Il n'arrête pas l'audit.
- Un commentaire en fin de ligne de test est permis et ne fait pas partie du détail.
- Une règle ne contient pas de blocs : chaque test est écrit sur une seule ligne.
- Une règle se place dans le corps d'une classe ou dans une méthode. Dans le corps d'une classe, un champ de la classe est
atteint à travers la classe :
HouseRules.servers. - Deux règles du même nom arrêtent le programme quand il s'exécute.
audit
audit(devices: list[Device], configs: str = '', parallel: int = 10) -> AuditResult
- Avec
configs="folder", chaque configuration est lue depuisfolder/NAME.cfget aucun équipement n'est contacté. Une règle qui appelleshowéchoue alors sur cet équipement, avec une phrase qui dit pourquoi. Un fichier manquant fait échouer toutes les règles de cet équipement. - Sans
configs, chaque équipement est lu par SSH, jusqu'àparallelà la fois, avec les identifiants enregistrés parbogo login. Un équipement qui ne peut pas être lu échoue à toutes ses règles ; les autres continuent. - Un équipement dont la plateforme n'a pas d'objet configuration échoue à ses règles avec la phrase du tableau des plateformes.
Sur un AuditResult |
Résultat |
|---|---|
.rows |
list[AuditRow], une par équipement et par règle, dans l'ordre des équipements |
.failed |
Les lignes en échec |
.passed |
Vrai quand aucune n'a échoué. bool(result) est identique |
print(result) |
Un tableau, et une dernière ligne comme 2 of 3 failed |
Un AuditRow a .device, .rule, .passed et .detail. table(result.failed, ["device",
"rule", "detail"]) affiche les lignes en échec sous forme de tableau, comme le fait
audit_rules :
bogo run audit_rules.bogo
device rule detail
---------- -------------------------- ---------------------------------------------------------------
core-sw1 vty takes ssh only all(AuditRules.ssh_only(v) for v in config.section("line vty"))
core-sw1 ports in use are described AuditRules.undescribed(config) == []
access-sw2 vty takes ssh only all(AuditRules.ssh_only(v) for v in config.section("line vty"))
access-sw2 passwords are encrypted config.has("service password-encryption")
access-sw2 logs go to a server config.has("logging host")
access-sw2 clock from ntp config.has("ntp server")
access-sw2 ports in use are described AuditRules.undescribed(config) == []
7 of 14 checks failed.
core-sw1: no description on Gi1/0/3
access-sw2: no description on Vl10
Modèles
Un modèle est un fichier texte de lignes d'équipement avec des trous écrits {name}, sous la même forme que dans un
bloc change.
template(path: str) -> Template
Template.fill(d: Device, **values) -> str
Un fichier access-port.txt :
interface {port}
description {what}
switchport mode access
switchport access vlan {vlan}
snmp-server location {site}
t: Template = template("access-port.txt")
d: Device = Device(name="core-sw1", ip=192.0.2.11, platform="iosxe", site="north")
lines: str = t.fill(d, port=Intf("Gi1/0/7"), what="camera", vlan=30)
print(lines)
print(t.holes)
interface Gi1/0/7
description camera
switchport mode access
switchport access vlan 30
snmp-server location north
- Un trou prend sa valeur d'abord dans les noms donnés à
fill, puis dans l'équipement :name,ip,site,role,platformet chaque colonne supplémentaire de l'inventaire. - Une valeur peut être du texte, un nombre entier ou un type d'adresse (
IP,Net,IfAddr,MAC,Intf,VlanSet). UnSecretne peut pas remplir un trou. - Un trou sans valeur est une erreur qui nomme le trou et l'équipement :
ValueError: access-port.txt, line 4: the hole {vlan} has no value for device core-sw1. Give it as fill(d, vlan=...) or fill the 'vlan' column of the inventory.
Une cellule vide de l'inventaire compte comme une absence de valeur. Un texte vide donné exprès à fill est
accepté.
- Un trou est un simple nom. {vlan + 1} est refusé quand le fichier est lu : calculez la valeur en
Bogolang et passez-la par son nom. Un modèle n'a ni boucles ni conditions.
- {{ et }} sont de vraies accolades. Une } seule ou une { non fermée est refusée quand le fichier est lu,
avec le numéro de ligne.
- Les trous sont vérifiés quand le programme s'exécute, pas avant.
Un modèle rempli va dans un bloc change, seul sur sa ligne, et il est envoyé comme plusieurs lignes :
t: Template = template("access-port.txt")
for d in inventory("devices.csv"):
change on d:
apply:
{t.fill(d, port=Intf("Gi1/0/7"), what="camera", vlan=30)}
rollback:
default interface Gi1/0/7
verify:
"camera" in show("interfaces Gi1/0/7 description")
Voir changes.md.
Non prouvé
L'objet configuration a lu 86 vrais fichiers de sauvegarde sans erreur, et cinq règles d'audit ont été exécutées sur les 78 équipements IOS et IOS-XE qui en font partie. Les mises en forme d'ASA, NX-OS et AireOS ont été laissées hors de cet essai. Le lecteur Junos a été essayé sur les configurations de commutateurs Junos virtuels seulement. Voir not-proven.md.