Dokumentation aus Config generieren: Parsing, Source of Truth, NetBox

Dokumentation aus Config generieren ist für viele Netzwerk-Teams der schnellste Weg, eine verlässliche und aktuelle Dokumentation zu bekommen – ohne dass Menschen jede Änderung manuell nachpflegen müssen. In der Realität ist „Dokumentation“ oft veraltet, weil sie im Change-Prozess nicht automatisch mitläuft: VLANs werden erweitert, BGP-Policies angepasst, neue VRFs entstehen, aber die Wiki-Seite bleibt unverändert. Genau hier setzt ein moderner Ansatz an: Sie extrahieren strukturierte Daten aus laufenden Geräte-Konfigurationen (Parsing), normalisieren sie in ein konsistentes Datenmodell und schreiben sie in eine zentrale Source-of-Truth (SoT) wie NetBox. Von dort aus lassen sich wieder Reports, Diagramme, Compliance Checks und sogar Deployment-Templates generieren. Der Schlüssel ist, die Konfiguration nicht nur als Text zu betrachten, sondern als Datenquelle, aus der sich Fakten ableiten lassen: Interfaces, IPs, VLANs, Routing-Nachbarn, ACLs, QoS-Policies und Management-Standards. Dieser Artikel zeigt, wie Sie eine belastbare Pipeline aufbauen – inklusive Parsing-Strategien, Datenmodellierung, Drift-Erkennung und NetBox-Integration – ohne in Fragilität oder „Regex-Hölle“ zu enden.

Warum Config-basierte Dokumentation in der Praxis besser skaliert

Manuelle Dokumentation scheitert selten an mangelndem Willen, sondern an fehlender Kopplung zum Betrieb. Config-basierte Dokumentation ist erfolgreich, weil sie an den tatsächlichen Zustand gekoppelt ist. Damit erreichen Sie vier konkrete Vorteile:

• Aktualität: Dokumentation folgt Changes automatisch, statt sie nachträglich einzufangen.
• Objektivität: Die „Quelle“ ist die laufende Konfiguration oder der Live-State, nicht eine Interpretation.
• Auditierbarkeit: Änderungen werden als Datenpunkte sichtbar (z. B. „VRF hinzugefügt“, „BGP Neighbor geändert“).
• Automatisierung: Aus denselben Daten lassen sich Compliance Checks, Inventar-Reports und Golden-Config-Vergleiche ableiten.

Wichtig ist aber die Erwartung: Eine aus Config generierte Dokumentation ist hervorragender „Ist-Zustand“. Für „Soll-Zustand“ benötigen Sie zusätzlich ein Zielmodell (Source of Truth), das den gewünschten Zustand beschreibt.

Config als Wahrheit oder Source of Truth als Wahrheit?

Bevor Sie technisch starten, müssen Sie eine strategische Entscheidung treffen, weil sie Ihr Datenmodell und Ihre Workflows bestimmt:

• Config ist die Wahrheit: Sie lesen regelmäßig Geräteconfigs aus und generieren daraus Dokumentation. Vorteil: schnell startbar, sehr realitätsnah. Risiko: „Spaghetti-Konfig“ wird zur Wahrheit, und Abweichungen werden nicht aktiv verhindert.
• Source of Truth ist die Wahrheit: NetBox (oder ein anderes SoT) ist der Soll-Zustand, und Konfigurationen werden daraus generiert. Vorteil: konsistent, kontrollierbar, gut für GitOps. Risiko: hoher Initialaufwand für Datenpflege und Modellierung.
• Hybrid (in der Praxis am häufigsten): NetBox beschreibt das Soll (Standorte, Geräte, Interfaces, IPAM), während Config/State den Ist-Zustand liefert und Drift sichtbar macht.

Für viele Teams ist Hybrid der beste Einstieg: Sie importieren Fakten aus der Config, validieren sie gegen NetBox und schließen die Lücken schrittweise.

Welche Daten sich sinnvoll aus Configs extrahieren lassen

Nicht alles ist gut aus der Config ableitbar. Ein pragmatisches Datenmodell trennt stabile Inventar-Objekte von dynamischen Zuständen.

