Jerrit Fritzsche
610719c316
Enterprise-Backup-, Recovery-, Verification-, Security- und Monitoring-Plattform fuer Proxmox VE, Windows, Linux und Dateisysteme. Der Leitsatz, der fast jede Entscheidung erklaert: Ein Backup gilt erst als vertrauenswuerdig, wenn Integritaet geprueft und Wiederherstellbarkeit nachgewiesen wurde. Deshalb steigt ein Wiederherstellungspunkt erst nach einem tatsaechlich durchgefuehrten Restore-Test auf "recoverable", und Unbekanntes geht in keine Bewertung als "gut" ein. Umfang (Phasen 0-23): - Repository Engine: inhaltsadressierte Bloecke, atomares Commit-Protokoll, Katalogaufbau allein aus den Manifesten — ohne Datenbank - Backup Engine: inhaltsabhaengiges Chunking, Deduplizierung trotz Verschluesselung, zstd, AES-256-GCM, Streaming mit Gegendruck - Agenten fuer Windows und Linux mit Auftragsabholung (Pull-Modell) - Proxmox-Provider mit beiden Zugriffswegen auf die Sicherungsarchive - Scheduler, Recovery Engine mit Pruefpunkt, Verification, Unveraenderlichkeit - Weboberflaeche, Kennzahlen, Meldungen, Berichte, Security Center, Ransomware-Heuristik (meldet, handelt nie) - Disaster Recovery, Haertung, Leistungsmessung, Chaos Testing - Eingefrorene Vertraege fuer API, Migrationen, Backup-Format und Repository - Auslieferungspaket fuer linux/amd64, linux/arm64 und windows/amd64 Nicht enthalten und als solches gekennzeichnet: Kapazitaetsprognose, Backup Copy, Changed Block Tracking bei Proxmox, erweiterte Attribute und ACLs. Gebaut, aber nie auf echter Hardware gefahren: der Windows-Dienst, die systemd-Einheit und der verpflichtende Proxmox-Meilenstein — ob eine wiederhergestellte VM startet, ist ungeprueft. Einzelheiten in CHANGELOG.md und docs/release-candidate.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
214 lines
7.6 KiB
Markdown
214 lines
7.6 KiB
Markdown
# 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.
|