NetTransfare/README.md

NetBox Backup, Restore & Upgrade Tool

Ein interaktives Python-Werkzeug zur Sicherung, Wiederherstellung und Aktualisierung einer NetBox-Installation unter Linux.

Das Skript kombiniert folgende Aufgaben in einer einfachen Terminal-Oberfläche:

• PostgreSQL-Datenbank sichern
• NetBox-Media-Dateien sichern
• Backups als ZIP-Datei speichern
• Datenbank und Media-Dateien wiederherstellen
• Neue NetBox-Releases herunterladen und installieren
• Konfiguration, LDAP-Einstellungen, Plugins, Media-Dateien, Reports und Custom Scripts übernehmen
• NetBox-Dienste stoppen, starten und überprüfen
• Die bisherige Installation für einen möglichen Rollback aufbewahren

Important

Dieses Projekt ist kein offizielles Werkzeug des NetBox-Projekts. Teste Backup, Restore und Upgrade zuerst auf einer Testinstanz. Ein aktuelles, extern gespeichertes Backup sollte vor jedem Upgrade vorhanden sein.

---

Inhaltsverzeichnis

1. Voraussetzungen
2. Installation
3. Schnellstart
4. Konfiguration
5. Backup erstellen
6. Backup wiederherstellen
7. NetBox upgraden
8. Übernommene Dateien und Verzeichnisse
9. Plugins und LDAP
10. CSRF Trusted Origins
11. Rollback-Verhalten
12. Backup-Aufbau
13. Troubleshooting
14. Sicherheitshinweise
15. Bekannte Einschränkungen

---

Voraussetzungen

Betriebssystem

Das Tool ist für eine klassische NetBox-Installation unter Linux vorgesehen. Die Upgrade-Funktion benötigt:

• Linux beziehungsweise ein POSIX-System
• systemd
• Root-Rechte
• Schreibzugriff auf /opt
• Internetzugriff auf GitHub

Python

• Python 3.8 oder neuer empfohlen
• Es werden ausschließlich Module aus der Python-Standardbibliothek verwendet
• Zusätzliche Python-Pakete sind für das Tool selbst nicht erforderlich

Systemprogramme

Folgende Programme müssen verfügbar sein:

Programm	Verwendung
pg_dump	PostgreSQL-Datenbank sichern
pg_restore	PostgreSQL-Dump wiederherstellen
dropdb	Vorhandene Zieldatenbank beim Restore löschen
createdb	Zieldatenbank neu erstellen
systemctl	NetBox-Dienste stoppen und starten
cp	Konfiguration und lokale Daten beim Upgrade übernehmen
chown	Eigentümer der wiederhergestellten Media-Dateien setzen
git	Optional zur Erkennung der installierten NetBox-Version

Unter Debian oder Ubuntu können die PostgreSQL-Clientprogramme beispielsweise über das Paket postgresql-client bereitgestellt werden.

NetBox-Verzeichnisstruktur

Standardmäßig erwartet das Tool NetBox unter:

/opt/netbox

Dabei werden unter anderem folgende Pfade erwartet:

/opt/netbox/upgrade.sh
/opt/netbox/netbox/netbox/configuration.py
/opt/netbox/netbox/media/

/opt/netbox darf entweder ein normales Verzeichnis oder ein Symlink auf ein versionsbezogenes Verzeichnis sein.

NetBox-Dienste

Das Skript verwendet standardmäßig diese Service-Namen:

netbox
netbox-rq

Bei abweichenden Unit-Namen muss die Konstante NETBOX_SERVICES im Skript angepasst werden.

---

Installation

Skript nach /usr/local/sbin oder in ein anderes geeignetes Verzeichnis kopieren:

sudo cp netbox_backup_restore_upgrade.py /usr/local/sbin/netbox-tool
sudo chmod 750 /usr/local/sbin/netbox-tool
sudo chown root:root /usr/local/sbin/netbox-tool

Anschließend starten:

sudo /usr/local/sbin/netbox-tool