• Stabil und gut extrahierbar: Hostname, Management-IP, Interface-Definitionen, VLANs, SVIs, VRFs, Routing-Protokoll-Konfiguration, ACL-Struktur, QoS-Klassen, NTP/Syslog/SNMP-Settings.
• Teilweise extrahierbar: BGP-Neighborships (Config ja, Session-State nein), OSPF Areas/Interfaces (Config ja, adjacency state nein).
• Schlecht nur aus Config: Live-Status (Up/Down), tatsächliche Nachbarn (LLDP/CDP live), MAC/ARP/ND, Drops/Errors, CPU/Memory. Das gehört in Telemetrie/Monitoring.

Ein guter Ansatz ist daher: Dokumentation aus Config für „Design- und Intent-Fakten“ und ergänzend Live-State aus „show“-Daten, Streaming Telemetry oder APIs.

Parsing-Strategien: Von „Regex“ zu robusten Parsern

Parsing ist der technische Kern – und zugleich die größte Fehlerquelle, wenn es zu schnell improvisiert wird. In der Praxis haben sich vier Parsing-Strategien etabliert, die sich kombinieren lassen.

Textbasierte Parser (Regex, TTP, TextFSM)

• Wann sinnvoll: Schnellstart, begrenzter Scope (z. B. VLANs, Interfaces, NTP), heterogene Plattformen.
• Vorteil: Flexibel, leicht zu erweitern.
• Risiko: Fragil bei Formatänderungen, schwer langfristig zu pflegen, Testaufwand steigt.

Bewährte Bausteine sind TextFSM und die NTC Templates, die für viele Vendor-Outputs standardisierte Templates liefern.

Strukturierte Parser (Genie/pyATS, vendor-spezifische Libraries)

• Wann sinnvoll: Cisco-zentrierte Umgebungen, stabile API/Parser-Unterstützung, Fokus auf „show“-Parsing zusätzlich zur Config.
• Vorteil: Höhere Robustheit, strukturiertes JSON als Output.
• Risiko: Abhängigkeit von Vendor-Ökosystem und Versionen, Lernkurve.

Für Cisco ist pyATS/Genie ein verbreiteter Ansatz, um „show“-Outputs in strukturierte Daten zu überführen.

Model-driven Ansätze (YANG/NETCONF/RESTCONF, OpenConfig, gNMI)

• Wann sinnvoll: Moderne Plattformen, langfristig stabile Datenmodelle, Telemetrie und Konfiguration als Daten.
• Vorteil: Weniger textfragil, klar definierte Modelle, bessere Automatisierbarkeit.
• Risiko: Nicht jede Plattform deckt alles ab, Modellabdeckung variiert, Integration komplexer.

Für einen Überblick eignen sich OpenConfig und die Grundlagen zu YANG (NETMOD Working Group).

Konfig-Parsing als AST (CiscoConfParse & ähnliche)

• Wann sinnvoll: IOS/IOS XE/NX-OS Configs als Textstruktur, wenn Sie Hierarchien (Interface-Blöcke, Router-Prozesse, Policy-Maps) zuverlässig erkennen müssen.
• Vorteil: Strukturierter Zugriff auf Parent/Child-Statements, weniger „Regex-Spaghetti“.
• Risiko: Fokus auf bestimmte Syntaxfamilien, Stillstand bei exotischen Features.

Pipeline-Architektur: So entsteht aus Configs eine belastbare Dokumentation

Stabile Systeme entstehen durch klare Pipeline-Stufen. Ein praxiserprobtes Modell umfasst fünf Schritte:

• Collect: Configs und/oder State-Daten einsammeln (SSH, API, Backup-System, Git-Repo).
• Parse: Rohdaten in strukturierte Entities umwandeln (Interfaces, IPs, VLANs, VRFs, Neighbors).
• Normalize: Vendor- und Syntaxunterschiede in ein einheitliches Datenmodell bringen.
• Validate: Plausibilitätschecks und Policy-Checks (z. B. „jede Management-IP in Mgmt-VRF“, „Trunks haben Allowed Lists“).
• Publish: Ergebnisse in NetBox/SoT schreiben und Reports/Docs generieren.

Diese Stufen sollten voneinander entkoppelt sein. Das erleichtert Tests, erlaubt Rollbacks und macht die Pipeline wartbar.

Normalisierung: Der wichtigste Schritt für Multi-Vendor und Skalierung

Parsing allein reicht nicht, weil Vendor-Modelle unterschiedlich sind. Normalisierung bedeutet: Sie definieren ein Zielschema und mappen alle Quellen darauf. Beispiele:

• Interface-Namen: „Gi1/0/1“ vs. „Ethernet1“ → Normalform + Original speichern.
• VRF-Konzept: IOS VRF vs. NX-OS VRF → Einheitliche VRF-Entity mit Tags (Tenant, Zone).
• VLAN & SVI: VLAN-ID, Name, SVI-IP(s), Gateway-Redundanz → ein Modell, das beides abbildet.
• Routing Peers: BGP neighbor config, AFI/SAFI, Policy references → normalisierte Peer-Entity.

Der Vorteil: Ab diesem Punkt ist Ihre Dokumentation vendorunabhängig, und Ihre Reports/Checks müssen nicht mehr „Cisco vs. Juniper vs. Arista“ unterscheiden.

NetBox als Source of Truth: Was Sie dort abbilden sollten

NetBox ist in vielen Organisationen die zentrale SoT für Netzwerk-Assets und IPAM. Für „Dokumentation aus Config generieren“ ist NetBox besonders geeignet, weil es Inventar, Standortmodell, IP-Adressen, VRFs und Custom Fields zusammenführen kann. Bewährt hat sich eine klare Trennung:

• In NetBox als Soll/Ist-Basis: Sites, Racks, Devices, Interfaces, VRFs, Prefixes, IPs, VLANs, Circuits (wenn genutzt).
• Als erweiterte Metadaten: Tags, Tenants, Rollen, Criticality, Owner, Change-Klassen.
• Nicht als Live-State: Interface-Status, BGP Session-State, Drops/CPU – das gehört in Monitoring/Telemetry.

Ein praxistaugliches Ziel ist: NetBox enthält genug Struktur, um Ihre Dokumentation und Templates zu generieren, und Ihre Pipeline schreibt aus Configs nur das, was zu diesem Modell passt.

NetBox-Integration: Schreibstrategien, Konflikte und Datenqualität

Wenn Sie Daten aus Configs in NetBox schreiben, brauchen Sie Regeln, um Konflikte und „Flapping“ zu vermeiden.

• Write-Policy: Welche Felder dürfen aus der Config überschrieben werden (z. B. Interface-Description), welche nicht (z. B. Rack-Position)?
• Conflict Handling: Wenn NetBox und Config widersprechen: gewinnt NetBox (SoT) oder gewinnt Config (Ist)? Im Hybridmodell sollten Konflikte als Drift markiert werden, nicht blind überschrieben.
• Idempotenz: Jeder Lauf der Pipeline sollte reproduzierbar sein und keine unnötigen Änderungen erzeugen.
• Human-in-the-loop: Kritische Änderungen (z. B. VRF neu, Prefix verschoben) sollten Review erfordern.

Für Teams mit GitOps ist ein starkes Pattern: Die Pipeline erzeugt Pull Requests mit vorgeschlagenen NetBox-Änderungen (oder Reports), statt direkt produktive Daten zu überschreiben.

Source of Truth erweitern: Custom Fields, Tags und Naming-Standards

NetBox wird besonders wertvoll, wenn Sie Governance-Daten ergänzen, die in Configs nicht sauber existieren. Dazu zählen:

• Geräterolle: Access, Distribution, Core, Leaf, Spine, Border.
• Security Zone/Tenant: Für Segmentierung und Policy-Reports.
• Ownership: Verantwortliche Teams, Applikationsowner, Betriebskritikalität.
• Lifecycle: „In Betrieb“, „Decommission geplant“, „Lab“ – für Audit und Change-Filter.

Diese Daten machen aus „Dokumentation“ ein Steuerungsinstrument: Sie können Reports pro Tenant erzeugen, Compliance Checks pro Rolle laufen lassen und Changes gezielt begrenzen.

Dokumentation generieren: Welche Outputs wirklich nützlich sind

Das Ziel ist nicht ein 300-seitiges PDF, sondern operative Artefakte, die Teams im Alltag nutzen. Bewährte Output-Typen:

• Interface- und IPAM-Reports: „Welche IPs sind wo?“, „Welche Links verbinden welche Geräte?“, „Welche VRFs existieren?“
• Routing-Übersichten: BGP Peerings, OSPF Areas, Redistribution-Policies (als Diagramm oder Tabelle).
• Security-Reports: Management-ACLs, AAA-Standards, SNMPv3-Status, CoPP-Profile.
• Change-Diffs: Was hat sich seit gestern geändert? Welche Devices sind drifted?
• Topologie-Diagramme: Physische Links (LLDP/CDP), LAGs, kritische Uplinks, WAN-Circuits.

