syncova-backup/docs/agent-installation.md

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

# 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

curl -X POST https://<server>/api/v1/agents/enrollment-tokens \
  -H "Authorization: Bearer <token>" \
  -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

New-Item -ItemType Directory -Force -Path C:\ProgramData\Syncova

.\syncova-agent.exe register `
  --server https://<server> `
  --token <aufnahme-token> `
  --state C:\ProgramData\Syncova\agent.json

Die Zustandsdatei enthält das Betriebstoken. Sie gehört geschützt:

icacls C:\ProgramData\Syncova\agent.json /inheritance:r /grant:r "SYSTEM:(R)"

3. Als Dienst einrichten

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:

# Als Registry-Wert des Dienstes, damit es nicht in einem Skript steht
$env = @("SYNCOVA_ENCRYPTION_KEYS=v1:<base64-schluessel>")
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:

sc.exe config SyncovaAgent obj= "DOMAIN\svc_syncova" password= "<passwort>"

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

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://<server> --token <aufnahme-token> \
  --state /etc/syncova/agent.json

Die mitgelieferte Einheit liegt unter deployment/syncova-agent.service:

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:

sudo install -m 0600 /dev/null /etc/syncova/agent.env
echo "SYNCOVA_ENCRYPTION_KEYS=v1:<base64-schluessel>" | 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:

{
  "name": "Dateiserver täglich",
  "repository_id": "<repository>",
  "schedule": { "type": "daily", "time": "02:00", "time_zone": "Europe/Berlin" },
  "sources": [{
    "type": "filesystem",
    "id": "D:\\Daten",
    "name": "Dateiserver D:",
    "agent_id": "<agent-kennung>"
  }]
}

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

# Meldet sich der Agent?
curl -H "Authorization: Bearer <token>" https://<server>/api/v1/agents

# Was hat er zuletzt getan?
curl -H "Authorization: Bearer <token>" https://<server>/api/v1/agents/<id>/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.