Alternativ direkt aus dem aktuellen Ordner:

chmod +x netbox_backup_restore_upgrade.py
sudo ./netbox_backup_restore_upgrade.py

Optional kann vorab die Python-Syntax geprüft werden:

python3 -m py_compile netbox_backup_restore_upgrade.py

---

Schnellstart

Nach dem Start erscheint das Hauptmenü:

============================================================
   NETBOX BACKUP, RESTORE & UPGRADE TOOL
============================================================

  1. Backup erstellen
  2. Backup wiederherstellen
  3. NetBox upgraden
  4. Einstellungen prüfen / anpassen
  5. Beenden

Empfohlene Reihenfolge vor einem Upgrade:

1. Einstellungen kontrollieren.
2. Vollständiges Datenbank- und Media-Backup erstellen.
3. Backup-Datei auf ein anderes System kopieren.
4. Release Notes der Zielversion lesen.
5. Plugin-Kompatibilität prüfen.
6. Upgrade starten.
7. Weboberfläche, Worker, Plugins und Logs kontrollieren.

---

Konfiguration

Die Standardwerte befinden sich am Anfang des Skripts:

CONFIG = {
    "netbox_path": "/opt/netbox",
    "db_host": "localhost",
    "db_name": "netbox",
    "db_user": "netbox",
    "db_pass": "",
    "backup_dir": "/tmp",
    "python_path": "",
}

Konfigurationswerte

Schlüssel	Beschreibung	Standard
netbox_path	Aktiver NetBox-Installationspfad	/opt/netbox
db_host	PostgreSQL-Server	localhost
db_name	Name der NetBox-Datenbank	netbox
db_user	PostgreSQL-Benutzer	netbox
db_pass	PostgreSQL-Passwort	leer
backup_dir	Ziel für Backups und temporäre Archive	/tmp
python_path	Optionaler Python-Interpreter für upgrade.sh	leer

Python-Version für das Upgrade festlegen

Normalerweise verwendet upgrade.sh den passenden Standardinterpreter. Falls eine bestimmte Python-Version benötigt wird, kann sie angegeben werden:

"python_path": "/usr/bin/python3.12",

Das Skript setzt dann beim Aufruf von upgrade.sh die Umgebungsvariable PYTHON.

Datenbankpasswort

Ist db_pass gesetzt, wird es für PostgreSQL-Befehle über die Umgebungsvariable PGPASSWORD bereitgestellt.

Aus Sicherheitsgründen ist eine PostgreSQL-Passwortdatei häufig besser geeignet:

/root/.pgpass

Beispiel:

localhost:5432:netbox:netbox:MEIN_PASSWORT

Berechtigungen setzen:

chmod 600 /root/.pgpass

Danach kann db_pass im Skript leer bleiben.

Note

Änderungen über das Menü Einstellungen prüfen / anpassen gelten nur für den aktuell laufenden Prozess. Sie werden nicht dauerhaft in einer Datei gespeichert. Für dauerhafte Änderungen muss der CONFIG-Block im Skript angepasst werden.

---

Backup erstellen

Im Hauptmenü auswählen:

1. Backup erstellen

Auswahlmöglichkeiten

Das Tool fragt, ob folgende Komponenten gesichert werden sollen:

• PostgreSQL-Datenbank
• Media-Dateien

Beim Datenbank-Backup können zusätzlich Daten bestimmter Tabellen ausgelassen werden.

Changelog auslassen

Bei Auswahl dieser Option wird der Inhalt der Tabelle extras_objectchange nicht exportiert:

Changelog (extras_objectchange) auslassen? Spart viel Platz. (j/N)

Die Tabellenstruktur bleibt im Dump erhalten. Nur die darin gespeicherten Daten werden übersprungen.

Diese Option kann die Backup-Größe deutlich reduzieren, wenn die Änderungsprotokollierung sehr umfangreich ist.

Benutzer auslassen

Folgende Tabelleninhalte werden dabei nicht exportiert:

