MrBlake/NetBox-Export
1
0
Fork 0
Code Issues Pull Requests Actions 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:36:42 +02:00
co-authored by Claude Opus 5.5
parent 47e9192fda
commit 9a1e702099
1 changed files with 161 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+161 -112
View File
@@ -1,37 +1,68 @@
# NetBox-Export
NetBox-Export ist ein Plugin für NetBox 4.6.x und 4.7.x. Es exportiert einen abgegrenzten
Mandanten- oder Standortbereich als portables ZIP-Archiv und importiert ihn in
eine zweite NetBox-Instanz.
Export a scoped tenant or site area as a portable ZIP archive and import it into
a second NetBox instance.
Unterstützte Startpunkte:
| | |
|---|---|
| **Plugin name** | `netbox_export` |
| **Package** | `netbox-export` |
| **NetBox** | `4.6.0` – `4.7.x` |
| **Python** | `>=3.12` |
| **Repository** | <https://git.mrblake.cc/MrBlake/NetBox-Export> |
- Mandantengruppe einschließlich Untergruppen und Mandanten
- einzelner Mandant
- Region einschließlich Unterregionen und Standorten
- einzelner Standort
- Lokation einschließlich Unterlokationen
## Features
Der Export folgt den Besitzbeziehungen zu DCIM-, IPAM-, Circuit-,
Virtualisierungs-, VPN-, Wireless-, Kontakt-, Tag- und Bilddaten. Benötigte
Stammdaten werden als Abhängigkeiten mitgenommen. Primärschlüssel der
Quellinstanz werden nie direkt als Zielschlüssel verwendet.
Supported starting points:
- tenant group including sub-groups and tenants
- single tenant
- region including sub-regions and sites
- single site
- location including sub-locations
The export follows ownership relations to DCIM, IPAM, circuit, virtualisation,
VPN, wireless, contact, tag and image data. Required master data is included as
dependencies. Primary keys of the source instance are never used directly as
target keys.
## Compatibility
- NetBox `4.6.0` – `4.7.x`
- Python `>=3.12`
- Source and target must run the same NetBox version and the same plugins,
plugin versions and migrations.
## Installation
Das Plugin muss auf beiden NetBox-Instanzen installiert sein.
The plugin must be installed on **both** NetBox instances. All paths assume a
standard installation under `/opt/netbox`.
### 1. Install the package
```bash
cd /opt/netbox
source venv/bin/activate
pip install --upgrade --force-reinstall \
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
# Prüfen, ob das Modul im NetBox-venv verfügbar ist
python -c "import netbox_export; print(netbox_export.__file__)"
```
In `configuration.py` ergänzen:
For reproducible production installs, replace `main` 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
grep -qxF "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main" /opt/netbox/local_requirements.txt \
|| echo "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main" | sudo tee -a /opt/netbox/local_requirements.txt
```
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`.
### 3. Enable the plugin
In `/opt/netbox/netbox/netbox/configuration.py`:
```python
PLUGINS = [
@@ -43,122 +74,140 @@ PLUGINS_CONFIG = {
"max_objects": 50000,
"max_archive_size_mb": 250,
"query_batch_size": 500,
# Auf beiden Instanzen identisch setzen, um Archive zu signieren.
"archive_signing_key": "eine-lange-zufaellige-geheime-zeichenfolge",
# Set identically on both instances to sign archives.
"archive_signing_key": "a-long-random-secret-string",
},
}
```
Anschließend:
If other plugins are already configured, add `netbox_export` to the existing
list and dictionary instead of replacing them.
### 4. Apply migrations, collect static files, restart
```bash
cd /opt/netbox/netbox
python manage.py migrate netbox_export
python manage.py collectstatic --no-input
/opt/netbox/venv/bin/python manage.py migrate netbox_export
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
```
Falls `ModuleNotFoundError: No module named 'netbox_export'` erscheint, wurde
das Paket nicht in `/opt/netbox/venv` installiert. In diesem Fall den obigen
Installationsblock erneut ausführen und darauf achten, dass
`/opt/netbox/venv/bin/python` verwendet wird:
If `ModuleNotFoundError: No module named 'netbox_export'` appears, the package
was not installed into `/opt/netbox/venv`. Check with:
```bash
/opt/netbox/venv/bin/python -m pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
/opt/netbox/venv/bin/python -c \
"import netbox_export; print(netbox_export.__file__)"
/opt/netbox/venv/bin/python -c "import netbox_export; print(netbox_export.__file__)"
```
Bei einer Docker-Installation wird das Paket in das eigene NetBox-Image
aufgenommen; danach wird der Container mit dem aktivierten Plugin neu gebaut und
die Migration ausgeführt.
For Docker installations, add the package to your NetBox image, rebuild the
container with the plugin enabled and run the migration.
## Verwendung
## Update
Die Oberfläche liegt unter **Plugins > NetBox-Export > Export / Import** und ist
aus Sicherheitsgründen nur für Superuser sichtbar.
```bash
/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
"git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
1. Auf Instanz A den Typ und das konkrete Objekt wählen und das ZIP exportieren.
2. Auf Instanz B das ZIP zunächst mit **Nur prüfen** verarbeiten.
3. Nach erfolgreichem Prüflauf **Nur prüfen** deaktivieren, den schreibenden
Import bestätigen und das Archiv erneut hochladen.
cd /opt/netbox/netbox
/opt/netbox/venv/bin/python manage.py migrate netbox_export
/opt/netbox/venv/bin/python manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq
```
Der Import läuft atomar. Bei einem Fehler werden alle Datenbankänderungen
zurückgerollt. Die Konfliktstrategie **Aktualisieren** nutzt zuerst die dauerhaft
gespeicherte Zuordnung aus Quellinstanz, Modell und Quell-ID; bei einem ersten
Import werden vorhandene Objekte über ihre eindeutigen Fachschlüssel erkannt.
`--force-reinstall` makes pip pick up branch changes even if the package
version has not been bumped. Update source and target instance together.
## Verhalten und Grenzen
When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from
`local_requirements.txt` and runs migrations and `collectstatic`:
- Quelle und Ziel müssen dieselbe unterstützte NetBox-Version (4.6.x oder 4.7.x) und dieselben Plugins/Modelle verwenden.
- Benutzerkonten und Berechtigungen werden nicht exportiert. Fehlende oder
nicht eindeutige Referenzen auf Benutzer und Gruppen werden ausgelassen und
nach dem Import als Warnung angezeigt. Benötigt ein neuer Datensatz zwingend
eine solche Referenz, wird nur dieser Datensatz übersprungen.
- Der Import erstellt und aktualisiert Objekte. Zielobjekte, die im Archiv nicht
vorkommen, werden bewusst nicht gelöscht.
- Fehlende Bilddateien werden im Archiv vermerkt, können aber nicht rekonstruiert
werden.
- Große Exporte werden synchron verarbeitet. `max_objects` begrenzt Laufzeit und
Speicherverbrauch.
- `query_batch_size` steuert die Größe gebündelter Datenbankabfragen. Der
Standardwert `500` ist für typische PostgreSQL-Installationen geeignet;
Werte zwischen `250` und `1000` erlauben eine Anpassung an Arbeitsspeicher und
Datenbankleistung.
```bash
sudo /opt/netbox/upgrade.sh
sudo systemctl restart netbox netbox-rq
```
## Plugin-Kompatibilität
## Uninstall
Der Exportgraph berücksichtigt installierte, mandantenbezogene Modelle und
Dateien aus NetBox-SLM, Netbox-DokiWiki und NetBox-VM-Import. Private oder
temporäre Plugin-Modelle werden nicht exportiert. Die von Netbox-Utilities
erzwungene Mandantenpflicht wird beim Import berücksichtigt: Das Zielobjekt wird
erst gespeichert, nachdem sein Mandant importiert und zugeordnet wurde. Ist kein
Mandant auflösbar, wird automatisch ein vorhandener Mandant `Auto-Import`
verwendet oder neu angelegt. Der Importbericht weist darauf hin.
Beziehungen, die Teil einer Plugin-Datenbankprüfung sind, werden vollständig
aufgelöst, bevor das Objekt erstmals gespeichert wird. Dies betrifft unter
anderem die Plattformzuordnung von NetBox-SLM-Softwareinstallationen.
Eindeutige optionale Beziehungen wie die primären IP-Adressen von Geräten und
virtuellen Maschinen werden in einer zweiten Phase zugewiesen. Eine veraltete
Zielzuordnung wird dabei atomar gelöst und als Warnung protokolliert.
Gespeicherte Importzuordnungen werden bei Wiederholungsimporten gegen den
aktuellen Fachschlüssel geprüft. Existiert das Objekt bereits unter diesem
Schlüssel, wird die Zuordnung korrigiert, statt ein Duplikat anzulegen.
Bei neuen NetBox-Modulen wird die automatische Komponentenreplikation
deaktiviert. Ports, Interfaces und Bays werden stattdessen ausschließlich aus
den Archivdatensätzen angelegt beziehungsweise vorhandenen Komponenten
zugeordnet.
Geräte werden in einer separaten Abschlussphase im Rack platziert, damit auch
Positionswechsel ohne temporäre Doppelbelegung funktionieren. Bei fremden
Belegungen löst **Aktualisieren** das Zielgerät mit Warnung von seiner Position,
**Überspringen** lässt das importierte Gerät positionslos und **Import abbrechen**
meldet den Rackplatzkonflikt vor dem Datenbankfehler. Mehr-U- und
Full-Depth-Belegungen werden dabei berücksichtigt.
Front-/Rear-Port-Zuordnungen von Patchpanels werden als eigene Datensätze
exportiert und bei **Aktualisieren** auf den Stand der Quelle gebracht. Nach dem
Import stößt das Plugin für alle enthaltenen Kabel die NetBox-eigene
Neuberechnung der Kabelpfade an. Für diese Korrektur muss mit Plugin-Version
`0.3.12` oder neuer ein neues Archiv auf der Quellinstanz erzeugt werden, da
ältere Archive keine Portzuordnungen enthalten.
PostgreSQL-Range-Felder, darunter die erlaubten VLAN-ID-Bereiche einer
VLAN-Gruppe, werden typisiert im Archiv gespeichert. Der Import erkennt auch
die von älteren Plugin-Versionen als Text exportierten Range-Werte.
Bei Bildanhängen werden Breite und Höhe direkt aus der Bilddatei im Archiv
ermittelt. Dadurch sind die Pflichtfelder von NetBox auch im Prüflauf und bei
Dateispeichern ohne unmittelbaren Modell-Save gesetzt. Bilder oberhalb des von
NetBox verwendeten Limits von 25 Millionen Pixeln werden proportional auf
höchstens 20 Millionen Pixel verkleinert und im Importbericht als Warnung
ausgewiesen. Zum Schutz des Importprozesses bleibt eine harte Quellgrenze von
100 Millionen Pixeln bestehen.
1. Remove `"netbox_export"` from `PLUGINS` and `PLUGINS_CONFIG`.
2. Remove the line from `/opt/netbox/local_requirements.txt`.
3. Uninstall the package and restart NetBox:
Auf Quelle und Ziel müssen jeweils dieselben Plugin-Versionen und Migrationen
installiert sein. Verschlüsselte Zugangsdaten von NetBox-VM-Import sind nur bei
identischem Django-`SECRET_KEY` direkt nutzbar; andernfalls muss das Kennwort am
Ziel neu gesetzt werden.
```bash
/opt/netbox/venv/bin/pip uninstall netbox-export
sudo systemctl restart netbox netbox-rq
```
## Tests
## Configuration
| Key | Default | Description |
|---|---|---|
| `max_objects` | `50000` | Upper limit of objects per export (runtime and memory) |
| `max_archive_size_mb` | `250` | Maximum archive size |
| `query_batch_size` | `500` | Size of batched database queries; `250`–`1000` is reasonable |
| `archive_signing_key` | – | Shared secret to sign archives; must be identical on both instances |
## Usage
The UI is located under **Plugins > NetBox-Export > Export / Import** and, for
security reasons, is only visible to superusers.
1. On instance A, choose the type and the specific object and export the ZIP.
2. On instance B, first process the ZIP with **Dry run only**.
3. After a successful dry run, disable **Dry run only**, confirm the writing
import and upload the archive again.
The import is atomic: on error, all database changes are rolled back. The
conflict strategy **Update** first uses the stored mapping of source instance,
model and source ID; on a first import, existing objects are matched by their
unique natural keys.
### Behaviour and limits
- User accounts and permissions are not exported. Missing or ambiguous user and
group references are omitted and reported as warnings; if a new record
strictly requires such a reference, only that record is skipped.
- The import creates and updates objects. Target objects not contained in the
archive are intentionally **not** deleted.
- Missing image files are noted in the archive but cannot be reconstructed.
- Large exports are processed synchronously; `max_objects` limits runtime and memory.
### Plugin compatibility
- Tenant-related models and files of NetBox-SLM, Netbox-Documentation and
NetBox-VM-Import are included. Private or temporary plugin models are not exported.
- The mandatory tenant assignment of Netbox-Utilities is respected: an object is
only saved after its tenant has been imported. If no tenant can be resolved,
an existing tenant `Auto-Import` is used or created, and the import report
says so.
- Relations checked by plugin database constraints (e.g. the platform of
NetBox-SLM software installations) are resolved before the first save.
- Unique optional relations such as primary IPs of devices and VMs are assigned
in a second phase; stale target assignments are released atomically and logged.
- Stored import mappings are validated against the current natural key on
repeated imports, correcting the mapping instead of creating duplicates.
- Automatic component replication is disabled for new modules; ports,
interfaces and bays are created solely from archive records.
- Devices are placed in racks in a separate final phase so position swaps work
without temporary double occupancy. For foreign occupants, **Update** releases
the target device with a warning, **Skip** leaves the imported device without
a position, and **Abort import** reports the rack conflict. Multi-U and
full-depth occupancy are considered.
- Front/rear port mappings of patch panels are exported as separate records and
synced on **Update**; cable paths are recalculated after import. This requires
an archive created with version `0.3.12` or newer.
- PostgreSQL range fields (e.g. VLAN ID ranges of VLAN groups) are stored typed;
text values from older versions are still recognised.
- Image width and height are read from the archived file. Images above NetBox's
25-megapixel limit are scaled down to at most 20 megapixels with a warning; a
hard source limit of 100 megapixels applies.
- Encrypted credentials of NetBox-VM-Import are only usable with an identical
Django `SECRET_KEY`; otherwise set the password again on the target.
## Development and tests
```bash
python -m pytest
```
## License
Apache License 2.0 — see [LICENSE](LICENSE).