Ein guter Standard ist, Dokumentation als HTML/Markdown zu generieren und in ein zentrales Portal zu veröffentlichen, statt statische PDFs zu verteilen.

Drift Detection: Wenn Config und SoT auseinanderlaufen

Der größte Mehrwert einer SoT entsteht, wenn Abweichungen sichtbar werden. Drift Detection bedeutet: Sie vergleichen den Ist-Zustand (Config/State) mit dem Soll-Zustand (NetBox/Intent) und erzeugen Findings.

• Typische Drift-Fälle: Uplink ohne Allowed VLAN List, fehlender NTP-Server, SNMPv2c noch aktiv, Interface-Descriptions weichen ab, VRF-Routen fehlen.
• Bewertung: Nicht jeder Drift ist kritisch. Nutzen Sie Severity-Klassen (Info/Warn/Critical).
• Remediation: Automatisch korrigieren nur dort, wo Sie Idempotenz und Risiko beherrschen; sonst als Change-Ticket/PR.

Die Drift-Perspektive sorgt dafür, dass Dokumentation nicht nur „schön“ ist, sondern aktiv Betrieb stabilisiert.

Validierung und Tests: Parser-Qualität ist ein Produkt, kein Skript

Parsing-Pipelines scheitern häufig, weil sie nicht getestet werden. Stabilität erreichen Sie nur mit Engineering-Disziplin:

• Golden Samples: Halten Sie Beispiel-Configs aus verschiedenen Plattformen/Versionen als Testfälle vor.
• Unit Tests: Jede Parsing-Regel hat Tests (Input → erwartetes JSON).
• Schema Validation: Validieren Sie normalisierte Daten gegen ein Schema (z. B. JSON Schema), um „stille“ Fehler zu vermeiden.
• Regression Tests: Wenn Vendor-Outputs sich ändern, erkennen Sie Breaks früh.

Ein hilfreiches Konzept ist „Contract Testing“: Wenn Ihre Parser ein bestimmtes Datenmodell liefern müssen, testen Sie dieses Modell, nicht nur den Text.

Security und Compliance: Secrets, Minimierung und Zugriffskontrolle

Wenn Sie Konfigurationen sammeln und in Systeme schreiben, entstehen neue Risiken. Ein Secure-by-Design Ansatz umfasst:

• Secrets-Handling: Passwörter/Keys nicht in Klartext speichern; Redaction beim Export; Nutzung eines Secret Managers.
• Least Privilege für Collector: Read-only Accounts, getrennt nach Rolle, und nur notwendige Rechte.
• Audit Logs: Wer hat welche Config wann gezogen? Wer hat NetBox-Daten geändert?
• Datenschutz: Interface-Descriptions und Kommentare können personenbezogene Daten enthalten; Policy definieren.

Ein häufiger Fehler ist, „Backup-Configs“ als unkritisch zu behandeln. In Wirklichkeit enthalten sie oft genug Informationen, um ein Netz zu kompromittieren.

Tooling-Patterns: Nornir/Ansible, NetBox Plugins und Reporting

Für die Umsetzung gibt es bewährte Patterns, die unabhängig vom konkreten Tool-Stack funktionieren:

• Collector-Layer: Nornir oder Ansible für das Einsammeln von Configs/State, mit Inventory aus NetBox.
• Parser-Layer: TextFSM/NTC Templates, pyATS/Genie oder YANG/gNMI, je nach Plattform und Ziel.
• Publisher-Layer: NetBox API für Writes, plus Reporting (Markdown/HTML) und Ticketing/PR-Erstellung.
• Quality Gates: Linting, Schema Validation, Policy Checks, bevor Daten „offiziell“ werden.

NetBox kann dabei nicht nur Ziel, sondern auch Quelle sein: Viele Teams nutzen NetBox als Inventory für Automatisierung, während Parser die Ist-Daten zurückschreiben oder Drift markieren.

Typische Fallstricke und wie Sie sie vermeiden