auth_user
auth_group
users_token

Warning

Das Auslassen von Benutzern kann beim Restore zu Fremdschlüsselproblemen oder fehlenden Zuordnungen führen. Verwende diese Option nur, wenn das Zielsystem bereits passende Benutzer besitzt oder du die Folgen genau kennst.

Backup-Datei

Die Datei wird nach folgendem Schema erzeugt:

netbox_backup_YYYYMMDD_HHMMSS.zip

Beispiel:

/tmp/netbox_backup_20260720_143500.zip

Nach erfolgreicher Erstellung zeigt das Tool den vollständigen Pfad an.

Backup anschließend prüfen

Datei anzeigen:

ls -lh /tmp/netbox_backup_*.zip

ZIP-Inhalt prüfen:

unzip -l /tmp/netbox_backup_20260720_143500.zip

Prüfsumme erzeugen:

sha256sum /tmp/netbox_backup_20260720_143500.zip

Backup auf einen externen Speicher kopieren:

scp /tmp/netbox_backup_20260720_143500.zip backupserver:/srv/backups/netbox/

Ein Backup sollte nicht ausschließlich unter /tmp verbleiben. Je nach Systemkonfiguration kann dieses Verzeichnis beim Neustart geleert werden.

---

Backup wiederherstellen

Im Hauptmenü auswählen:

2. Backup wiederherstellen

Caution

Der Restore überschreibt die vorhandenen Daten der Zielinstanz. Die konfigurierte PostgreSQL-Datenbank wird gelöscht und neu erstellt.

Ablauf

1. Sicherheitsabfrage bestätigen.
2. Vollständigen Pfad zur ZIP-Datei eingeben.
3. Das Archiv wird in ein temporäres Verzeichnis entpackt.
4. metadata.json wird geprüft.
5. Falls enthalten, wird die Datenbank gelöscht und neu erstellt.
6. Der PostgreSQL-Dump wird importiert.
7. Falls enthalten, werden Media-Dateien ersetzt.
8. upgrade.sh wird ausgeführt.
9. netbox und netbox-rq werden neu gestartet.

Benötigte Datenbankrechte

Der konfigurierte Datenbankbenutzer muss für den Restore ausreichende Rechte besitzen. Insbesondere müssen dropdb und createdb mit diesem Benutzer funktionieren.

Test:

sudo -u postgres psql -c "\du"

Falls der NetBox-Datenbankbenutzer keine Datenbanken erstellen darf, muss der Ablauf angepasst oder ein administrativer PostgreSQL-Benutzer verwendet werden.

Restore-Befehl im Hintergrund

Der Dump wird sinngemäß so importiert:

pg_restore \
  -h localhost \
  -U netbox \
  -d netbox \
  --clean \
  --no-owner \
  netbox_database.dump

Meldungen von pg_restore werden angezeigt. Da PostgreSQL auch bei einzelnen Warnungen einen Rückgabecode ungleich null liefern kann, meldet das Tool den Restore als abgeschlossen und gibt vorhandene Hinweise aus. Kontrolliere anschließend die Datenbank und die NetBox-Logs.

Media-Dateien

Vorhandene Media-Dateien unter folgendem Pfad werden ersetzt:

/opt/netbox/netbox/media

Danach setzt das Tool den Eigentümer auf:

netbox:netbox

---

NetBox upgraden

Im Hauptmenü auswählen:

3. NetBox upgraden

Die Upgrade-Funktion muss als root oder mit sudo ausgeführt werden.

Zielversion

Die Version kann mit oder ohne vorangestelltes v eingegeben werden:

4.6.5

oder:

v4.6.5

Akzeptiert werden ausschließlich stabile Versionsnummern im Format:

X.Y.Z

Pre-Releases wie 4.6.0-beta1 werden nicht akzeptiert.

Versionsprüfung

Das Tool versucht die installierte NetBox-Version über mehrere Methoden zu erkennen:

• Name des tatsächlichen Installationsverzeichnisses
• exaktes Git-Tag
• NetBox-Python-Paket im vorhandenen virtuellen Environment
• NetBox-Versionsdateien

Die Zielversion muss höher als die erkannte installierte Version sein. Downgrades werden nicht automatisiert.

Bei einem erkannten Major-Sprung gibt das Tool eine zusätzliche Warnung aus.

Upgrade-Ablauf

Das Tool führt folgende Schritte durch:

1. Zielversion validieren.
2. Bestehende NetBox-Installation prüfen.
3. Bestätigung für Backup und Release Notes verlangen.
4. Optional die vorkonfigurierten Plugins ergänzen.
5. LDAP-Konfiguration erkennen.
6. CSRF_TRUSTED_ORIGINS prüfen oder ergänzen.
7. Release-Archiv von GitHub herunterladen.
8. TAR-Archiv sicher entpacken und prüfen.
9. Lokale Dateien und Verzeichnisse übernehmen.
10. Dienste stoppen.
11. Installationsverzeichnisse beziehungsweise Symlink umschalten.
12. /opt/netbox/upgrade.sh ausführen.
13. Dienste neu starten.
14. Dienststatus prüfen.
15. Alte Installation als Rückfalloption behalten.

Download-Adresse

Das Release wird nach diesem Schema geladen:

https://github.com/netbox-community/netbox/archive/refs/tags/vX.Y.Z.tar.gz

Das temporäre Archiv wird nach dem Upgrade wieder gelöscht.

Downtime

Download, Entpacken und die Vorbereitung der neuen Installation erfolgen vor dem Stoppen der Dienste. Die eigentliche Downtime beginnt erst bei der Umschaltung auf die neue Installation.

Dienste

Vor der Umschaltung werden folgende Dienste gestoppt:

netbox
netbox-rq

Nach erfolgreichem upgrade.sh werden beide Dienste neu gestartet und mit systemctl is-active geprüft.

---

Übernommene Dateien und Verzeichnisse

Beim Upgrade werden folgende Inhalte aus der bestehenden Installation in das neue Release kopiert.

Pflichtdatei

netbox/netbox/configuration.py

Fehlt diese Datei, wird das Upgrade abgebrochen.

Optionale Dateien

netbox/netbox/ldap_config.py
local_requirements.txt
gunicorn.py

Fehlende optionale Dateien führen nicht zum Abbruch.

Optionale Verzeichnisse

netbox/media/
netbox/scripts/
netbox/reports/

Die Inhalte werden unter Erhaltung von Rechten, Zeitstempeln und symbolischen Eigenschaften mit cp -a kopiert.

Nicht automatisch übernommene Anpassungen

Manuelle Änderungen an Dateien aus dem eigentlichen NetBox-Quellcode werden nicht automatisch erkannt oder zusammengeführt. Dazu zählen beispielsweise direkt modifizierte Templates, Python-Dateien oder statische Dateien außerhalb der oben genannten Pfade.

Solche Änderungen sollten als Plugin, Custom Script oder über einen dokumentierten Deployment-Prozess umgesetzt werden.

---

Plugins und LDAP

Vorhandene Requirements

Eine bestehende Datei wird übernommen:

/opt/netbox/local_requirements.txt

Vorhandene Einträge bleiben erhalten. Das Tool versucht Paketnamen zu erkennen und fügt ein Paket nicht erneut hinzu, wenn bereits ein unversionierter oder gepinnter Eintrag existiert.

Beispiele, die als dasselbe Paket erkannt werden:

netbox-topology-views
netbox-topology-views==4.2.1
netbox_topology_views>=4.0

Vorkonfigurierte Plugins

Auf Wunsch ergänzt das Tool folgende Einträge:

netbox-topology-views
netbox-attachments
netbox-ping
netbox-reorder-rack
netbox-secrets
netbox-inventory
git+https://git.mrblake.cc/MrBlake/NetBox-VM-Import.git#egg=netbox_vmware_importer

Diese Liste befindet sich in der Konstante:

