Interaktive Komplettinstallation

Der Installer richtet NetBox-Plugin, Host-Agent, systemd-Socket, Requirements und den markierten Konfigurationsblock gemeinsam ein. Er fragt Pfade, Dienstkonto, NetBox-Version und Betriebsmodus ab, zeigt vorab eine Zusammenfassung und erstellt Sicherungskopien. Lade ihn zuerst herunter und prüfe seinen Inhalt; führe keinen ungeprüften Remote-Code direkt über eine Pipe als Root aus.

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

Wähle für die erste Funktionsprüfung den sicheren Testmodus. Der Produktionsmodus verlangt zusätzlich die Eingabe ECHT INSTALLIEREN. Der folgende Abschnitt dokumentiert dieselben Schritte für eine manuelle Installation.

1. Plugin aus git.mrblake.cc installieren

Trage das Plugin dauerhaft in /opt/netbox/local_requirements.txt ein. Die empfohlene HTTPS-Archivvariante benötigt kein lokal installiertes Git. Für reproduzierbare Installationen solltest du main durch einen geprüften Commit-SHA ersetzen.

sudo sed -i '/^[[:space:]]*netbox-plugin-store[[:space:]]*@/d' /opt/netbox/local_requirements.txt
echo 'netbox-plugin-store @ https://git.mrblake.cc/MrBlake/Netbox-Store/archive/main.tar.gz#subdirectory=netbox_plugin' | sudo tee -a /opt/netbox/local_requirements.txt
sudo /opt/netbox/upgrade.sh

Der erste Befehl entfernt ausschließlich ältere Bezugsquellen dieses Plugins. Dadurch bleibt auch nach einem Wechsel zwischen Git- und Archivinstallation genau ein Eintrag vorhanden.

Alternative mit Git

Wenn du stattdessen eine git+https-Requirement verwendest, muss das Programm git vor dem NetBox-Upgrade installiert sein:

sudo apt update
sudo apt install -y git

# Requirement:
netbox-plugin-store @ git+https://git.mrblake.cc/MrBlake/Netbox-Store.git@main#subdirectory=netbox_plugin

2. API-Token-Pepper konfigurieren

NetBox 4.6 warnt beim Start, wenn kein Pepper für v2-API-Tokens vorhanden ist. Erzeuge einmalig einen zufälligen Wert:

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

Übernimm die Ausgabe anschließend in /opt/netbox/netbox/netbox/configuration.py. Die Ganzzahl 1 ist die Pepper-ID:

API_TOKEN_PEPPERS = {
    1: "HIER_DEN_GENERIERTEN_WERT_EINTRAGEN",
}

Achte auf den Doppelpunkt nach der numerischen ID (1:, nicht 1;). Prüfe die Python-Syntax, bevor du das Upgrade fortsetzt; bei Erfolg erzeugt dieser Befehl keine Ausgabe:

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

3. Plugin in NetBox aktivieren

Ergänze die NetBox-Konfiguration:

PLUGINS = [
    "netbox_plugin_store",
]

PLUGINS_CONFIG = {
    "netbox_plugin_store": {
        "store_url": "https://netbox.mrblake.cc",
        "allowed_store_urls": ["https://netbox.mrblake.cc"],
        "allowed_artifact_urls": [
            "https://git.mrblake.cc",
            "https://github.com",
            "https://codeload.github.com",
        ],
        "execution_mode": "dry_run",
    }
}

Führe danach Migrationen und statische Dateien aus und starte NetBox neu:

sudo /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate
sudo /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

Gunicorn 25/26: Control-Socket deaktivieren

Wenn journalctl -u netbox den Fehler Control server error: Permission denied: '/nonexistent' zeigt oder Gunicorn trotz laufender Worker nicht antwortet, deaktiviere den optionalen Control-Socket:

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/

Die Control-Schnittstelle wird von NetBox nicht für den normalen WSGI-Betrieb benötigt. Der Test muss innerhalb von zehn Sekunden einen HTTP-Status ausgeben.

4. Sicheren Host-Agent einrichten

dry_run verändert das System nicht. Für Installieren, Aktualisieren, Aktivieren und Entfernen wird der mitgelieferte Linux Host-Agent benötigt. Installiere ihn in eine eigene virtuelle Umgebung:

sudo apt update
sudo apt install -y python3-venv util-linux curl
sudo python3 -m venv /opt/netbox-store-agent/venv
sudo /opt/netbox-store-agent/venv/bin/pip install --upgrade pip
sudo /opt/netbox-store-agent/venv/bin/pip install \
  'mrblake-netbox-store-agent @ https://git.mrblake.cc/MrBlake/Netbox-Store/archive/main.tar.gz#subdirectory=host_agent'

