Portunity Wiki - Neue Seiten [de]

Offsite-Backups mit Restic: Portunity secureBackup (S3)

Tfr@superroot — Tue, 24 Feb 2026 18:53:06 GMT

Tfr@superroot: /* S3-Bucket erzeugen */ +

= Portunity secureBackup (S3) mit restic nutzen =
== Variante A: per REST zum Restic-Server ==

Anders als bei einem klassischen FTP- oder SFTP-Zugang bietet Restic die Möglichkeit, über ein eigenes Protokoll namens REST mit einem Restic-Server zu kommunizieren. Diese Art der Verbindung ist für Datensicherungen optimiert.

Zudem stehen separate Zugangsdaten zur Verfügung, über die neue Snapshots hinzugefügt, aber bestehende nicht bearbeitet oder entfernt werden können. Dies bietet einen verbesserten Schutz gegen Ransomware und ist im Kundencenter als "Append-Only-Zugang" betitelt.

Restic benötigt Zugangsdaten bestehend aus einer URL, einem Benutzernamen und einem Server-Kennwort. Das Server-Kennwort ist <em>nicht</em> die Repository-Passphrase, die zur Ende-zu-Ende-Verschlüsselung der Daten verwendet wird. Diese fragt Restic erst bei der Einrichtung auf Ihrem Computer während des init-Befehls ab.

=== Zugang erstellen ===