DEFAULT_PLUGIN_REQUIREMENTS

Sie kann vor der Nutzung an die eigene Umgebung angepasst werden.

LDAP

Wird folgende Datei in der bestehenden Installation gefunden:

/opt/netbox/netbox/netbox/ldap_config.py

führt das Tool zwei Aktionen aus:

1. ldap_config.py wird in die neue Installation kopiert.
2. django-auth-ldap wird in local_requirements.txt sichergestellt.

Plugin-Kompatibilität

Das Tool kann nicht zuverlässig prüfen, ob ein Plugin die Zielversion von NetBox unterstützt. Diese Prüfung erfolgt spätestens beim Installieren der Requirements durch upgrade.sh.

Vor dem Upgrade sollten für jedes Plugin geprüft werden:

• unterstützte NetBox-Version
• unterstützte Python-Version
• erforderliche Migrationsschritte
• geänderte Konfigurationswerte
• bekannte Inkompatibilitäten

Ein nicht kompatibles Plugin kann upgrade.sh abbrechen oder NetBox nach dem Neustart am Starten hindern.

---

CSRF Trusted Origins

Das Tool prüft, ob in configuration.py eine direkte Zuweisung vorhanden ist:

CSRF_TRUSTED_ORIGINS = [
    "https://netbox.example.local",
]

Während des Upgrades können neue Origins kommagetrennt eingegeben werden:

https://netbox.example.local,http://192.168.1.50

Zulässig sind ausschließlich Origins mit:

• http://
• https://
• Hostname oder IP-Adresse
• optionalem Port
• keinem Pfad
• keiner Query
• keinem Fragment

Gültig:

https://netbox.example.local
http://192.168.1.50
https://netbox.example.local:8443

Ungültig:

netbox.example.local
https://netbox.example.local/netbox
https://netbox.example.local?test=1

Werden neue Origins eingegeben, hängt das Tool einen neuen Block an configuration.py an:

# Automatisch durch das NetBox-Upgrade-Tool gesetzt
CSRF_TRUSTED_ORIGINS = [
    'https://netbox.example.local',
    'http://192.168.1.50',
]

Note

Existiert bereits eine direkte Zuweisung und werden zusätzlich neue Werte eingegeben, enthält die Datei anschließend zwei Zuweisungen. In Python gilt die zuletzt ausgewertete Zuweisung. Prüfe die Datei nach dem Upgrade und konsolidiere die Einstellung bei Bedarf.

Dynamisch importierte oder programmatisch zusammengesetzte CSRF-Einstellungen können durch die einfache Prüfung möglicherweise nicht erkannt werden. Das Tool warnt in diesem Fall und verlangt eine zusätzliche Bestätigung.

---

Rollback-Verhalten

Das Rollback-Verhalten hängt davon ab, wann ein Fehler auftritt.

Fehler vor dem Start von upgrade.sh

Tritt der Fehler nach der Verzeichnisumschaltung, aber vor dem Start von upgrade.sh auf, versucht das Tool automatisch:

1. die bisherige Installation wieder zu aktivieren,
2. die NetBox-Dienste neu zu starten.

In diesem Stadium wurden noch keine NetBox-Datenbankmigrationen durch das neue Release ausgeführt.

Fehler nach dem Start von upgrade.sh

Sobald upgrade.sh gestartet wurde, erfolgt kein automatischer vollständiger Rollback mehr.

Grund: Datenbankmigrationen könnten bereits ganz oder teilweise ausgeführt worden sein. Eine reine Rückschaltung des Programmverzeichnisses könnte dann eine ältere NetBox-Version mit einem neueren Datenbankschema kombinieren.

Für einen vollständigen Rollback sind typischerweise erforderlich:

1. Dienste stoppen.
2. Vorherige Installation wieder aktivieren.
3. Datenbank aus dem vor dem Upgrade erstellten Backup wiederherstellen.
4. Media-Dateien bei Bedarf aus demselben Backup wiederherstellen.
5. Zur alten Installation passendes upgrade.sh beziehungsweise die notwendigen Wartungsschritte ausführen.
6. Dienste starten und Logs prüfen.

