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

```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://<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

```powershell
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:

```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:<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:

```powershell
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

```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://<server> --token <aufnahme-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:<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:

```json
{
  "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

```bash
# 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.