sudo install -d -o root -g root -m 0750 /etc/netbox-store-agent
curl -fsSL https://git.mrblake.cc/MrBlake/Netbox-Store/raw/branch/main/host_agent/examples/agent.toml \
  | sudo tee /etc/netbox-store-agent/agent.toml >/dev/null
sudo chmod 0600 /etc/netbox-store-agent/agent.toml

curl -fsSL https://git.mrblake.cc/MrBlake/Netbox-Store/raw/branch/main/host_agent/systemd/netbox-store-agent.service \
  | sudo tee /etc/systemd/system/netbox-store-agent.service >/dev/null
curl -fsSL https://git.mrblake.cc/MrBlake/Netbox-Store/raw/branch/main/host_agent/systemd/netbox-store-agent.socket \
  | sudo tee /etc/systemd/system/netbox-store-agent.socket >/dev/null
sudo sed -i 's#/usr/local/bin/netbox-store-agent#/opt/netbox-store-agent/venv/bin/netbox-store-agent#' \
  /etc/systemd/system/netbox-store-agent.service

Ermittle anschließend UID und GID des NetBox-Dienstkontos:

id netbox
id -u netbox
id -g netbox

Öffne /etc/netbox-store-agent/agent.toml und trage die ausgegebenen Zahlen bei allowed_peer_uids, allowed_peer_gids und socket_gid ein. Setze außerdem unter [policy] die tatsächlich installierte NetBox-Version. Pfade und erlaubte Hosts des Beispiels sind bereits auf die Standardinstallation unter /opt/netbox und diesen Store ausgerichtet.

Erzeuge die beiden verwalteten Startdateien und binde sie einmalig ein:

echo 'STORE_PLUGINS = []' | sudo tee /opt/netbox/netbox/netbox/store_plugins.py >/dev/null
echo '# Generated by netbox-store-agent. Do not edit.' | sudo tee /opt/netbox/local_requirements_store.txt >/dev/null
sudo chmod 0644 /opt/netbox/netbox/netbox/store_plugins.py /opt/netbox/local_requirements_store.txt

grep -qxF -- '-r /opt/netbox/local_requirements_store.txt' /opt/netbox/local_requirements.txt \
  || echo '-r /opt/netbox/local_requirements_store.txt' | sudo tee -a /opt/netbox/local_requirements.txt

Füge in configuration.py direkt nach der vorhandenen PLUGINS-Liste einmalig Folgendes ein:

from netbox.store_plugins import STORE_PLUGINS

PLUGINS += STORE_PLUGINS

Prüfe zunächst die Agent-Konfiguration und den Socket im sicheren Dry-Run-Modus:

sudo /opt/netbox-store-agent/venv/bin/netbox-store-agent \
  --config /etc/netbox-store-agent/agent.toml validate-config
sudo systemctl daemon-reload
sudo systemctl enable --now netbox-store-agent.socket
sudo -u netbox /opt/netbox-store-agent/venv/bin/netbox-store-agent capabilities

Wenn dieser Test erfolgreich ist, ändere in agent.toml den Eintrag unter [agent] bewusst auf dry_run = false. Stelle anschließend die Plugin-Konfiguration um:

"execution_mode": "agent",
"agent_socket_path": "/run/netbox-store-agent/agent.sock",
"agent_timeout": 30,
"default_dry_run": False,

Aktiviere die reale Ausführung erst nach Prüfung aller Werte:

sudo systemctl restart netbox-store-agent.service
sudo /opt/netbox/venv/bin/python -m py_compile /opt/netbox/netbox/netbox/configuration.py
sudo systemctl restart netbox netbox-rq
sudo -u netbox /opt/netbox-store-agent/venv/bin/netbox-store-agent capabilities

Zwei bewusste Freigaben: Für eine reale Aktion müssen sowohl execution_mode = "agent" im NetBox-Plugin als auch dry_run = false im Host-Agent gesetzt sein. Kontrolliere im Bestätigungsdialog außerdem, dass „Nur prüfen (Dry-Run)“ nicht markiert ist. Eine Installation lässt das neue Plugin zunächst deaktiviert; führe danach separat „Aktivieren“ aus.

Source-Kandidaten werden nur nach Admin-Freigabe verarbeitet. Der Agent prüft Commitbindung, Größe und SHA-256, baut daraus lokal ein Wheel und installiert nicht direkt aus einem beweglichen Branch.