Normales Verzeichnis

Ist /opt/netbox ein normales Verzeichnis, wird die alte Installation beispielsweise hier abgelegt:

/opt/netbox_old_20260720_143500

Existiert der Name bereits, hängt das Tool eine laufende Nummer an.

Symlink-Installation

Ist /opt/netbox ein Symlink, wird das neue Release beispielsweise hier installiert:

/opt/netbox-4.6.5

Der Symlink /opt/netbox wird atomar auf das neue Verzeichnis umgestellt. Das vorherige Release-Verzeichnis bleibt bestehen.

Das Zielverzeichnis darf noch nicht existieren. Bei einem bereits vorhandenen /opt/netbox-4.6.5 bricht das Tool ab, damit keine vorhandenen Daten überschrieben werden.

---

Backup-Aufbau

Ein vollständiges ZIP-Backup besitzt folgenden Aufbau:

netbox_backup_YYYYMMDD_HHMMSS.zip
├── metadata.json
├── netbox_database.dump
└── media/

Je nach gewähltem Backup-Umfang können netbox_database.dump oder media/ fehlen.

Metadaten

Beispiel einer metadata.json:

{
    "version": "1.2",
    "timestamp": "20260720_143500",
    "source_db": "netbox",
    "contains_db": true,
    "contains_media": true,
    "excluded_changelog": false,
    "excluded_users": false
}

Diese Datei wird beim Restore verwendet, um den enthaltenen Umfang zu bestimmen.

Sicherheit beim Entpacken

Das Tool prüft ZIP- und TAR-Pfade vor dem Entpacken, um Path-Traversal-Angriffe zu verhindern. TAR-Archive mit symbolischen Links oder Hardlinks werden abgelehnt.

Trotzdem sollten ausschließlich Backups und Release-Archive aus vertrauenswürdigen Quellen verwendet werden.

---

Troubleshooting

pg_dump: command not found

PostgreSQL-Client installieren:

sudo apt update
sudo apt install postgresql-client

Bei mehreren PostgreSQL-Versionen sollte eine zum Server passende Client-Version verwendet werden.

PostgreSQL fragt nach einem Passwort

Möglichkeiten:

• db_pass im Skript setzen
• /root/.pgpass konfigurieren
• lokale PostgreSQL-Authentifizierung passend einrichten

dropdb oder createdb schlägt fehl

Der konfigurierte Benutzer besitzt vermutlich nicht die erforderlichen Rechte.

PostgreSQL-Rollen prüfen:

sudo -u postgres psql -c "\du"

Alternativ den Restore-Ablauf so anpassen, dass administrative Datenbankaktionen mit einem separaten PostgreSQL-Benutzer ausgeführt werden.

Zielversion wird nicht gefunden

Fehlermeldung:

NetBox-Release vX.Y.Z wurde auf GitHub nicht gefunden.

Prüfen:

• Schreibweise der Version
• Internetzugriff
• DNS-Auflösung
• Proxy- oder Firewall-Regeln
• Existenz des Releases

Download schlägt über einen Proxy fehl

Python berücksichtigt üblicherweise die Standardvariablen:

export HTTPS_PROXY=http://proxy.example.local:3128
export HTTP_PROXY=http://proxy.example.local:3128
sudo -E ./netbox_backup_restore_upgrade.py

Beachte die Sicherheitsauswirkungen von sudo -E.

configuration.py fehlt

Das Tool erwartet:

/opt/netbox/netbox/netbox/configuration.py

Prüfe CONFIG["netbox_path"] und die tatsächliche NetBox-Verzeichnisstruktur.

Dienst startet nach dem Upgrade nicht

Status prüfen:

systemctl status netbox --no-pager -l
systemctl status netbox-rq --no-pager -l

Logs prüfen:

journalctl -u netbox -n 200 --no-pager
journalctl -u netbox-rq -n 200 --no-pager