• Zu früh alles parsen wollen: Starten Sie mit 5–10 klaren Entities (Interfaces, IPs, VLANs, VRFs, BGP Peers), dann iterativ erweitern.
• Regex ohne Tests: Parsing ohne Unit Tests ist langfristig instabil. Bauen Sie früh Test-Samples auf.
• SoT wird „Datenfriedhof“: Ohne Ownership und Lifecycle-Management bleiben veraltete Prefixes/VLANs stehen. Definieren Sie Owner und Reviews.
• Blindes Überschreiben: Config schreibt NetBox „kaputt“ oder umgekehrt. Nutzen Sie Drift-Mechanik statt Overwrite.
• Keine Redaction: Secrets landen in Git/NetBox/Reports. Redaction und Secret-Handling sind Pflicht.
• Keine Semantik: Ohne Rollen/Tags/Zone-Modelle bleibt Dokumentation „nur Inventar“. Ergänzen Sie Governance-Daten.

Blueprint: Schritt-für-Schritt Startplan für „Dokumentation aus Config generieren“

• Phase 1: Config-Collection standardisieren (Quelle, Format, Zeitplan, Redaction).
• Phase 2: Parser für Kernobjekte bauen (Devices, Interfaces, IPs, VLANs, VRFs) + Unit Tests.
• Phase 3: Normalisiertes Datenmodell definieren und gegen Schema validieren.
• Phase 4: NetBox als SoT aufsetzen/befüllen (Sites, Roles, IPAM) und Write-Policy festlegen.
• Phase 5: Drift Detection einführen und Reports/PRs generieren.
• Phase 6: Erweiterung um Routing- und Security-Entities (BGP Policies, ACL-Bibliotheken, Golden Config Checks).

Dieses Vorgehen verhindert, dass das Projekt an „zu großer Vision“ scheitert. Sie liefern früh Nutzwert und bauen Qualität schrittweise aus.

Outbound-Referenzen

• NetBox Dokumentation für Datenmodell, API und Best Practices rund um Source of Truth und IPAM.
• NTC Templates (TextFSM) als Sammlung praxiserprobter Parser-Templates für Multi-Vendor „show“-Outputs.
• TextFSM als Basiswerkzeug für strukturierte Extraktion aus CLI-Outputs.
• Cisco pyATS/Genie für robuste, strukturierte Parser und State-Extraktion in Cisco-Umgebungen.
• OpenConfig für modellgetriebene Konfiguration und Telemetrie-Modelle über Vendor-Grenzen hinweg.
• IETF NETMOD / YANG als Einstieg in YANG-Modelle und standardisierte Network-Data-Modeling-Grundlagen.

Cisco Netzwerkdesign, CCNA Support & Packet Tracer Projekte

Cisco Networking • CCNA • Packet Tracer • Network Configuration

Ich biete professionelle Unterstützung im Bereich Cisco Computer Networking, einschließlich CCNA-relevanter Konfigurationen, Netzwerkdesign und komplexer Packet-Tracer-Projekte. Die Lösungen werden praxisnah, strukturiert und nach aktuellen Netzwerkstandards umgesetzt.

Diese Dienstleistung eignet sich für Unternehmen, IT-Teams, Studierende sowie angehende CCNA-Kandidaten, die fundierte Netzwerkstrukturen planen oder bestehende Infrastrukturen optimieren möchten. Finden Sie mich auf Fiverr.

Leistungsumfang:

• Netzwerkdesign & Topologie-Planung

• Router- & Switch-Konfiguration (Cisco IOS)

• VLAN, Inter-VLAN Routing

• OSPF, RIP, EIGRP (Grundlagen & Implementierung)

• NAT, ACL, DHCP, DNS-Konfiguration

• Troubleshooting & Netzwerkoptimierung

• Packet Tracer Projektentwicklung & Dokumentation

• CCNA Lern- & Praxisunterstützung

Lieferumfang:

• Konfigurationsdateien

• Packet-Tracer-Dateien (.pkt)

• Netzwerkdokumentation

• Schritt-für-Schritt-Erklärungen (auf Wunsch)

Arbeitsweise:Strukturiert • Praxisorientiert • Zuverlässig • Technisch fundiert

CTA:
Benötigen Sie professionelle Unterstützung im Cisco Networking oder für ein CCNA-Projekt?
Kontaktieren Sie mich gerne für eine Projektanfrage oder ein unverbindliches Gespräch. Finden Sie mich auf Fiverr.