Agent-Update-Mechanik

Wie und wann theProx-Agents nach Updates suchen, sich selbst aktualisieren und wann Updates tatsächlich angewendet werden. Drei Ebenen, die strikt getrennt sind.

Kurzfassung: Agents erkennen/melden Updates periodisch und aktualisieren teils ihre eigene Binary, aber das Anwenden von OS-/Docker-Updates ist nie autonom — es ist manuell (UI) oder über den server-seitigen Auto-Update-Scheduler (vom Betreiber konfiguriert).

1. Update-Erkennung (Reporting) — periodisch, nur Anzeige

Der Agent sammelt im Daten-Loop, welche Updates verfügbar sind (OS via apt/dnf, Docker-Compose- Digests) und meldet das ans Backend. Das installiert nichts — es füllt nur die Anzeige ("N Updates verfügbar").

Agent	`scan_interval` Default	Anmerkung
Node-Agent	300 s (5 min)	Backend-seitiger Per-Node-Wert ist die Quelle der Wahrheit (#44), wird bei jedem Reconnect angewendet; zur Laufzeit per UI änderbar (`set_interval`, ohne Agent-Neustart).
VM-Guest-Agent	1800 s (30 min)	zusätzlich eigener `update_interval` (s. u.).

Konfiguration: SCAN_INTERVAL / AGENT_SCAN_INTERVAL in /etc/theprox-agent/agent.conf.

2. Agent-Selbst-Update — Agent aktualisiert seine eigene Binary

Betrifft nur die Agent-Software selbst, nicht OS/Docker. Verhalten unterscheidet sich je Agent-Typ:

Node-Agent: kommando-getriggert (kein Timer)

Der Node-Agent aktualisiert sich nicht von allein. Self-Update läuft nur, wenn das Backend das Kommando agent.self_update schickt (commands_async.rs) — manuell ausgelöst oder über einen geplanten Job. Es gibt keinen autonomen Self-Update-Timer im Node-Agent.

Der Node-Agent betreibt zwar einen Hintergrund-Loop (vm_binaries), der die VM-Agent-Binaries periodisch nachzieht — aber nur, um sie an Gäste auszuliefern (Port 9101). Das ist kein Selbst-Update des Node-Agents.

VM-Guest-Agent: autonomer Loop

Der VM-Guest-Agent prüft alle update_interval Sekunden (Default 600 s = 10 min) beim Backend auf eine neuere VM-Agent-Binary, lädt sie ggf. und ersetzt sich selbst. Zusätzlich kann der Node-Agent per vm.self_update_all alle VM-Agents zentral aktualisieren.

Konfiguration: UPDATE_INTERVAL in der agent.conf des VM-Agents.

Integrität & Transport des Self-Updates (#187)

Download nur über https (bzw. ws/http, wenn TRUSTED_TRANSPORT=vpn gesetzt ist, #189) — Server-Zertifikat wird verifiziert.
sha256-Integritätsprüfung über den X-Binary-Hash-Header: fehlt der Header oder weicht der Hash ab → Update wird verweigert (fail-closed). Ersetzen erfolgt atomar.
Keine ed25519-Signatur: das Vertrauen stützt sich auf TLS (self-hosted-Modell, ein Backend + Agents in einer Vertrauenszone). Siehe Self-Update-Signing / Deployment-Public.

3. Update-Anwenden (OS/Docker) — nie autonom durch den Agent

Der Agent installiert OS-/Docker-Updates nicht von selbst. Das geschieht ausschließlich:

On-demand: Klick auf "Update" im UI (einzeln oder Bulk).
Geplant: über den Node-Auto-Update-Scheduler (#174). Dieser läuft server-seitig (scheduler.py, Tick alle 60 s, feuert fällige Jobs per Cron) nach einem vom Betreiber konfigurierten Zeitplan. Der Agent entscheidet das nicht selbst — er führt nur aus, was der Scheduler/Backend beauftragt.

Zusammenfassung

Vorgang	Autonom?	Takt	Quelle
Update-Erkennung (Anzeige)	ja	scan_interval (Node 5 min / VM 30 min)	Agent-Daten-Loop
Node-Agent Selbst-Update	nein	nur auf Kommando `agent.self_update`	Backend/Job
VM-Agent Selbst-Update	ja	update_interval (Default 10 min)	VM-Agent-Loop
OS/Docker Anwenden	nein	on-demand oder geplant	UI bzw. Scheduler #174 (Betreiber)

Faustregel: Suchen/Melden passiert automatisch. Die eigene Binary hält der VM-Agent selbst aktuell (Node-Agent nur auf Kommando). Das Anwenden echter OS-/Docker-Updates bleibt eine bewusste Entscheidung — manuell oder über den selbst konfigurierten Zeitplan.

Bezug: #44 (Per-Node scan_interval), #174 (Auto-Update-Scheduler), #187/#189 (Self-Update-Transport). Stand verifiziert gegen Node-Agent/VM-Guest-Agent + scheduler.py.