Häufige Ursachen:

• inkompatibles Plugin
• falsche Python-Version
• fehlende Systembibliothek
• Fehler in configuration.py
• Fehler in ldap_config.py
• unvollständige Datenbankmigration
• falsche Dateirechte
• geänderte NetBox-Konfigurationsoptionen

upgrade.sh schlägt bei einem Plugin fehl

Plugin vorübergehend in local_requirements.txt auskommentieren oder entfernen, sofern das für die betreffende Migration zulässig ist. Anschließend Plugin-Dokumentation prüfen und eine kompatible Version eintragen.

Vor Änderungen immer sicherstellen, dass ein vollständiges Backup vorhanden ist.

Falscher Python-Interpreter

Im Einstellungsmenü oder dauerhaft im CONFIG-Block setzen:

"python_path": "/usr/bin/python3.12",

Pfad prüfen:

ls -l /usr/bin/python3.12
/usr/bin/python3.12 --version

Media-Dateien besitzen falsche Rechte

Prüfen:

ls -ld /opt/netbox/netbox/media
find /opt/netbox/netbox/media -maxdepth 2 -printf '%u:%g %p\n' | head

Korrigieren:

sudo chown -R netbox:netbox /opt/netbox/netbox/media

Upgrade wurde mit Strg+C unterbrochen

Das globale KeyboardInterrupt-Handling beendet das Programm. Wurde upgrade.sh bereits gestartet, darf nicht davon ausgegangen werden, dass ein automatischer Rollback erfolgt ist.

Vorgehen:

1. Dienststatus prüfen.
2. Prozessliste auf laufende Upgrade-, Pip- oder Migrationsprozesse prüfen.
3. Installationspfad und Symlink-Ziel prüfen.
4. Datenbankschema nicht ohne Backup zurücksetzen.
5. Logs und Ausgabe des Upgrades auswerten.

---

Sicherheitshinweise

Root-Rechte

Backup-Funktionen können je nach Dateirechten möglicherweise ohne Root-Rechte funktionieren. Restore und Upgrade benötigen jedoch erhöhte Rechte für:

• Zugriff auf /opt/netbox
• systemctl
• chown
• Verzeichnisumschaltung

Führe das Tool deshalb für administrative Vorgänge mit sudo aus.

Passwörter im Quelltext

Ein Datenbankpasswort im CONFIG-Block ist für jeden Benutzer lesbar, der Zugriff auf die Skriptdatei besitzt.

Empfehlungen:

• Passwort möglichst über .pgpass bereitstellen
• Skript nur für Root lesbar machen
• keine Skripte mit Zugangsdaten in öffentliche Repositories übertragen
• Backups verschlüsselt speichern

Geeignete Rechte:

sudo chown root:root /usr/local/sbin/netbox-tool
sudo chmod 700 /usr/local/sbin/netbox-tool

Backup-Schutz

Ein NetBox-Datenbankbackup kann sensible Informationen enthalten, beispielsweise:

• Benutzerkonten
• API-Tokens
• Geräte- und Standortdaten
• IP-Adressen
• Secrets aus Plugins
• Dokumente und Bilder

Backups sollten deshalb:

• verschlüsselt übertragen werden
• verschlüsselt gespeichert werden
• nur für berechtigte Personen zugänglich sein
• nach einem definierten Aufbewahrungsplan gelöscht werden

/tmp als Backup-Ziel

/tmp ist als Standardwert bequem, aber nicht als dauerhafter Backup-Speicher geeignet. Ändere backup_dir beispielsweise auf:

"backup_dir": "/srv/backups/netbox",

Verzeichnis vorbereiten:

sudo install -d -m 700 -o root -g root /srv/backups/netbox

Release- und Plugin-Quellen

Das NetBox-Release wird von GitHub geladen. Ein Plugin-Requirement verweist zusätzlich auf einen externen Git-Server.

Prüfe vor dem Einsatz:

