MrBlake/mrb-netbox-topology-views
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README in English with standard structure

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
MrBlake
2026-09-30 13:37:00 +02:00
co-authored by Claude Opus 5.5
parent 4a12037ac4
commit ffe594a5f9
1 changed files with 140 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+140 -146
View File
@@ -1,92 +1,95 @@
# MRB NetBox Topology Views
Ein angepasster Fork von **NetBox Topology Views** mit erweiterten Rack-Ansichten,
interaktiver Kabelverfolgung und zusätzlichen Netzwerk-Icons.
A customised fork of **NetBox Topology Views** with extended rack views,
interactive cable tracing and additional network icons.
Das Plugin erzeugt Topologien aus den in NetBox gepflegten Geräten, Ports und
Kabeln. Neben der klassischen Topologie bietet dieser Fork eine vollständige
Darstellung einzelner oder mehrerer Racks einschließlich Vorderseite,
Rückseite und Verkabelung.
The plugin builds topologies from the devices, ports and cables maintained in
NetBox. In addition to the classic topology, this fork provides a complete view
of one or more racks including front, rear and cabling.
## Vorteile dieses Forks
| | |
|---|---|
| **Plugin name** | `netbox_topology_views` |
| **Package** | `netbox-topology-views` |
| **NetBox** | `4.7.x` |
| **Python** | see `setup.py` |
| **Repository** | <https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views> |
- Ein oder mehrere Racks gemeinsam anzeigen
- Geräte positionsgenau anhand ihrer Höheneinheiten darstellen
- Vorder- und Rückseite eines Racks getrennt betrachten
- Auf- und absteigende HE-Nummerierung sowie individuelle Start-HE automatisch berücksichtigen
- Rackübergreifende und externe Kabelverbindungen erkennen
- Geräte in der Kabeltopologie frei verschieben
- Geräte in der Kabeltopologie innerhalb jedes Racks nach ihrer Rackposition sortieren
- Kabeltopologie in den Browser-Vollbildmodus schalten
- Kabeltopologie zwischen 50 und 200 Prozent zoomen und im Vollbild scrollen
- Geräte in der Kabeltopologie mit rund 5 mm Abstand darstellen
- P2P-WirelessLinks und Multi-Access-WLANs als violette, gestrichelte Funkstrecken darstellen
- Funk-/WLAN-Verbindungen und Stromkabel in der Kabeltopologie der Rack-Ansicht optional ein-/ausblenden, farblich abgesetzt von Netzwerkkabeln (violett gestrichelt bzw. orange gepunktet)
- Manuelle Positionen pro Rack-Auswahl im Browser speichern
- Verbindungen eines Geräts beim Hover weiß hervorheben
- Alle verbundenen Ports und Gegenstellen eines Geräts anzeigen
- Schnittstellen eines Kabels beim Hover anzeigen
- Geräte und Kabel direkt aus der Topologie in NetBox öffnen
- Einzelne Racks, alle Racks oder die Kabeltopologie als SVG, PNG und draw.io exportieren
- Exporte grundsätzlich mit transparentem Hintergrund erzeugen
- Farben von Rackansicht und Export an den aktiven Light- oder Dark-Mode anpassen
- Topologie als PNG oder diagrams.net/draw.io-XML exportieren
- Zusätzliche Icons für Network-, Leaf-, Spine- und Aggregation-Switche
- Unterstützung für helle und dunkle NetBox-Themes
## Features
## Änderungen gegenüber dem Original
- Show one or more racks together
- Render devices at their exact rack unit position
- View front and rear of a rack separately
- Ascending/descending U numbering and custom starting unit are respected automatically
- Detect cross-rack and external cable connections
- Freely move devices in the cable topology
- Sort devices in the cable topology by rack position within each rack
- Browser full-screen mode for the cable topology
- Zoom the cable topology between 50 and 200 % and scroll in full-screen
- Render P2P wireless links and multi-access WLANs as purple dashed radio links
- Optionally show/hide wireless links and power cables in the rack view's cable topology, visually distinct from network cables (purple dashed / orange dotted)
- Store manual positions per rack selection in the browser
- Highlight a device's connections in white on hover
- Show all connected ports and peers of a device
- Show a cable's terminations on hover
- Open devices and cables in NetBox directly from the topology
- Export single racks, all racks or the cable topology as SVG, PNG and draw.io — always with transparent background
- Colours of rack view and export follow the active light or dark mode
- Additional icons for network, leaf, spine and aggregation switches
Dieser Fork ergänzt insbesondere:
### Changes compared to the original
1. Die neue Menükategorie **Weitere Ansichten**.
2. Eine Rack-Ansicht mit Filtern für Site, Location und mehrere Racks.
3. Positionsgenaue Rack-Elevations für Vorder- und Rückseite.
4. Eine Kabeltabelle mit A- und B-Terminierungen.
5. Eine interaktive, verschiebbare Kabeltopologie unter den Racks.
6. Hover-Hervorhebung und Port-zu-Port-Verfolgung für Geräte und Kabel.
7. Lokal gespeicherte Gerätepositionen und eine Funktion zum Zurücksetzen.
8. Ein erweitertes, skalierbares SVG-Iconset für Switch-Rollen.
9. Transparente SVG-, PNG- und draw.io-Exporte für Rack- und Topologieansichten.
10. Anpassungen für die Verwendung mit NetBox 4.6, darunter die geänderte
`Rack.units`-Property.
## Vorschau
Die klassische Topologieansicht stammt aus dem ursprünglichen Plugin:
1. New menu category **More views**.
2. A rack view with filters for site, location and multiple racks.
3. Position-accurate rack elevations for front and rear.
4. A cable table with A and B terminations.
5. An interactive, movable cable topology below the racks.
6. Hover highlighting and port-to-port tracing for devices and cables.
7. Locally stored device positions and a reset function.
8. An extended, scalable SVG icon set for switch roles.
9. Transparent SVG, PNG and draw.io exports for rack and topology views.
10. Adjustments for NetBox 4.6+, including the changed `Rack.units` property.
![Topology in light mode](doc/img/topology_light.png)
![Topology in dark mode](doc/img/topology_dark.png)
## Installation aus Gitea
## Compatibility
Das Plugin kann direkt aus dem `develop`-Branch installiert werden:
- NetBox `4.7.x` (`min_version`/`max_version` in `netbox_topology_views/__init__.py`)
- Based on NetBox Topology Views `4.5.1`
Since the upstream release officially targets NetBox 4.5.x, test updates to
newer NetBox versions in a staging instance first.
## Installation
All paths assume a standard installation under `/opt/netbox`.
### 1. Install the package
```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop"
```
Für eine reproduzierbare Produktivinstallation sollte statt `develop` ein
Release-Tag oder ein bestimmter Commit verwendet werden:
For reproducible production installs, replace `develop` with a release tag or a
full commit ID.
### 2. Add the plugin to `local_requirements.txt`
This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade:
```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@v4.5.1-mrb.1"
grep -qxF "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" /opt/netbox/local_requirements.txt \
|| echo "git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop" | sudo tee -a /opt/netbox/local_requirements.txt
```
Für automatische Neuinstallationen bei einem NetBox-Upgrade wird derselbe
Eintrag in `/opt/netbox/local_requirements.txt` hinterlegt:
If the repository is private, the NetBox server needs a read-only deploy token
or an SSH key. Do not store credentials in `local_requirements.txt`.
```text
git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop
```
### 3. Enable the plugin
Bei einem privaten Gitea-Repository muss der NetBox-Server Zugriff über einen
Deploy-Token oder SSH-Key erhalten.
## NetBox-Konfiguration
In `netbox/configuration.py` wird das Python-Paket aktiviert:
In `/opt/netbox/netbox/netbox/configuration.py`:
```python
PLUGINS = [
@@ -102,135 +105,126 @@ PLUGINS_CONFIG = {
}
```
Danach werden Migrationen und statische Dateien verarbeitet:
If other plugins are already configured, add `netbox_topology_views` to the
existing list and dictionary instead of replacing them.
### 4. Apply migrations, collect static files, restart
```bash
cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate
/opt/netbox/venv/bin/python manage.py migrate netbox_topology_views
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
```
Nach Änderungen an CSS oder Icons kann ein Hard-Reload des Browsers mit
`Strg+F5` erforderlich sein.
After changes to CSS or icons a hard reload in the browser (`Ctrl+F5`) may be
necessary.
## Aktualisierung
## Update
```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/mrb-netbox-topology-views.git@develop"
cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate
/opt/netbox/venv/bin/python manage.py migrate netbox_topology_views
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
```
`--force-reinstall` ist derzeit sinnvoll, da der Fork intern noch die
Paketversion `4.5.2` verwendet.
`--force-reinstall` is required because the fork still uses the internal
package version `4.5.2`.
## Verwendung
When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from
`local_requirements.txt` and runs migrations and `collectstatic`:
### Klassische Topologie
```bash
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
```
Unter **Plugins → Topology Views → Topology** steht die ursprüngliche,
filterbare Topologieansicht zur Verfügung. Sie unterstützt unter anderem:
## Uninstall
- physische Kabel
- logische Verbindungen
- Nachbargeräte
- Circuit-Terminations
- Power Feeds
- Wireless Links
- Coordinate Groups
- PNG- und XML-Export
1. Remove `"netbox_topology_views"` from `PLUGINS` and `PLUGINS_CONFIG`.
2. Remove the line from `/opt/netbox/local_requirements.txt`.
3. Uninstall the package and restart NetBox:
### Rack-Ansicht
```bash
/opt/netbox/venv/bin/pip uninstall netbox-topology-views
sudo systemctl restart netbox netbox-rq
```
Die erweiterte Ansicht befindet sich unter:
## Usage
**Plugins → Topology Views → Weitere Ansichten → Rack-Ansicht**
### Classic topology
Über Site, Location und Rack können ein einzelnes Rack oder mehrere Racks
ausgewählt werden. Optional lassen sich auch leere Racks einblenden.
**Plugins → Topology Views → Topology** provides the original, filterable
topology view. It supports physical cables, logical connections, neighbour
devices, circuit terminations, power feeds, wireless links, coordinate groups,
and PNG and XML export.
In der Elevation werden Geräte entsprechend ihrer Position, Gerätehöhe und
Rack-Seite dargestellt. Unter den Elevations folgen:
### Rack view
1. die interaktive Kabeltopologie und
2. eine tabellarische Übersicht sämtlicher betroffener Kabel.
**Plugins → Topology Views → More views → Rack view**
In der Kabeltopologie können Geräte per Drag-and-drop verschoben werden. Beim
Hover über ein Gerät werden dessen Kabel hervorgehoben und alle verbundenen
Ports aufgelistet. Beim Hover über ein Kabel erscheinen beide Terminierungen.
Ein Klick öffnet das jeweilige NetBox-Objekt.
Select a single rack or several racks via site, location and rack; empty racks
can be shown optionally. Devices are rendered according to position, height and
rack face. Below the elevations follow:
Über die Export-Schaltflächen können ein einzelnes Rack, alle aktuell
angezeigten Racks oder die interaktive Kabeltopologie als SVG, PNG oder
draw.io-Datei gespeichert werden. Sämtliche Exportformate werden ohne
Hintergrundfläche erzeugt. Im draw.io-Export bleiben Rack-Rahmen, Geräte und
Beschriftungen als einzelne Elemente bearbeitbar. Topologiekabel werden als
echte Kanten exportiert und folgen den Geräten beim Verschieben in draw.io.
1. the interactive cable topology, and
2. a table of all involved cables.
Die Positionen werden im `localStorage` des Browsers gespeichert. Sie gelten
damit nur für den jeweiligen Browser und die konkrete Rack-/Filterauswahl.
In the cable topology, devices can be moved via drag and drop. Hovering a device
highlights its cables and lists all connected ports; hovering a cable shows both
terminations. A click opens the NetBox object.
## Geräte-Icons
The export buttons save a single rack, all displayed racks or the cable topology
as SVG, PNG or draw.io, always without background. In the draw.io export, rack
frames, devices and labels remain individually editable, and topology cables are
real edges that follow the devices.
Das Plugin ordnet Icons anhand des Slugs einer Device Role zu. Dieser Fork
liefert zusätzlich folgende SVG-Dateien aus:
Positions are stored in the browser's `localStorage` and apply only to that
browser and the specific rack/filter selection.
| Device-Role-Slug | Icon-Datei |
With [Netbox-Utilities](https://git.mrblake.cc/MrBlake/Netbox-Utilities)
installed, partial-width devices are rendered side by side in the rack view.
## Device icons
Icons are assigned by device role slug. This fork additionally ships:
| Device role slug | Icon file |
| --- | --- |
| `network-switch` | `network-switch.svg` |
| `leaf-switch` | `leaf-switch.svg` |
| `spine-switch` | `spine-switch.svg` |
| `aggregation-switch` | `aggregation-switch.svg` |
Eigene Bilder können weiterhin über die Seite **Images** zugeordnet werden.
Der Standardpfad lautet `netbox_topology_views/img` innerhalb von
`STATIC_ROOT`.
Custom images can still be assigned on the **Images** page. The default path is
`netbox_topology_views/img` within `STATIC_ROOT`.
## Berechtigungen
## Permissions
Für die klassische Topologie werden mindestens folgende Rechte benötigt:
Classic topology: `dcim.view_site`, `dcim.view_device`.
- `dcim.view_site`
- `dcim.view_device`
Rack view: `dcim.view_rack`, `dcim.view_device`, `dcim.view_cable`.
Für die Rack-Ansicht werden benötigt:
Saving classic topology coordinates additionally requires the corresponding
permissions on `netbox_topology_views.coordinate`.
- `dcim.view_rack`
- `dcim.view_device`
- `dcim.view_cable`
## Origin and credits
Für das Speichern klassischer Topologiekoordinaten werden zusätzlich die
entsprechenden Rechte auf `netbox_topology_views.coordinate` benötigt.
## Kompatibilität
Die Basis dieses Forks ist NetBox Topology Views `4.5.1`. Die neuen
Rack-Funktionen wurden für den Einsatz mit NetBox `4.6.5` angepasst und das
Plugin ist für NetBox `4.7.x` (`min_version`/`max_version` in
`netbox_topology_views/__init__.py`) freigegeben. Da das ursprüngliche
Release offiziell für NetBox 4.5.x ausgewiesen ist, sollten Updates auf
neuere NetBox-Versionen zunächst in einer Testumgebung geprüft werden.
## Ursprung und Danksagung
Dieses Projekt ist ein Fork des Open-Source-Plugins
This project is a fork of the open-source plugin
[NetBox Topology Views](https://github.com/mattieserver/netbox-topology-views).
The original plugin was created by **Mattijs Vanhaverbeke**. Most of the classic
topology view, data models, filters and export functions are based on his work
and the contributions to the original project.
Das ursprüngliche Plugin wurde von **Mattijs Vanhaverbeke** erstellt. Der
größte Teil der klassischen Topologieansicht, Datenmodelle, Filter und
Exportfunktionen basiert auf seiner Arbeit und den Beiträgen des ursprünglichen
Projekts.
This fork is developed independently and is not officially affiliated with the
original author or the NetBox project.
Dieser Fork wird unabhängig weiterentwickelt und ist nicht mit dem
ursprünglichen Autor oder dem NetBox-Projekt offiziell verbunden.
## License
## Lizenz
Das Projekt steht wie das Original unter der
[Apache License 2.0](LICENSE). Bestehende Copyright-, Lizenz- und
Urheberhinweise des ursprünglichen Projekts bleiben erhalten.
Like the original, this project is licensed under the
[Apache License 2.0](LICENSE). Existing copyright, license and attribution
notices of the original project are retained.