109 lines
7.6 KiB
PHP
109 lines
7.6 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 Plugin Store installieren</h1>
|
||
<p>Der interaktive Installer richtet Plugin, Host-Agent und NetBox-Konfiguration gemeinsam ein. Docker und ein lokales Git sind nicht erforderlich.</p>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="shell prose-shell install-guide">
|
||
<h2>Voraussetzungen</h2>
|
||
<ul>
|
||
<li>NetBox 4.6.5 bis 4.6.8 auf einem Linux-Host, standardmäßig unter <code>/opt/netbox</code></li>
|
||
<li><code>sudo</code>- beziehungsweise Root-Zugriff und eine funktionierende Internetverbindung</li>
|
||
<li>ein aktuelles Backup von NetBox-Konfiguration und Datenbank</li>
|
||
</ul>
|
||
<aside class="notice warning"><strong>Produktionshinweis:</strong> Der Agent darf geprüfte Python-Pakete installieren, verwaltete NetBox-Dateien ändern und die Dienste <code>netbox</code> sowie <code>netbox-rq</code> neu starten. Prüfe das Script vor der Ausführung.</aside>
|
||
|
||
<h2>1. Installer herunterladen und prüfen</h2>
|
||
<p>Lade das Script zuerst als Datei herunter. Verwende keine direkte <code>curl | sudo bash</code>-Pipe, damit du den ausgeführten Inhalt vorher kontrollieren kannst.</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>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.</p>
|
||
|
||
<h2>2. Betriebsmodus auswählen</h2>
|
||
<ul>
|
||
<li><strong>Sicherer Testmodus:</strong> Katalog und Lifecycle-Pläne können geprüft werden; Lifecycle-Aktionen verändern das System nicht.</li>
|
||
<li><strong>Produktionsmodus:</strong> Installationen, Updates, Aktivierungen, Deaktivierungen und Deinstallationen laufen über den Host-Agent. Dieser Modus verlangt zusätzlich die exakte Eingabe <code>ECHT INSTALLIEREN</code>.</li>
|
||
</ul>
|
||
<p>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.</p>
|
||
|
||
<h2>3. Was automatisch eingerichtet wird</h2>
|
||
<ul>
|
||
<li><code>netbox-plugin-store</code> in der NetBox-Virtualenv und in <code>local_requirements.txt</code></li>
|
||
<li>der Host-Agent unter <code>/opt/netbox-store-agent/venv</code></li>
|
||
<li><code>/etc/netbox-store-agent/agent.toml</code> mit Dienstkonto und NetBox-Version</li>
|
||
<li>systemd-Service und Unix-Socket</li>
|
||
<li><code>netbox.store_plugins</code> und die verwaltete Requirements-Datei</li>
|
||
<li>ein eindeutig markierter, bei Updates ersetzbarer Block in <code>configuration.py</code></li>
|
||
<li>Migrationen, statische Dateien und Neustart der beteiligten Dienste</li>
|
||
</ul>
|
||
<p>Vorhandene Konfigurationen werden nicht vollständig überschrieben. Vor jeder Änderung entstehen Sicherungskopien unter <code>/var/backups/netbox-plugin-store/</code>.</p>
|
||
|
||
<h2>4. Installation prüfen</h2>
|
||
<pre><code>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__)'</code></pre>
|
||
|
||
<h2>5. Erstes Store-Plugin installieren</h2>
|
||
<ol>
|
||
<li>Öffne in NetBox den Plugin Store und wähle ein Plugin mit verfügbarer Version.</li>
|
||
<li>Starte <strong>Installieren</strong>. Im Produktionsmodus darf „Nur prüfen (Dry-Run)“ nicht markiert sein.</li>
|
||
<li>Kontrolliere im Audit, dass <code>Dry-Run: Nein</code> und ein Agent-Vorgang angezeigt werden.</li>
|
||
<li>Eine erfolgreiche Installation lässt das Plugin absichtlich deaktiviert. Führe anschließend separat <strong>Aktivieren</strong> aus.</li>
|
||
</ol>
|
||
<aside class="notice"><strong>Keine Repository-Releases erforderlich:</strong> Definiert das Python-Paket eine Version, erzeugt der Store beim Synchronisieren ein commitgebundenes Source-Artefakt. Dieses muss im Store-Adminbereich unter „Release-Artefakte“ separat freigegeben werden.</aside>
|
||
|
||
<h2>Updates und erneute Konfiguration</h2>
|
||
<p>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.</p>
|
||
|
||
<h2>Häufige Hinweise</h2>
|
||
<h3>Audit erfolgreich, aber nichts installiert</h3>
|
||
<p>Steht im Audit <code>Dry-Run: Ja</code> oder <code>state: dry-run</code>, wurde nur der Ablauf geprüft. Für eine reale Installation muss der Produktionsmodus eingerichtet und der Dry-Run-Haken deaktiviert sein.</p>
|
||
|
||
<h3>Keine Version auswählbar</h3>
|
||
<p>Plugin und Artefakt werden getrennt freigegeben. Synchronisiere das Repository im Store-Adminbereich und gib danach das Wheel- oder Source-Artefakt unter „Release-Artefakte“ frei.</p>
|
||
|
||
<h3>„configuration.py must contain exactly one static PLUGINS assignment“</h3>
|
||
<p>Eine ältere Installer-Version konnte im verwalteten Block eine zweite <code>PLUGINS</code>-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 <code>netbox_plugin_store</code> in der einzigen statischen Liste und erzeugt den korrigierten Block neu.</p>
|
||
<pre><code>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</code></pre>
|
||
|
||
<h3>Socket-Prüfung meldet „No such file or directory“</h3>
|
||
<p>Lade den aktuellen Installer erneut herunter und führe ihn noch einmal aus. Eine ältere systemd-Unit konnte beim Neustart das Verzeichnis des Agent-Sockets entfernen. Der aktuelle Installer ersetzt die Unit und startet den Agent über korrekte Socket-Aktivierung.</p>
|
||
|
||
<h3>API_TOKEN_PEPPERS-Warnung</h3>
|
||
<p>Diese NetBox-Einstellung gehört nicht zum Plugin und wird deshalb nicht automatisch verändert:</p>
|
||
<pre><code>sudo /opt/netbox/venv/bin/python /opt/netbox/netbox/generate_secret_key.py</code></pre>
|
||
<p>Trage den erzeugten geheimen Wert mit einem Doppelpunkt nach der numerischen ID in <code>configuration.py</code> ein und bewahre ihn dauerhaft auf:</p>
|
||
<pre><code>API_TOKEN_PEPPERS = {
|
||
1: "HIER_DEN_GENERIERTEN_WERT_EINTRAGEN",
|
||
}</code></pre>
|
||
|
||
<h3>Gunicorn meldet „Permission denied: /nonexistent“</h3>
|
||
<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>
|
||
|
||
<h2>Manuelle Installation</h2>
|
||
<p>Für abweichende Pfade oder eigene systemd-Policies stehen die technischen Einzelheiten in der <a href="https://git.mrblake.cc/MrBlake/Netbox-Store/src/branch/main/netbox_plugin/README.md" rel="noreferrer noopener">Plugin-Dokumentation</a> und der <a href="https://git.mrblake.cc/MrBlake/Netbox-Store/src/branch/main/host_agent/README.md" rel="noreferrer noopener">Host-Agent-Dokumentation</a>.</p>
|
||
</section>
|
||
<?php include __DIR__ . '/partials/footer.php'; ?>
|