Um einen Zugang zu erstellen und zu aktivieren, können Sie im Kundencenter auf [https://service.portunity.net service.portunity.net] nach Aufruf des gebuchten Produkts im Menüpunkt "Backup-Restic" folgendermaßen vorgehen:

* Öffnen Sie einen der Zugangsdaten-Kästen durch Klick auf das Dreieck
* Wählen Sie "Konto aktivieren"
* Legen Sie im Kennwort-Feld ein Kennwort für den Standard-Zugang fest
* Wählen Sie "abweichendes Append only-Kennwort aktivieren"
* Legen Sie ein Kennwort für den Append-only-Zugang fest
* Speichern Sie die Änderung durch Klick auf den grünen Knopf oben rechts

Zur Nutzung des Append-only-Zugangs werden die untere URL und das Append-only-Kennwort benötigt.

=== Restic nutzen ===

Erste Schritte mit Restic auf der Kommandozeile:

==== Repository initialisieren ====

<pre>restic -r 'rest:https://Benutzername:Kennwort@restic-rw-….portunity.de/backup1234_01' init</pre>

==== Sicherung durchführen (z.B. für den Ordner ~/Dokumente) ====

<pre>restic -r 'rest:https://Benutzername:Kennwort@restic-rw-….portunity.de/backup1234_01' backup ~/Dokumente</pre>

==== Bestehende Sicherungen auflisten ====

<pre>restic -r 'rest:https://Benutzername:Kennwort@restic-rw-….portunity.de/backup1234_01' snapshots</pre>

==== bestimmte Sicherung wiederherstellen (z.B. ID "12345ABC") ====

<pre>restic -r 'rest:https://Benutzername:Kennwort@restic-rw-….portunity.de/backup1234_01' restore 12345ABC --target ~/Wiederherstellung</pre>

== Variante B: über die S3-kompatible Schnittstelle ==

Sofern Sie nicht Restic als Backup-Software einsetzen und das noch besser dafür spezialisierte REST-Protokoll nutzen möchten, ist eine S3-kompatible Schnittstelle das Mittel der Wahl, falls Ihre Software es anbietet.

Sie können im Kundencenter auf [https://service.portunity.net service.portunity.net] nach Aufruf des gebuchten Produkts im Menüpunkt "Backup-S3" sogennante ''Buckets'' anlegen und den Zugriffsschlüssel einsehen bzw. neu generieren lassen. Die angezeigte Key-ID und der zugehörige Secret Access Key sind die Zugangsdaten für das jeweilige Bucket und müssen in der Backupsoftware hinterlegt werden.

=== S3-Bucket erzeugen ===

* Klicken Sie – sofern noch nicht geschehen – auf "Neuen Schlüssel generieren".
* Tragen Sie die danach angezeigte Key-ID und den Secret Access Key in Ihre Backupsoftware ein.
* Je nach Software wird die Angabe einer Region verlangt. Tragen Sie in diesem Fall den angezeigten Wert aus dem Feld "S3-Region" ein.

=== Restic-Beispielbefehle ===

Für die Nutzung mit der Backup-Software Restic empfehlen wir die Nutzung des Restic-Servers anstelle der S3-kompatiblen Schnittstelle. Falls Sie jedoch S3 bevorzugen, beispielsweise zur Wahrung von Kompatibilität mit anderer Software und zum Exportieren der Backup-Daten, können Sie folgende Befehle verwenden.

Die export-Befehle werden in jeder Shell-Sitzung nur einmal benötigt. Tipp: Ersetzen Sie die Zeilenumbrüche durch Semikolons, dann haben Sie eine einzige Zeile mit einem bequem erneut aufrufbaren Backup-Befehl inklusive Key-ID und Access Key.

==== Repository initialisieren ====

<pre>
export AWS_ACCESS_KEY_ID=die-angezeigte-key-id
export AWS_SECRET_ACCESS_KEY=der-angezeigte-secret-access-key
restic -r 's3:https://.....s3.portunityhosted.de/backupYYYYY-ZZ' init
</pre>

==== Sicherung durchführen (z.B. für den Ordner ~/Dokumente) ====

<pre>
export AWS_ACCESS_KEY_ID=die-angezeigte-key-id
export AWS_SECRET_ACCESS_KEY=der-angezeigte-secret-access-key
restic -r 's3:https://.....s3.portunityhosted.de/backupYYYYY-ZZ' backup ~/Dokumente
</pre>

==== Bestehende Sicherungen auflisten ====

<pre>
export AWS_ACCESS_KEY_ID=die-angezeigte-key-id
export AWS_SECRET_ACCESS_KEY=der-angezeigte-secret-access-key
restic -r 's3:https://.....s3.portunityhosted.de/backupYYYYY-ZZ' snapshots
</pre>

==== bestimmte Sicherung wiederherstellen (z.B. ID "12345ABC") ====

<pre>
export AWS_ACCESS_KEY_ID=die-angezeigte-key-id
export AWS_SECRET_ACCESS_KEY=der-angezeigte-secret-access-key
restic -r 's3:https://.....s3.portunityhosted.de/backupYYYYY-ZZ' restore 12345ABC --target ~/Wiederherstellung
</pre>

Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3/Ceph)

Lr@superroot — Fri, 09 Jan 2026 18:20:14 GMT

Tfr@superroot: hat „Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3/Ceph)“ nach „Offsite-Backups mit UniFi NAS Kopia Backup Software (Docker) Portunity secureBackup (S3)“ verschoben

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

'''''Hinweis:'''
* Wir haben das im Mitarbeiter-Kreis mit einem Unifi NAS Pro 8 getestet und dies von daher hier auch benannt. Die Anleitung ist aber allgemeingültig auch für andere NAS-Systeme wie Synology, QNAP, Windows-Freigabe, Linux Samba-Dienste u.a. und sollte dort ähnlich / gleichwertig funktionieren und stellt keine Wertung oder Empfehlung für Unifi von Ubiquiti dar.
* Auf NAS-Systemen anderer Hersteller haben Sie aber möglicherweise auch gesonderte / herstellereigene Backup-Lösungen, welche über eine 1:1 Kopie analog zu Kopia auch inkrementelle und deduplizierte Backups direkt vom NAS aus ermöglichen. Dennoch kann auch dabei Kopia Sinn machen, wenn Sie weitere Backupquellen einbinden möchten.''

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
** oder andere NAS-Systeme wie Synology, QNAP, FreeNas, Windows-Freigaben u.a.
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal. Bitte verwechsels Sie die Snapshoots auf dem NAS nicht mit den Snapshoots innerhalb von Kopia - dies sind zwei völlig getrennte Welten!

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<source lang="text">
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/backup-paperless cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</source>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<source lang="text">
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</source>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
/mnt/
backup-daten/
backup-homeassistant/
backup-kasse/
backup-paperless/
backup-restore/
</pre>

