1055 lines
27 KiB
Markdown
1055 lines
27 KiB
Markdown
# 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](#voraussetzungen)
|
|
2. [Installation](#installation)
|
|
3. [Schnellstart](#schnellstart)
|
|
4. [Konfiguration](#konfiguration)
|
|
5. [Backup erstellen](#backup-erstellen)
|
|
6. [Backup wiederherstellen](#backup-wiederherstellen)
|
|
7. [NetBox upgraden](#netbox-upgraden)
|
|
8. [Übernommene Dateien und Verzeichnisse](#übernommene-dateien-und-verzeichnisse)
|
|
9. [Plugins und LDAP](#plugins-und-ldap)
|
|
10. [CSRF Trusted Origins](#csrf-trusted-origins)
|
|
11. [Rollback-Verhalten](#rollback-verhalten)
|
|
12. [Backup-Aufbau](#backup-aufbau)
|
|
13. [Troubleshooting](#troubleshooting)
|
|
14. [Sicherheitshinweise](#sicherheitshinweise)
|
|
15. [Bekannte Einschränkungen](#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:
|
|
|
|
```text
|
|
/opt/netbox
|
|
```
|
|
|
|
Dabei werden unter anderem folgende Pfade erwartet:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
sudo /usr/local/sbin/netbox-tool
|
|
```
|
|
|
|
Alternativ direkt aus dem aktuellen Ordner:
|
|
|
|
```bash
|
|
chmod +x netbox_backup_restore_upgrade.py
|
|
sudo ./netbox_backup_restore_upgrade.py
|
|
```
|
|
|
|
Optional kann vorab die Python-Syntax geprüft werden:
|
|
|
|
```bash
|
|
python3 -m py_compile netbox_backup_restore_upgrade.py
|
|
```
|
|
|
|
---
|
|
|
|
## Schnellstart
|
|
|
|
Nach dem Start erscheint das Hauptmenü:
|
|
|
|
```text
|
|
============================================================
|
|
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:
|
|
|
|
```python
|
|
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
|
|
"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:
|
|
|
|
```text
|
|
/root/.pgpass
|
|
```
|
|
|
|
Beispiel:
|
|
|
|
```text
|
|
localhost:5432:netbox:netbox:MEIN_PASSWORT
|
|
```
|
|
|
|
Berechtigungen setzen:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
netbox_backup_YYYYMMDD_HHMMSS.zip
|
|
```
|
|
|
|
Beispiel:
|
|
|
|
```text
|
|
/tmp/netbox_backup_20260720_143500.zip
|
|
```
|
|
|
|
Nach erfolgreicher Erstellung zeigt das Tool den vollständigen Pfad an.
|
|
|
|
### Backup anschließend prüfen
|
|
|
|
Datei anzeigen:
|
|
|
|
```bash
|
|
ls -lh /tmp/netbox_backup_*.zip
|
|
```
|
|
|
|
ZIP-Inhalt prüfen:
|
|
|
|
```bash
|
|
unzip -l /tmp/netbox_backup_20260720_143500.zip
|
|
```
|
|
|
|
Prüfsumme erzeugen:
|
|
|
|
```bash
|
|
sha256sum /tmp/netbox_backup_20260720_143500.zip
|
|
```
|
|
|
|
Backup auf einen externen Speicher kopieren:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
/opt/netbox/netbox/media
|
|
```
|
|
|
|
Danach setzt das Tool den Eigentümer auf:
|
|
|
|
```text
|
|
netbox:netbox
|
|
```
|
|
|
|
---
|
|
|
|
## NetBox upgraden
|
|
|
|
Im Hauptmenü auswählen:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
4.6.5
|
|
```
|
|
|
|
oder:
|
|
|
|
```text
|
|
v4.6.5
|
|
```
|
|
|
|
Akzeptiert werden ausschließlich stabile Versionsnummern im Format:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
netbox/netbox/configuration.py
|
|
```
|
|
|
|
Fehlt diese Datei, wird das Upgrade abgebrochen.
|
|
|
|
### Optionale Dateien
|
|
|
|
```text
|
|
netbox/netbox/ldap_config.py
|
|
local_requirements.txt
|
|
gunicorn.py
|
|
```
|
|
|
|
Fehlende optionale Dateien führen nicht zum Abbruch.
|
|
|
|
### Optionale Verzeichnisse
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```python
|
|
DEFAULT_PLUGIN_REQUIREMENTS
|
|
```
|
|
|
|
Sie kann vor der Nutzung an die eigene Umgebung angepasst werden.
|
|
|
|
### LDAP
|
|
|
|
Wird folgende Datei in der bestehenden Installation gefunden:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```python
|
|
CSRF_TRUSTED_ORIGINS = [
|
|
"https://netbox.example.local",
|
|
]
|
|
```
|
|
|
|
Während des Upgrades können neue Origins kommagetrennt eingegeben werden:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
https://netbox.example.local
|
|
http://192.168.1.50
|
|
https://netbox.example.local:8443
|
|
```
|
|
|
|
Ungültig:
|
|
|
|
```text
|
|
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:
|
|
|
|
```python
|
|
# 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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```text
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```bash
|
|
systemctl status netbox --no-pager -l
|
|
systemctl status netbox-rq --no-pager -l
|
|
```
|
|
|
|
Logs prüfen:
|
|
|
|
```bash
|
|
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
|
|
"python_path": "/usr/bin/python3.12",
|
|
```
|
|
|
|
Pfad prüfen:
|
|
|
|
```bash
|
|
ls -l /usr/bin/python3.12
|
|
/usr/bin/python3.12 --version
|
|
```
|
|
|
|
### Media-Dateien besitzen falsche Rechte
|
|
|
|
Prüfen:
|
|
|
|
```bash
|
|
ls -ld /opt/netbox/netbox/media
|
|
find /opt/netbox/netbox/media -maxdepth 2 -printf '%u:%g %p\n' | head
|
|
```
|
|
|
|
Korrigieren:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```python
|
|
"backup_dir": "/srv/backups/netbox",
|
|
```
|
|
|
|
Verzeichnis vorbereiten:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
systemctl status netbox netbox-rq --no-pager
|
|
```
|
|
|
|
Fehler in den Logs:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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 |