• Vertrauen in die Quelle
• Erreichbarkeit
• TLS- und Zertifikatskette
• gewünschte Version beziehungsweise Commit-Pinning
• interne Richtlinien für Software-Lieferketten

Für reproduzierbare Installationen sollten Plugin-Versionen oder Commits möglichst fest vorgegeben werden.

---

Bekannte Einschränkungen

• Einstellungen aus dem Menü werden nicht dauerhaft gespeichert.
• Das Tool prüft Plugin-Kompatibilität nicht vorab.
• Es liest oder interpretiert keine NetBox-Release Notes automatisch.
• Major-Upgrade-Pfade werden nur gewarnt, nicht vollständig validiert.
• Ein automatischer Datenbank-Rollback nach gestarteter Migration ist absichtlich nicht implementiert.
• PostgreSQL-Backup und Restore verwenden denselben konfigurierten Datenbankbenutzer.
• Die Service-Namen netbox und netbox-rq sind fest vorkonfiguriert.
• Zusätzliche Dienste wie ein separater Housekeeping-Service, Reverse Proxy oder Monitoring-Agent werden nicht neu gestartet.
• Manuelle Änderungen am NetBox-Quellcode werden nicht übernommen.
• Bei neu eingegebenen CSRF-Origins wird ein zusätzlicher Konfigurationsblock angehängt, statt einen bestehenden Block strukturell zu bearbeiten.
• Das Skript führt keinen automatischen HTTP-Healthcheck der NetBox-Weboberfläche durch.
• Es wird keine automatische Backup-Rotation durchgeführt.
• Das Backup wird nicht automatisch verschlüsselt.

---

Empfohlene Prüfung nach einem Upgrade

Dienststatus:

systemctl status netbox netbox-rq --no-pager

Fehler in den Logs:

journalctl -u netbox -u netbox-rq --since "15 minutes ago" --no-pager

Weboberfläche prüfen:

• Anmeldung funktioniert
• Startseite lädt ohne Fehler
• Objekte und IPAM-Daten sind vorhanden
• Bilder und Dokumente sind erreichbar
• Custom Scripts und Reports sind vorhanden
• Hintergrundjobs werden verarbeitet
• LDAP-Anmeldung funktioniert
• Plugins werden geladen
• API-Aufrufe funktionieren

Installierte Version über die NetBox-Weboberfläche oder die lokale Installation kontrollieren.

Alte Installation und Backup erst entfernen, wenn die neue Version erfolgreich geprüft und für stabil befunden wurde.

---

Beispiel für einen sicheren Upgrade-Ablauf

# 1. Tool starten
sudo /usr/local/sbin/netbox-tool

# 2. Menüpunkt 1 wählen und vollständiges Backup erstellen

# 3. Backup extern sichern
scp /srv/backups/netbox/netbox_backup_20260720_143500.zip \
  backupserver:/srv/backups/netbox/

# 4. Prüfsumme speichern
sha256sum /srv/backups/netbox/netbox_backup_20260720_143500.zip \
  > /srv/backups/netbox/netbox_backup_20260720_143500.zip.sha256

# 5. Tool erneut starten und Menüpunkt 3 wählen
sudo /usr/local/sbin/netbox-tool

# 6. Nach dem Upgrade Dienste und Logs prüfen
systemctl status netbox netbox-rq --no-pager
journalctl -u netbox -u netbox-rq --since "15 minutes ago" --no-pager

---

Haftungsausschluss

Die Nutzung erfolgt auf eigene Verantwortung. Ein Upgrade kann durch inkompatible Plugins, geänderte Konfigurationsoptionen, Datenbankmigrationen, fehlende Abhängigkeiten oder lokale Anpassungen fehlschlagen.

Vor produktiven Änderungen sollten immer vorhanden sein:

• ein getestetes Datenbankbackup
• ein getestetes Media-Backup
• ein dokumentierter Rollback-Plan
• ein Wartungsfenster
• Zugriff auf System- und Datenbankkonsole
• eine getestete Wiederherstellung auf einer separaten Instanz