== .env (Beispiel, anonymisiert) ==
<source lang="text">
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</source>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<source lang="text">
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/backup-paperless:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</source>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<source lang="bash">
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</source>

Danach startet ihr Kopia normal:
<source lang="bash">
docker compose up -d
</source>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
Bauen Sie sich kleine Shell-Scripte und starten Sie diese per cronjob z.B. täglich:
<source lang="bash">
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</source>

Oder gezielt. Dies hat den Vorteil verschiedene Backups zu verschiedenen Zeiten starten zu können und dies mit weiteren Backupzyklen abzustimmen (z.B. HomeAssistant sichert auf das NAS um 3 Uhr nachts, von dort geht es um 5 Uhr mit Kopia weiter nach Extern):
<source lang="bash">
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</source>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.

[[Category:Hosting_Anleitungen]][[Category:Hosting]]

Offsite-Backups mit UniFi NAS + Kopia Backup Software (Docker) + Portunity secureBackup (S3/Ceph)

Lr@superroot — Fri, 09 Jan 2026 18:19:13 GMT

Lr@superroot: Erste Version der Kopia-Backup Anleitung by Lea

= Zielbild (kurz) =
Dieses Setup kombiniert zwei Dinge:
* '''Schnelle lokale Wiederherstellung''' über Snapshots auf dem UniFi NAS (für „Mist gebaut / Datei versehentlich gelöscht“).
* '''Echte externe Datensicherung (Offsite)''' über Kopia-Snapshots in ein Portunity Secure-Backup S3-Bucket (Ceph/RGW) – inkrementell, dedupliziert, mit Aufbewahrungsregeln (täglich/wöchentlich/monatlich), ohne 20-fache Vollkopien.

UniFi Drive/Unifi UNAS Pro 8 & Co bietet aktuell primär Backup als '''1:1-Kopie''' (Delta bezogen auf Dateien). Für längere Historien und „richtige“ Snapshot-Backups mit Dedupe/Encryption setzen wir deshalb Kopia auf einem separaten Docker-Host ein.

= Architektur =
'''Komponenten:'''
* '''UniFi NAS Pro 8''' mit mehreren SMB-Shares (z. B. Daten, Homeassistant, Paperless, Kasse, Media).
* '''Docker-Host''' (Linux) im gleichen Netz:
** mountet SMB-Shares read-only (quellseitig)
** stellt ein separates SMB-Share „Restore“ read-write bereit (zielseitig)
** betreibt '''Kopia als Docker-Container''' (Web-UI + Scheduler).
* '''Portunity Secure-Backup (S3 kompatibel)''' als Offsite-Ziel (Ceph Object Storage).
* '''HomeAssistant, lokales PaperLess & weitere Systeme'''
** sichern lokal zunächst 1x als 1:1 Kopie auf dem NAS, z.B. Paperless-Exporter via Cronjob, via Cronjob über Rsync o.ä.
** bzw. legen ihre von Haus aus möglichen Sicherungen auf einem Share ab, z.B. HomeAssistant, Registrierkassen o.ä. haben ein integriertes Backup, z.B. täglich für X Tage o.üä.

'''Warum read-only Mounts?'''
Der Backup-Host soll im Normalbetrieb keine Produktivdaten verändern können. Restore erfolgt bewusst über ein separates Restore-Ziel.

== UniFi NAS: Shares & lokale Snapshots ==
Auf dem UniFi NAS werden die Shares wie gewohnt angelegt. Lokale Snapshots sind optional, aber sehr praktisch.

'''Wichtiger Hinweis zur UniFi-Snapshot-Logik:'''
Pro Share ist in der UI typischerweise '''nur ein Snapshot-Schedule''' möglich (z. B. täglich ODER wöchentlich). Deshalb empfehlen wir:
* Produktiv-Shares (z. B. Daten, Paperless): '''täglich''' (z. B. 30–90 Versionen)
* Reine Backup-Shares (z. B. Backup_Paperless, Backup_Homeassistant): '''wöchentlich''' (z. B. 8–12)
* Große, „nice-to-have“ Daten (z. B. Media/Filmarchive): optional keine lokalen Snapshots

