NetBox Plugin Store installieren

Voraussetzungen

• NetBox 4.6.5 bis 4.6.8 auf einem Linux-Host, standardmäßig unter /opt/netbox
• sudo- beziehungsweise Root-Zugriff und eine funktionierende Internetverbindung
• ein aktuelles Backup von NetBox-Konfiguration und Datenbank

1. Installer herunterladen und prüfen

Lade das Script zuerst als Datei herunter. Verwende keine direkte curl | sudo bash-Pipe, damit du den ausgeführten Inhalt vorher kontrollieren kannst.

curl -fsSLo /tmp/netbox-store-install.sh \
  https://git.mrblake.cc/MrBlake/Netbox-Store/raw/branch/main/install.sh

less /tmp/netbox-store-install.sh
sudo bash /tmp/netbox-store-install.sh

Der Installer ermittelt zu Beginn einen festen 40-stelligen Commit. Plugin, Agent, Konfigurationsvorlage und systemd-Units werden anschließend ausschließlich aus genau diesem Stand geladen.

2. Betriebsmodus auswählen

• Sicherer Testmodus: Katalog und Lifecycle-Pläne können geprüft werden; Lifecycle-Aktionen verändern das System nicht.
• Produktionsmodus: Installationen, Updates, Aktivierungen, Deaktivierungen und Deinstallationen laufen über den Host-Agent. Dieser Modus verlangt zusätzlich die exakte Eingabe ECHT INSTALLIEREN.

Danach bestätigt der Benutzer NetBox-Pfad, Dienstkonto, erkannte NetBox-Version und Store-URL. Vor der ersten Änderung zeigt das Script alle Werte noch einmal zusammengefasst an.

3. Was automatisch eingerichtet wird

• netbox-plugin-store in der NetBox-Virtualenv und in local_requirements.txt
• der Host-Agent unter /opt/netbox-store-agent/venv
• /etc/netbox-store-agent/agent.toml mit Dienstkonto und NetBox-Version
• systemd-Service und Unix-Socket
• netbox.store_plugins und die verwaltete Requirements-Datei
• ein eindeutig markierter, bei Updates ersetzbarer Block in configuration.py
• Migrationen, statische Dateien und Neustart der beteiligten Dienste

Vorhandene Konfigurationen werden nicht vollständig überschrieben. Vor jeder Änderung entstehen Sicherungskopien unter /var/backups/netbox-plugin-store/.

4. Installation prüfen

sudo systemctl status netbox-store-agent.socket --no-pager -l
sudo systemctl status netbox-store-agent.service --no-pager -l
sudo systemctl status netbox netbox-rq --no-pager -l

sudo -u netbox \
  /opt/netbox-store-agent/venv/bin/netbox-store-agent capabilities

sudo /opt/netbox/venv/bin/python -c \
  'from netbox_plugin_store import __version__; print(__version__)'

5. Erstes Store-Plugin installieren

1. Öffne in NetBox den Plugin Store und wähle ein Plugin mit verfügbarer Version.
2. Starte Installieren. Im Produktionsmodus darf „Nur prüfen (Dry-Run)“ nicht markiert sein.
3. Kontrolliere im Audit, dass Dry-Run: Nein und ein Agent-Vorgang angezeigt werden.
4. Eine erfolgreiche Installation lässt das Plugin absichtlich deaktiviert. Führe anschließend separat Aktivieren aus.

Updates und erneute Konfiguration

Der Installer ist wiederholbar. Lade bei einem Update die aktuelle Datei erneut herunter und führe sie noch einmal aus. Veraltete Store-Requirements und der markierte Konfigurationsblock werden aktualisiert; manuelle Einstellungen außerhalb dieses Blocks bleiben erhalten.

Häufige Hinweise

Audit erfolgreich, aber nichts installiert

Steht im Audit Dry-Run: Ja oder state: dry-run, wurde nur der Ablauf geprüft. Für eine reale Installation muss der Produktionsmodus eingerichtet und der Dry-Run-Haken deaktiviert sein.

Keine Version auswählbar

Plugin und Artefakt werden getrennt freigegeben. Synchronisiere das Repository im Store-Adminbereich und gib danach das Wheel- oder Source-Artefakt unter „Release-Artefakte“ frei.

„configuration.py must contain exactly one static PLUGINS assignment“

Eine ältere Installer-Version konnte im verwalteten Block eine zweite PLUGINS-Zuweisung anlegen. Lade den aktuellen Installer erneut herunter und führe ihn mit denselben gewünschten Einstellungen aus. Er entfernt den alten Block, ergänzt netbox_plugin_store in der einzigen statischen Liste und erzeugt den korrigierten Block neu.

curl -fsSLo /tmp/netbox-store-install.sh \
  https://git.mrblake.cc/MrBlake/Netbox-Store/raw/branch/main/install.sh
sudo bash /tmp/netbox-store-install.sh

sudo /opt/netbox/venv/bin/python -m py_compile \
  /opt/netbox/netbox/netbox/configuration.py

API_TOKEN_PEPPERS-Warnung

Diese NetBox-Einstellung gehört nicht zum Plugin und wird deshalb nicht automatisch verändert:

sudo /opt/netbox/venv/bin/python /opt/netbox/netbox/generate_secret_key.py

Trage den erzeugten geheimen Wert mit einem Doppelpunkt nach der numerischen ID in configuration.py ein und bewahre ihn dauerhaft auf:

API_TOKEN_PEPPERS = {
    1: "HIER_DEN_GENERIERTEN_WERT_EINTRAGEN",
}

Gunicorn meldet „Permission denied: /nonexistent“

grep -qE '^[[:space:]]*control_socket_disable[[:space:]]*=[[:space:]]*True' /opt/netbox/gunicorn.py \
  || echo 'control_socket_disable = True' | sudo tee -a /opt/netbox/gunicorn.py

sudo systemctl restart netbox
curl -sS -o /dev/null -w 'HTTP %{http_code} in %{time_total}s\n' \
  --max-time 10 http://127.0.0.1:8001/login/

Manuelle Installation

Für abweichende Pfade oder eigene systemd-Policies stehen die technischen Einzelheiten in der Plugin-Dokumentation und der Host-Agent-Dokumentation.