Netzwerkdokumentation gehört zu den Aufgaben, die im IT-Alltag regelmäßig aufgeschoben werden – bis das Netz
ausfällt, ein neuer Kollege eingearbeitet werden muss oder ein Audit bevorsteht. Wer in diesem Moment keine
aktuelle Dokumentation hat, verliert wertvolle Zeit und arbeitet im Blindflug.
Eine gute Netzwerkdokumentation ist kein Selbstzweck. Sie hat konkrete Nutzen in mehreren Szenarien:
Troubleshooting: Im Fehlerfall ermöglicht eine aktuelle IP-Tabelle und Topologieübersicht die
schnelle Eingrenzung des Problems. Wer weiß, welches Gerät auf welchem Switch-Port hängt, spart sich
stundenlanges Suchen im Netz oder in veralteten Notizen.
Onboarding: Ein neuer Netzwerkadministrator oder ein externer Dienstleister braucht
einen schnellen Überblick. Eine strukturierte Dokumentation mit Topologiediagramm, VLAN-Tabelle und
Geräteinventar ist der beste Einstiegspunkt und reduziert die Einarbeitungszeit erheblich.
Änderungsmanagement: Jede Änderung an der Infrastruktur – ob neues VLAN, geänderter
Routing-Eintrag oder Austausch eines Switches – muss nachvollziehbar sein. Ohne Dokumentation ist
unklar, wer was wann geändert hat und warum eine bestimmte Entscheidung getroffen wurde.
ITIL-Kontext: Im Rahmen von ITIL (IT Infrastructure Library) ist die
Konfigurationsverwaltung (Configuration Management) ein zentraler Prozess. Die CMDB
(Configuration Management Database) lebt von aktuellen und verlässlichen Daten – und das Netzwerk ist
ein wesentlicher Teil davon. Eine gepflegte Netzwerkdokumentation ist die Grundlage für einen
funktionierenden Change-Management-Prozess.
Die wichtigste Eigenschaft einer Netzwerkdokumentation ist nicht ihre Ausführlichkeit, sondern ihre
Aktualität. Eine veraltete Dokumentation kann im Ernstfall gefährlicher sein als gar keine, weil sie
falsche Annahmen erzeugt. Deshalb ist es entscheidend, Prozesse zu etablieren, die eine Aktualisierung
der Dokumentation als festen Bestandteil jeder Infrastrukturänderung verankern.
2. Was gehört in eine Netzwerkdokumentation?
Eine vollständige Netzwerkdokumentation besteht aus mehreren Schichten, die zusammen ein konsistentes
Bild der Infrastruktur ergeben. Die wichtigsten Bestandteile im Überblick:
2.1 IP-Adressplan (IPAM)
Der IP-Adressplan ist das Herzstück jeder Netzwerkdokumentation. Er listet alle genutzten Subnetze,
deren Zweck, die zugewiesenen IP-Adressen, zugehörige Hostnamen und Gerätetypen. Ein strukturiertes
IPAM (IP Address Management) verhindert Adresskonflikte und ermöglicht schnelles Auffinden von Geräten.
Werkzeuge wie NetBox, phpIPAM oder auch eine einfach gepflegte Tabelle in Git können diese Aufgabe
übernehmen, je nach Größe der Umgebung.
2.2 VLAN-Tabelle
VLANs sind logische Segmente des Netzwerks. Für jedes VLAN sollten VLAN-ID, Name, Zweck, zugeordnete
Subnetze und beteiligte Switches dokumentiert sein. Gerade in gewachsenen Umgebungen gibt es schnell
VLANs ohne klare Bedeutung oder doppelte IDs auf verschiedenen Switches – eine gepflegte VLAN-Tabelle
verhindert dieses "VLAN-Chaos" und ist oft der erste Ansatzpunkt bei Routing-Problemen zwischen Segmenten.
2.3 Physische Topologie
Die physische Topologie zeigt, wie Geräte physisch miteinander verbunden sind: welcher Server hängt an
welchem Switch-Port, über welche Kabel, in welchem Rack. Diese Ebene ist besonders wichtig bei
Hardware-Ausfällen, beim Einziehen neuer Kabel oder bei der Planung von Wartungsfenstern, da sie
zeigt, welche Abhängigkeiten beim Abschalten eines Geräts bestehen.
2.4 Logische Topologie
Die logische Topologie abstrahiert von der Verkabelung und zeigt Routing-Pfade, Firewall-Zonen,
VLAN-Übergänge und Segmentgrenzen. Sie beantwortet die Frage: Wie fließt der Datenverkehr durch das
Netzwerk? Diese Ebene ist besonders wertvoll für die Fehlersuche bei Konnektivitätsproblemen und für
das Verständnis von Sicherheitszonen.
2.5 Geräteinventar
Ein Geräteinventar listet alle Netzwerkgeräte mit Hersteller, Modell, Seriennummer, Firmware-Version,
Standort (Rack, Raum, Gebäude) und Management-IP. Es ist die Grundlage für Wartungsplanung,
Lizenzmanagement und die rechtzeitige Erkennung von Geräten, die das End-of-Support-Datum des
Herstellers erreicht haben.
2.6 Kabelplan
Der Kabelplan dokumentiert, welche Ports über welche Kabel verbunden sind, inklusive Kabelnummern,
Kabeltyp (Cat6, Glasfaser, DAC) und Länge. In strukturierten Verkabelungssystemen mit Patchfeldern ist
dies besonders relevant, da ein undokumentiertes Patchfeld die Fehlersuche enorm erschwert. Auch für
die Kapazitätsplanung – wann müssen neue Kabeltrassen gezogen werden – ist diese Information wertvoll.
2.7 Passwörter und Zugänge
Zugangsdaten gehören ausdrücklich nicht in die allgemeine Netzwerkdokumentation.
Sie sollten ausschließlich in einem dedizierten Passwort-Manager (z.B. Vaultwarden, Bitwarden, KeePass)
oder einem Secrets-Management-System (z.B. HashiCorp Vault) verwaltet werden. In der Dokumentation kann
auf den Namen des Eintrags im Passwort-Manager verwiesen werden, nicht aber auf das Passwort selbst.
Dieses Prinzip gilt auch für API-Tokens und SSH-Schlüssel.
3. NetBox – IPAM und DCIM in einem
NetBox ist eine Open-Source-Plattform für IP Address Management (IPAM) und Data Center Infrastructure
Management (DCIM). Sie wurde ursprünglich von DigitalOcean entwickelt und ist heute eines der meistgenutzten
Werkzeuge zur Netzwerkdokumentation in professionellen Umgebungen – aber auch im Homelab hervorragend
einsetzbar. NetBox basiert auf Django und PostgreSQL und bietet eine übersichtliche Weboberfläche sowie
eine vollständige REST-API.
NetBox bildet folgende Konzepte ab:
Sites: Standorte wie Rechenzentrum, Büro oder Homelab
Racks: Physische Racks an einem Standort mit Höheneinheiten und Belegungsplan
Devices: Einzelne Geräte mit Typ, Rolle, Seriennummer und Status
Interfaces: Netzwerkschnittstellen der Geräte inklusive Verkabelung (Cables)
Prefixes: IP-Subnetze mit Zweck, Status und VLAN-Zuordnung
IP-Adressen: Einzelne Adressen mit Hostnamen, Status und Gerätezuordnung
VLANs: VLAN-Gruppen und einzelne VLANs mit ID, Name und Status
Circuits: WAN-Anbindungen und Provider-Verbindungen mit Bandbreite und Vertragsdaten
3.1 Self-hosted mit Docker
NetBox lässt sich einfach per Docker Compose betreiben. Das offizielle Repository
netbox-community/netbox-docker stellt eine fertige Compose-Konfiguration bereit, die
NetBox, PostgreSQL, Redis und den Nginx-Proxy enthält.
git clone https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<EOF
services:
netbox:
ports:
- 8000:8080
EOF
docker compose pull
docker compose up -d
Nach dem Start ist NetBox unter http://localhost:8000 erreichbar. Der initiale
Superuser wird mit dem folgenden Befehl erstellt:
NetBox bietet eine vollständige REST-API. Alle Ressourcen können über HTTP-Anfragen erstellt, gelesen,
aktualisiert und gelöscht werden. Die interaktive API-Dokumentation ist unter
/api/schema/swagger-ui/ erreichbar. Ein einfaches Beispiel, das alle Prefixes abruft und
deren Beschreibungen ausgibt:
Für Python-basierte Automatisierung bietet sich die Bibliothek pynetbox an, die die
REST-API komfortabel abstrahiert und unter anderem Paginierung automatisch behandelt.
import pynetbox
nb = pynetbox.api("https://netbox.example.com", token="dein-token")
for prefix in nb.ipam.prefixes.all():
print(f"{prefix.prefix} – {prefix.description}")
4. Diagramme mit draw.io
Textuell strukturierte Daten wie IP-Tabellen oder VLAN-Listen reichen allein nicht aus, um ein Netzwerk
vollständig zu verstehen. Topologiediagramme bieten eine visuelle Übersicht, die sich gerade beim
Troubleshooting und in Gesprächen mit Kollegen oder Kunden als unverzichtbar erweist.
4.1 draw.io (diagrams.net)
draw.io (heute unter dem Namen diagrams.net verfügbar) ist ein kostenloses, browserbasiertes
Diagramm-Werkzeug, das auch als Electron-Desktop-App oder VS-Code-Erweiterung eingesetzt werden kann.
Es speichert Diagramme im XML-Format (.drawio), was die Versionierung in Git problemlos
ermöglicht. Für Netzwerktopologien bietet draw.io folgende relevante Funktionen:
Fertige Netzwerk-Shape-Bibliotheken für generische Netzwerkgeräte, Server und Clouds
Importierbare Cisco Stencils für realistische Gerätesymbole nach Cisco-Designstandard
Export als SVG, PNG oder PDF für Einbindung in Dokumentationswebsites oder Wikis
Ebenen (Layers) für physische und logische Topologie in einer gemeinsamen Datei
Einbettung in Confluence, Notion und andere Wikis über offizielle Integrationen
4.2 Versionshistorie von Diagrammen in Git
Da draw.io-Dateien reines XML sind, können Änderungen per git diff nachvollzogen werden.
Sinnvoll ist ein eigenes Unterverzeichnis im Dokumentations-Repository:
Vor jeder größeren Infrastrukturänderung sollte das Diagramm aktualisiert und ein aussagekräftiger
Commit erstellt werden, zum Beispiel: "Add server VLAN 50 to logical topology and update L3 routing".
So entsteht eine lückenlose Änderungshistorie, die parallel zur tatsächlichen Infrastrukturänderung verläuft.
4.3 Alternativen und ergänzende Werkzeuge
Für code-basierte Diagramme bietet Mermaid eine kompakte Textsyntax, die direkt in
Markdown-Dateien eingebettet werden kann und von GitHub, GitLab und Gitea direkt gerendert wird.
Das eignet sich gut für einfache Abhängigkeitsgraphen und Flussdiagramme, stößt aber bei komplexen
Netzwerktopologien schnell an Layout-Grenzen. Für automatisch aus Live-Daten generierte Topologien
bietet sich das Open-Source-Projekt netdisco an, das per SNMP und LLDP die Infrastruktur
erkundet.
5. Git als Dokumentationsbackend
Git ist nicht nur für Quellcode geeignet – es ist ein hervorragendes Versionierungssystem für jede Art
von Textdateien. Für Netzwerkdokumentation, die aus Markdown, CSV, YAML oder XML besteht, bietet Git
mehrere entscheidende Vorteile: vollständige Änderungshistorie, lesbare Diffs für jede Änderung,
Branching für größere Umbauten und einfache Kollaboration über Merge Requests bzw. Pull Requests.
5.1 Markdown-Dokumentation
Prosatext zur Erklärung von Netzwerksegmenten, Architekturentscheidungen oder Betriebsprozessen lässt
sich gut in Markdown verfassen. GitLab, Gitea und GitHub rendern Markdown direkt im Browser – die
Dokumentation ist damit ohne zusätzliche Werkzeuge lesbar. Auch Tabellen in Markdown werden von allen
gängigen Git-Plattformen unterstützt und eignen sich gut für überschaubare IP-Pläne.
5.2 IP-Adresspläne als CSV oder YAML
Für maschinenlesbare und versionierbare Daten bieten sich CSV oder YAML an. YAML hat den Vorteil
aussagekräftigerer Diffs, weil Feldnamen explizit im Text erscheinen. Ein Beispiel für eine
YAML-Struktur eines IP-Plans:
Für Teams bieten GitLab und Gitea integrierte Wikis, die selbst als Git-Repository geführt werden.
Dadurch können Dokumentation und Infrastrukturcode in derselben Plattform verwaltet werden. GitLab
bietet darüber hinaus die Möglichkeit, mit GitLab Pages aus Markdown-Dateien automatisch
eine statische Dokumentationswebsite zu generieren. So entsteht eine lesbare, intern erreichbare
Dokumentationsseite ohne zusätzlichen Hosting-Aufwand.
6. Automatisierung der Dokumentation
Manuell gepflegte Dokumentation veraltet schnell. Wer Teile der Dokumentation automatisch aus der
Live-Infrastruktur ableiten kann, erhält eine verlässlichere und aktuellere Datenbasis. Einige bewährte
Ansätze für die Automatisierung:
6.1 NetBox-Ansible-Integration
Ansible kann NetBox sowohl als Datenquelle (Dynamic Inventory) als auch als Ziel für automatisch
erzeugte Dokumentationsdaten verwenden. Das Ansible-Collection-Paket
netbox.netbox stellt Module bereit, um Geräte, IP-Adressen und Interfaces direkt aus
Ansible-Playbooks in NetBox zu pflegen. So wird NetBox zum Single Source of Truth, der nach jedem
Provisionierungsvorgang automatisch aktualisiert wird:
Umgekehrt kann NetBox als Dynamic-Inventory-Quelle für Ansible dienen: Ansible liest alle Geräte
einer bestimmten Rolle oder eines bestimmten Standorts direkt aus NetBox aus und spielt Konfigurationen
automatisiert ein, ohne eine statische Inventardatei pflegen zu müssen.
6.2 LLDP-Neighbor-Discovery für automatische Topologieerkennung
LLDP (Link Layer Discovery Protocol) ist ein standardisiertes Protokoll nach IEEE 802.1AB, über das
Netzwerkgeräte ihre direkten Nachbarn sowie eigene Fähigkeiten und Schnittstellen bekannt geben.
Viele verwaltbare Switches, Router und moderne Linux-Server mit dem Paket lldpd
unterstützen LLDP. Durch Auslesen der LLDP-Neighbortabellen lässt sich automatisch rekonstruieren,
welche Geräte miteinander verbunden sind:
# LLDP-Neighbors auf einem Linux-Host abfragen
lldpctl
# Ausgabe als JSON für maschinelle Weiterverarbeitung
lldpctl -f json | jq '.lldp.interface[] | {name: .name, neighbor: .chassis}'
Diese Daten können per Skript in NetBox oder eine andere Dokumentationsdatenbank geschrieben werden
und ergeben so eine automatisch erzeugte physische Topologie.
6.3 ntopng für Verkehrsanalyse und Host-Erkennung
ntopng ist ein Open-Source-Netzwerk-Traffic-Analyzer, der unter anderem automatisch
eine Übersicht aktiver Hosts, genutzter Protokolle und Kommunikationsbeziehungen erstellt. Er kann als
ergänzendes Werkzeug eingesetzt werden, um undokumentierte Geräte im Netz zu entdecken oder unerwartete
Kommunikationsbeziehungen sichtbar zu machen. ntopng lässt sich per Mirror-Port (SPAN) oder auf einem
inline-Sensor betreiben und zeigt in Echtzeit, welche IP-Adressen aktiv sind und miteinander
kommunizieren. Die Erkenntnisse können dann gezielt in die Dokumentation übernommen werden.
Nicht jede Umgebung rechtfertigt den Aufwand für eine vollständige NetBox-Installation mit
Ansible-Automatisierung. Für ein Homelab oder eine kleine Infrastruktur mit unter 50 Geräten empfiehlt
sich ein schlanker Ansatz, der wartbar bleibt, ohne überdimensioniert zu sein. Das Ziel ist ein
System, das so einfach ist, dass es tatsächlich gepflegt wird.
7.1 IP-Tabelle in Markdown und Git
Eine Markdown-Tabelle in einem Git-Repository reicht für kleine Umgebungen vollständig aus. Sie ist
ohne Werkzeug lesbar, versioniert und auf jeder Git-Plattform sofort dargestellt:
Die VLAN-Tabelle wird als YAML-Datei neben den Markdown-Dateien abgelegt. Sie ist maschinenlesbar und
kann bei Bedarf automatisch in NetBox importiert oder per Skript ausgewertet werden:
vlans:
- id: 1
name: "Management"
subnet: "10.0.0.0/24"
zweck: "Netzwerkgeräte und Server-Management-Interfaces"
- id: 20
name: "IoT"
subnet: "10.0.20.0/24"
zweck: "Smart-Home-Geräte, isoliert vom restlichen Netz"
firewall_regeln: "kein Zugriff auf VLAN 1, 30, 40"
- id: 30
name: "Gaeste"
subnet: "10.0.30.0/24"
zweck: "Gäste-WLAN, nur Internet-Zugriff"
firewall_regeln: "nur Port 80/443 nach außen erlaubt"
7.3 draw.io-Topologie im Git-Repository
Eine draw.io-Datei mit der physischen und logischen Topologie wird direkt im Git-Repository abgelegt.
Sie wird bei jeder Infrastrukturänderung aktualisiert und mit einem sprechenden Commit-Message
versioniert. Für Lesbarkeit ohne draw.io wird zusätzlich ein SVG-Export eingecheckt:
7.4 NetBox für IPAM ab mittlerer Infrastrukturgröße
Sobald die Infrastruktur wächst und manuelle Tabellen unübersichtlich werden, lohnt sich der Umstieg
auf NetBox. Der Einstieg über Docker Compose ist unkompliziert, und die bestehenden Markdown-Tabellen
können über ein einfaches Python-Skript mit pynetbox in NetBox importiert werden. Der
Vorteil: NetBox bietet Suche, Filterung, eine übersichtliche Weboberfläche und eine API für spätere
Automatisierung – ohne dass die Grundstruktur der Dokumentation grundlegend neu gedacht werden muss.
Das Wichtigste bleibt in jedem Fall: Dokumentation, die nicht gepflegt wird, ist wertlos. Besser eine
einfache, aktuelle Markdown-Datei in Git als eine mächtige NetBox-Instanz mit veralteten Daten.
Startet klein, wählt ein System, das zum eigenen Arbeitsfluss passt, und pflegt es konsequent als
festen Bestandteil jeder Infrastrukturänderung.