Das ersetzt keine Offsite-Sicherung, ist aber für schnelle Rollbacks ideal.

= Portunity secureBackup (S3): Zugangsdaten finden =
Im Portunity Webinterface finden Sie pro Vertrag/Produkt eine „S3-kompatible Schnittstelle“ mit der Möglichkeit einen oder mehrere Buckets anzulegen.

'''Screenshot (Beispiel):'''
[[Datei:secure-backup-s3-schnittstelle.jpg|800px|thumb|Portunity Secure-Backup – S3-Schnittstelle (Beispielansicht).]]

'''Welche Felder braucht Kopia?'''
* '''S3-Bucket''' → Kopia Parameter: <code>--bucket</code>
* '''Key-ID''' → Environment: <code>AWS_ACCESS_KEY_ID</code> / <code>S3_ACCESS_KEY</code>
* '''Secret Access Key''' → Environment: <code>AWS_SECRET_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code>
* '''S3-Region''' → Kopia Parameter: <code>--region</code>
* '''S3-Pfad / Endpoint''' → Kopia Parameter: <code>--endpoint</code>

'''Wichtig (Stolperfalle):'''
Bei Kopia muss <code>--endpoint</code> '''nur der Hostname''' sein (ohne https:// und ohne /bucket-Pfad via bei Portunity ausgegeben mit s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01).
Beispiel:
* korrekt: <code>--endpoint=avcd123456.s3.backup1.portunityhosted.de</code>
* falsch: <code>--endpoint=s3://avcd123456.s3.backup1.portunityhosted.de/backup00000001-01</code>

= Docker-Host: SMB-Mounts vorbereiten =
Wir mounten die UniFi-Shares auf dem Docker-Host unter <code>/mnt</code>. Quellen sind read-only, Restore ist read-write.

== Beispiel-Verzeichnislayout ==
<pre>
/mnt/backup-daten (ro) -> UniFi Share "Daten"
/mnt/backup-homeassistant (ro) -> UniFi Share "Backup_Homeassistant"
/mnt/backup-kasse (ro) -> UniFi Share "Backup_Kasse"
/mnt/paperless-backup (ro) -> UniFi Share "Backup_Paperless"
/mnt/backup-restore (rw) -> UniFi Share "Backup_Restore" (oder ähnlicher Name)
</pre>

== Mount per /etc/fstab (Beispiel) ==
<pre>
# Credentials-Dateien sollten root-only sein (chmod 600)
# Beispiel: /etc/samba/cred_backup-daten

//192.168.220.3/Daten /mnt/backup-daten cifs credentials=/etc/samba/cred_backup-daten,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Homeassistant /mnt/backup-homeassistant cifs credentials=/etc/samba/cred_backup-ha,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Kasse /mnt/backup-kasse cifs credentials=/etc/samba/cred_backup-kasse,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0
//192.168.220.3/Backup_Paperless /mnt/paperless-backup cifs credentials=/etc/samba/cred_backup-paperless,vers=3.0,iocharset=utf8,ro,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0555,file_mode=0444 0 0

//192.168.220.3/Backup_Restore /mnt/backup-restore cifs credentials=/etc/samba/cred_backup-restore,vers=3.0,iocharset=utf8,rw,nofail,x-systemd.automount,uid=1000,gid=1000,dir_mode=0770,file_mode=0660 0 0
</pre>

'''Hinweis:''' uid und gid sollten auf einen angelegten User und Gruppe von der ID passend sein, so dass Kopia an die Daten auch dran kommt. Am besten der selbe User, unter dem von Kopia auch der Doccer dann läuft.

'''Credentials-Datei (Beispiel):'''
<pre>
username=BACKUPUSER
password=SUPERGEHEIM
domain=WORKGROUP
</pre>

= Kopia in Docker installieren =
Wir betreiben Kopia als Container mit:
* persistenter Config/Cache/Logs auf dem Host
* read-only Sources (SMB-Mounts)
* separatem Restore-Ziel (rw)
* Web-UI via Reverse Proxy (empfohlen: TLS)

== Ordnerstruktur ==
<pre>
/home/kopia/kopia/
docker-compose.yml
.env
config/
cache/
logs/
</pre>

== .env (Beispiel, anonymisiert) ==
<pre>
# Repository-Passwort (verschlüsselt ALLES im Repo; unbedingt sicher verwahren!)
KOPIA_PASSWORD=RANDOM-LONG-PASSPHRASE

# Web-UI Login für Kopia-Server (nur UI/API Zugriff, NICHT die Repo-Verschlüsselung)
KOPIA_UI_USER=admnin
KOPIA_UI_PASS=RANDOM-UI-PASSWORD

# Portunity Secure-Backup (S3/Ceph)
S3_ACCESS_KEY=AKIAxxxxxxxxxxxxxxxx
S3_SECRET_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>

'''Warum drei Passwörter?'''
* <code>KOPIA_PASSWORD</code> ist das '''Repository-Passwort''' (Key-Derivation/Encryption) – ohne dieses Passwort ist das Backup praktisch unlesbar. Mit diesem Passwort werden die Daten bei Portunity im secureBackup Speicher (=Repository) verschlüsselt. Bitte speichern Sie sich das Passwort sicher in Ihrem Passwort-Tresor oder Offline irgendwo sicher. Sollte der Docker-Host lokal ausfallen kommen Sie ohne dieses Passwort nicht mehr an Ihre gesicherten Daten lesbar heran.
* <code>KOPIA_UI_USER</code>/<code>KOPIA_UI_PASS</code> ist der '''Login für den Kopia-Server''' für das lokale Web-UI und die API. Das schützt den Zugriff auf die Bedienoberfläche, ändert aber nicht die Verschlüsselung im Repository bei Portunity.
* <code>S3_ACCESS_KEY</code> / <code>S3_SECRET_KEY</code> sind die Zugangsdaten zum angelegten s3-Bucket vom Portunity secureBackup.

== docker-compose.yml (Beispiel) ==
<pre>
services:
kopia:
image: kopia/kopia:latest
container_name: kopia
restart: unless-stopped
ports:
- "51515:51515"
environment:
TZ: Europe/Berlin

# WICHTIG: Config-Pfad zeigt auf eine Datei, nicht auf ein Verzeichnis
KOPIA_CONFIG_PATH: /app/config/kopia.config
KOPIA_CACHE_DIRECTORY: /app/cache
KOPIA_LOG_DIR: /app/logs

KOPIA_PASSWORD: "${KOPIA_PASSWORD}"
AWS_ACCESS_KEY_ID: "${S3_ACCESS_KEY}"
AWS_SECRET_ACCESS_KEY: "${S3_SECRET_KEY}"

volumes:
- ./config:/app/config
- ./cache:/app/cache
- ./logs:/app/logs

# Quellen (read-only)
- /mnt/backup-daten:/sources/Daten:ro
- /mnt/paperless-backup:/sources/Paperless:ro
- /mnt/backup-homeassistant:/sources/Homeassistant:ro
- /mnt/backup-kasse:/sources/Kasse:ro

# Restore-Ziel (read-write)
- /mnt/backup-restore:/restore:rw

command:
- server
- start
- --address=0.0.0.0:51515
- --insecure
- --server-username=${KOPIA_UI_USER}
- --server-password=${KOPIA_UI_PASS}
</pre>

'''Hinweis zu --insecure:'''
Kopia spricht dann HTTP ohne eigene TLS-Verschlüsselung. Das ist ok, wenn davor ein Reverse Proxy mit HTTPS-Termination sitzt - was wir empfehlen (z.B. NGIX / TRAEFIK). Ohne Proxy sollte Kopia selbst mit TLS betrieben werden.

= Repository im Portunity S3 initialisieren =
Das Repository wird einmalig im S3-Speicher vom Portunity secureBackup angelegt. Beispiel:

<pre>
cd /home/kopia/kopia

docker compose run --rm kopia \
repository create s3 \
--config-file=/app/config/kopia.config \
--bucket=MEIN_BUCKET_NAME \
--endpoint=s3.backup1.portunityhosted.de \
--region=eu-wup-2 \
--prefix=kopiahost1
</pre>

Danach startet ihr Kopia normal:
<pre>
docker compose up -d
</pre>

= Snapshots & Policies (GFS-Logik) =
Kopia-Snapshots werden in der Web-UI erstellt. Wichtig: In der Kopia-UI wählt ihr die '''Container-Pfade''' unter <code>/sources/…</code>, nicht die Host-Mounts unter <code>/mnt</code>.

Beispiele:
* <code>/sources/Homeassistant</code>
* <code>/sources/Kasse</code>
* <code>/sources/Paperless</code>
* <code>/sources/Daten</code>

Empfehlung für Policies:
* Homeassistant/Kasse: eher häufige Snapshots (z. B. täglich + wöchentlich), da viele kleine Änderungen.
* Daten/Paperless: täglich + wöchentlich + monatlich (je nach Datenwert).
* Große Media-Archive: meist auslassen oder separate Strategie.

= Restore-Konzept =
Restore läuft bewusst über ein separates Ziel (Share <code>Backup_Restore</code>):
1. In Kopia Web-UI Snapshot auswählen
2. Datei/Ordner nach <code>/restore</code> oder <code>/restore/backup-homeassistant-vom-11.12.2033</code> wiederherstellen
3. Von dort aus gezielt zurück in die Produktiv-Shares kopieren (manuell/skriptgesteuert)

Vorteile:
* Backup-Host braucht für Quellen nur read-only
* Restore ist nachvollziehbar und kontrolliert
* Kein „aus Versehen“ Überschreiben in Produktivpfaden

= Automatisierung =
Kopia kann Snapshots über die Web-UI als Tasks planen. Alternativ lässt sich per Cron triggern.

== Snapshot per Cron anstoßen (Beispiel) ==
<pre>
# alle konfigurierten Snapshot-Quellen einmal sichern:
docker compose exec -T kopia kopia snapshot create --all
</pre>

Oder gezielt:
<pre>
docker compose exec -T kopia kopia snapshot create /sources/Homeassistant
</pre>

= Betrieb & Praxis-Tipps =
* '''Monitoring:''' regelmäßig ins Kopia UI „Tasks“/„Maintenance“ schauen; Logs liegen zusätzlich im Host-Verzeichnis <code>/home/kopia/kopia/logs</code>.
* '''Repository-Passwort sicher verwahren:''' Ohne <code>KOPIA_PASSWORD</code> ist ein Restore nicht möglich.
* '''Netz/Firewall:''' Port 51515 am Docker-Host nur intern freigeben. Externer Zugriff idealerweise per VPN.
* '''TLS für komfortablen Zugriff:''' Reverse Proxy (z. B. Nginx Proxy Manager) + internes Zertifikat (z. B. Let’s Encrypt via DNS-01 oder interne CA).
* '''Dedup/Inkremenz:''' Kopia arbeitet blockbasiert; wiederkehrende Daten (z. B. ähnliche HA-Backups) werden sehr effizient gespeichert.

= Troubleshooting =
'''Kopia startet nicht / Config-Fehler'''
Wenn im Log sowas steht wie „config json … is a directory“: <code>KOPIA_CONFIG_PATH</code> muss eine Datei sein (z. B. <code>/app/config/kopia.config</code>), nicht ein Ordner.

'''S3 Endpoint Fehler'''
Wenn „Endpoint url cannot have fully qualified paths“: <code>--endpoint</code> darf keinen <code>/bucket</code> enthalten.

'''Restore scheitert wegen Dateinamen/Path-Limits (SMB)'''
Sehr lange Pfade können auf manchen SMB/NAS Kombinationen Probleme machen. Dann Restore erst nach <code>/restore</code> (lokal oder anderes Ziel) und anschließend mit angepasster Struktur zurückkopieren.