128 lines
10 KiB
PHP
128 lines
10 KiB
PHP
<?php declare(strict_types=1); include __DIR__ . '/partials/head.php'; ?>
|
||
<section class="install-hero">
|
||
<div class="shell prose-shell">
|
||
<p class="eyebrow">NetBox 4.6.5–4.6.8</p>
|
||
<h1>NetBox Store Plugin installieren</h1>
|
||
<p>Das Plugin verbindet deine NetBox mit <code>https://netbox.mrblake.cc</code>. Docker ist nicht erforderlich.</p>
|
||
</div>
|
||
</section>
|
||
<section class="shell prose-shell install-guide">
|
||
<aside class="notice"><strong>Vorher sichern:</strong> Erstelle ein Backup von NetBox und der Datenbank. Führe die Befehle auf dem NetBox-Host aus.</aside>
|
||
<h2>Interaktive Komplettinstallation</h2>
|
||
<p>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.</p>
|
||
<pre><code>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</code></pre>
|
||
<p>Wähle für die erste Funktionsprüfung den sicheren Testmodus. Der Produktionsmodus verlangt zusätzlich die Eingabe <code>ECHT INSTALLIEREN</code>. Der folgende Abschnitt dokumentiert dieselben Schritte für eine manuelle Installation.</p>
|
||
<h2>1. Plugin aus git.mrblake.cc installieren</h2>
|
||
<p>Trage das Plugin dauerhaft in <code>/opt/netbox/local_requirements.txt</code> ein. Die empfohlene HTTPS-Archivvariante benötigt kein lokal installiertes Git. Für reproduzierbare Installationen solltest du <code>main</code> durch einen geprüften Commit-SHA ersetzen.</p>
|
||
<pre><code>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</code></pre>
|
||
<p>Der erste Befehl entfernt ausschließlich ältere Bezugsquellen dieses Plugins. Dadurch bleibt auch nach einem Wechsel zwischen Git- und Archivinstallation genau ein Eintrag vorhanden.</p>
|
||
<h3>Alternative mit Git</h3>
|
||
<p>Wenn du stattdessen eine <code>git+https</code>-Requirement verwendest, muss das Programm <code>git</code> vor dem NetBox-Upgrade installiert sein:</p>
|
||
<pre><code>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</code></pre>
|
||
<h2>2. API-Token-Pepper konfigurieren</h2>
|
||
<p>NetBox 4.6 warnt beim Start, wenn kein Pepper für v2-API-Tokens vorhanden ist. Erzeuge einmalig einen zufälligen Wert:</p>
|
||
<pre><code>sudo /opt/netbox/venv/bin/python /opt/netbox/netbox/generate_secret_key.py</code></pre>
|
||
<p>Übernimm die Ausgabe anschließend in <code>/opt/netbox/netbox/netbox/configuration.py</code>. Die Ganzzahl <code>1</code> ist die Pepper-ID:</p>
|
||
<pre><code>API_TOKEN_PEPPERS = {
|
||
1: "HIER_DEN_GENERIERTEN_WERT_EINTRAGEN",
|
||
}</code></pre>
|
||
<p>Achte auf den Doppelpunkt nach der numerischen ID (<code>1:</code>, nicht <code>1;</code>). Prüfe die Python-Syntax, bevor du das Upgrade fortsetzt; bei Erfolg erzeugt dieser Befehl keine Ausgabe:</p>
|
||
<pre><code>sudo /opt/netbox/venv/bin/python -m py_compile /opt/netbox/netbox/netbox/configuration.py</code></pre>
|
||
<aside class="notice warning"><strong>Geheimnis dauerhaft sichern:</strong> Der Pepper muss vertraulich und über Upgrades hinweg unverändert erhalten bleiben. Entferne oder ändere einen bereits verwendeten Pepper nicht, da davon bestehende v2-API-Tokens abhängen. Für eine spätere Rotation wird eine weitere numerische ID ergänzt.</aside>
|
||
<h2>3. Plugin in NetBox aktivieren</h2>
|
||
<p>Ergänze die NetBox-Konfiguration:</p>
|
||
<pre><code>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",
|
||
}
|
||
}</code></pre>
|
||
<p>Führe danach Migrationen und statische Dateien aus und starte NetBox neu:</p>
|
||
<pre><code>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</code></pre>
|
||
<h3>Gunicorn 25/26: Control-Socket deaktivieren</h3>
|
||
<p>Wenn <code>journalctl -u netbox</code> den Fehler <code>Control server error: Permission denied: '/nonexistent'</code> zeigt oder Gunicorn trotz laufender Worker nicht antwortet, deaktiviere den optionalen Control-Socket:</p>
|
||
<pre><code>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/</code></pre>
|
||
<p>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.</p>
|
||
<h2>4. Sicheren Host-Agent einrichten</h2>
|
||
<p><code>dry_run</code> 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:</p>
|
||
<pre><code>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</code></pre>
|
||
<p>Ermittle anschließend UID und GID des NetBox-Dienstkontos:</p>
|
||
<pre><code>id netbox
|
||
id -u netbox
|
||
id -g netbox</code></pre>
|
||
<p>Öffne <code>/etc/netbox-store-agent/agent.toml</code> und trage die ausgegebenen Zahlen bei <code>allowed_peer_uids</code>, <code>allowed_peer_gids</code> und <code>socket_gid</code> ein. Setze außerdem unter <code>[policy]</code> die tatsächlich installierte NetBox-Version. Pfade und erlaubte Hosts des Beispiels sind bereits auf die Standardinstallation unter <code>/opt/netbox</code> und diesen Store ausgerichtet.</p>
|
||
<p>Erzeuge die beiden verwalteten Startdateien und binde sie einmalig ein:</p>
|
||
<pre><code>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</code></pre>
|
||
<p>Füge in <code>configuration.py</code> direkt nach der vorhandenen <code>PLUGINS</code>-Liste einmalig Folgendes ein:</p>
|
||
<pre><code>from netbox.store_plugins import STORE_PLUGINS
|
||
|
||
PLUGINS += STORE_PLUGINS</code></pre>
|
||
<p>Prüfe zunächst die Agent-Konfiguration und den Socket im sicheren Dry-Run-Modus:</p>
|
||
<pre><code>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</code></pre>
|
||
<p>Wenn dieser Test erfolgreich ist, ändere in <code>agent.toml</code> den Eintrag unter <code>[agent]</code> bewusst auf <code>dry_run = false</code>. Stelle anschließend die Plugin-Konfiguration um:</p>
|
||
<pre><code>"execution_mode": "agent",
|
||
"agent_socket_path": "/run/netbox-store-agent/agent.sock",
|
||
"agent_timeout": 30,
|
||
"default_dry_run": False,</code></pre>
|
||
<p>Aktiviere die reale Ausführung erst nach Prüfung aller Werte:</p>
|
||
<pre><code>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</code></pre>
|
||
<aside class="notice"><strong>Zwei bewusste Freigaben:</strong> Für eine reale Aktion müssen sowohl <code>execution_mode = "agent"</code> im NetBox-Plugin als auch <code>dry_run = false</code> 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.</aside>
|
||
<p>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.</p>
|
||
<aside class="notice warning"><strong>Wichtig:</strong> Source-Builds führen den Build-Code des freigegebenen Repository-Commits aus. Gib nur vertrauenswürdige Kandidaten frei.</aside>
|
||
</section>
|
||
<?php include __DIR__ . '/partials/footer.php'; ?>
|