From 2063d9ca3cbe1591f034dcae957839567d3f3c2f Mon Sep 17 00:00:00 2001
From: Louis-Alexander Kerst <louis@alexander-kerst.de>
Date: Mon, 24 Aug 2026 22:19:57 +0200
Subject: [PATCH] docs: address Gunicorn control socket hangs

---
 store/templates/installation.php | 8 ++++++++
 store/tests/run.php              | 2 ++
 2 files changed, 10 insertions(+)

diff --git a/store/templates/installation.php b/store/templates/installation.php
index 7a5c909..04609c2 100644
--- a/store/templates/installation.php
+++ b/store/templates/installation.php
@@ -53,6 +53,14 @@ PLUGINS_CONFIG = {
   <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 aus <code>host_agent/</code>, prüfe <code>/etc/netbox-store-agent/agent.toml</code> und stelle anschließend <code>execution_mode</code> auf <code>agent</code>.</p>
   <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>
diff --git a/store/tests/run.php b/store/tests/run.php
index a24c4bd..48f0568 100644
--- a/store/tests/run.php
+++ b/store/tests/run.php
@@ -498,6 +498,8 @@ test('public and admin templates render safely with complete artifact evidence',
     assertTrue(str_contains($installation, 'API_TOKEN_PEPPERS'));
     assertTrue(str_contains($installation, '/opt/netbox/netbox/generate_secret_key.py'));
     assertTrue(str_contains($installation, 'python -m py_compile'));
+    assertTrue(str_contains($installation, 'control_socket_disable = True'));
+    assertTrue(str_contains($installation, 'http://127.0.0.1:8001/login/'));
     $admin = $view->render('admin/dashboard', [
         'title' => 'Admin', 'currentPath' => '/admin', 'adminEnabled' => true, 'adminUser' => 'admin',
         'csrf' => 'safe-token', 'ok' => '', 'error' => '', 'sources' => $state['sources'],