# Agent installieren (Windows und Linux) Diese Anleitung beschreibt, was auf einem zu sichernden System einzurichten ist. > **Der Windows-Dienst ist geschrieben, aber nie ausgeführt worden.** Er > übersetzt für Windows — `make cross-build` prüft das bei jedem Lauf —, wurde > aber auf einem macOS-System entwickelt. Der Kommandozeilenweg und die gesamte > Auftragsausführung sind plattformunabhängig und nachgewiesen; der > Dienstwrapper ist der einzige ungeprüfte Teil. ## Was der Agent braucht | | | | --- | --- | | Netzverbindung | **ausgehend** zum Control-Server. Keine eingehende Freigabe nötig — der Agent holt seine Aufträge ab | | Repositoryzugriff | **schreibend**, siehe unten | | Rechte | Lesezugriff auf alles, was gesichert werden soll | | Schlüsselmaterial | `SYNCOVA_ENCRYPTION_KEYS`, sofern verschlüsselt gesichert wird | ### Der Punkt, der am häufigsten übersehen wird **Der Agent schreibt selbst ins Repository.** Der Auftrag enthält dessen Pfad; der Agent öffnet ihn direkt. - Läuft der Agent auf demselben Rechner wie der Control-Server: der lokale Pfad genügt. - Läuft er auf einem anderen Rechner: Das Repository muss dort **eingehängt** sein — als SMB-Freigabe, NFS-Einhängepunkt oder verbundenes Laufwerk. Erreicht der Agent das Repository nicht, meldet er `REPOSITORY_UNREACHABLE` mit dem Hinweis auf die Freigabe. Er liefert **keine** leere Sicherung ab. ## Bauen ```bash # Für Windows GOOS=windows GOARCH=amd64 go build -o syncova-agent.exe ./apps/agent/cmd/syncova-agent # Für Linux GOOS=linux GOARCH=amd64 go build -o syncova-agent ./apps/agent/cmd/syncova-agent ``` ## Windows ### 1. Aufnahme-Token am Server erzeugen ```bash curl -X POST https:///api/v1/agents/enrollment-tokens \ -H "Authorization: Bearer " \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"agent_name":"WINSRV01"}' ``` Der Name steht **im Token**, nicht in der Anmeldung des Agenten: Ein Agent bestimmt seinen Namen nicht selbst, sonst könnte er sich als ein anderes System ausgeben. Das Token gilt eine Stunde und nur einmal. ### 2. Agent aufnehmen ```powershell New-Item -ItemType Directory -Force -Path C:\ProgramData\Syncova .\syncova-agent.exe register ` --server https:// ` --token ` --state C:\ProgramData\Syncova\agent.json ``` Die Zustandsdatei enthält das **Betriebstoken**. Sie gehört geschützt: ```powershell icacls C:\ProgramData\Syncova\agent.json /inheritance:r /grant:r "SYSTEM:(R)" ``` ### 3. Als Dienst einrichten ```powershell sc.exe create SyncovaAgent ` binPath= "C:\Program Files\Syncova\syncova-agent.exe run --state C:\ProgramData\Syncova\agent.json" ` start= auto ` DisplayName= "Syncova Backup Agent" sc.exe description SyncovaAgent "Sichert dieses System über den Syncova Control Server." sc.exe failure SyncovaAgent reset= 86400 actions= restart/60000/restart/60000/restart/300000 sc.exe start SyncovaAgent ``` **Der Dienstname muss `SyncovaAgent` lauten.** Er ist im Programm festgeschrieben (`windowsServiceName`); weicht er ab, meldet sich der Prozess beim Dienstverwalter nicht an, und Windows beendet ihn nach der Startfrist — mit einer Meldung, die wie ein Absturz aussieht. ### 4. Schlüsselmaterial hinterlegen Der Dienst liest es aus seiner Umgebung: ```powershell # Als Registry-Wert des Dienstes, damit es nicht in einem Skript steht $env = @("SYNCOVA_ENCRYPTION_KEYS=v1:") Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\SyncovaAgent" ` -Name Environment -Value $env -Type MultiString Restart-Service SyncovaAgent ``` Ohne Schlüsselmaterial startet der Agent, **lehnt aber jeden Auftrag mit verlangter Verschlüsselung ab**. Er führt ihn nicht unverschlüsselt aus: Ein Backup, das der Server für verschlüsselt hält und das es nicht ist, wäre eine Zusicherung ins Leere. ### 5. Dienstkonto Standardmäßig läuft der Dienst als `LocalSystem`. Das genügt zum Lesen der meisten Dateien und ist der Grund, warum es funktioniert — aber es ist mehr Recht, als nötig. Für ein eigenes Dienstkonto: ```powershell sc.exe config SyncovaAgent obj= "DOMAIN\svc_syncova" password= "" ``` Das Konto braucht dann Leserechte auf alle zu sichernden Pfade **und** Schreib‑ rechte auf das Repository. Fehlt eines davon, meldet der Agent es als übergangenes Objekt — der Lauf wird zum Teilfehler, nicht zum stillen Erfolg. ## Linux ```bash sudo useradd --system --no-create-home --shell /usr/sbin/nologin syncova sudo install -m 0755 syncova-agent /usr/local/bin/ sudo install -d -m 0700 -o syncova -g syncova /etc/syncova sudo -u syncova /usr/local/bin/syncova-agent register \ --server https:// --token \ --state /etc/syncova/agent.json ``` Die mitgelieferte Einheit liegt unter `deployment/syncova-agent.service`: ```bash sudo cp deployment/syncova-agent.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now syncova-agent ``` Das Schlüsselmaterial gehört in eine Datei, die nur `root` liest: ```bash sudo install -m 0600 /dev/null /etc/syncova/agent.env echo "SYNCOVA_ENCRYPTION_KEYS=v1:" | sudo tee /etc/syncova/agent.env >/dev/null # In der Unit: EnvironmentFile=/etc/syncova/agent.env ``` > Auch `deployment/syncova-agent.service` ist auf macOS geschrieben und > ungeprüft — `systemd-analyze verify` gibt es dort nicht. ## Auftrag einrichten Der Auftrag entsteht am Server. Entscheidend ist die Zuweisung der Quelle an den Agenten: ```json { "name": "Dateiserver täglich", "repository_id": "", "schedule": { "type": "daily", "time": "02:00", "time_zone": "Europe/Berlin" }, "sources": [{ "type": "filesystem", "id": "D:\\Daten", "name": "Dateiserver D:", "agent_id": "" }] } ``` **Ohne `agent_id` sichert der Control-Server selbst** — und scheitert, weil er das Dateisystem des fremden Rechners nicht erreicht. ## Prüfen, ob es läuft ```bash # Meldet sich der Agent? curl -H "Authorization: Bearer " https:///api/v1/agents # Was hat er zuletzt getan? curl -H "Authorization: Bearer " https:///api/v1/agents//health ``` Windows-Ereignisprotokoll: Der Dienst schreibt seine Meldungen auf die Standardausgabe. Für das Ereignisprotokoll empfiehlt sich eine Umleitung in eine Datei über den `binPath` oder ein Dienstwrapper wie NSSM. ## Fehlerbilder | Meldung | Ursache | | --- | --- | | `REPOSITORY_UNREACHABLE` | Der Agent erreicht das Repository nicht. Freigabe eingehängt? Rechte des Dienstkontos? | | `ENCRYPTION_KEY_MISSING` | Auftrag verlangt Verschlüsselung, dem Agenten fehlt der Schlüssel | | `RESTORE_TARGET_FORBIDDEN` | Das Wiederherstellungsziel liegt in einem Systemverzeichnis | | `AGENT_LOST` | Der Agent meldete sich während eines Auftrags nicht mehr. Der Auftrag wird **nicht** selbsttätig wiederholt — er könnte bereits Blöcke geschrieben haben | | `UNKNOWN_TASK_TYPE` | Der Server kennt eine Auftragsart, die dieser Agent nicht hat. Agent aktualisieren | | Dienst startet und endet sofort | Zustandsdatei fehlt oder ist unlesbar. `syncova-agent register` erneut ausführen | ## Was der Agent nicht tut - **Er entscheidet nicht über Wiederherstellungen.** Recht und wörtliche Bestätigung des Zielpfads prüft der Server, bevor ein Auftrag entsteht. Was der Agent sehr wohl prüft, ist der Zielpfad gegen die Systemverzeichnisse **seines** Systems — das kann der Server nicht, er kennt sie nicht. - **Er sendet keine Daten an den Server.** Er schreibt unmittelbar ins Repository. Ein Streaming-Protokoll verdoppelte den Datenweg und machte den Control-Server zum Engpass jeder Sicherung. - **Er nimmt keine eingehenden Verbindungen an.** Alle Verbindungen gehen von ihm aus.