Installation unter Linux und macOS

Den Restow-Agent installieren Sie mit einem einzigen Befehl, den Restow für Sie erzeugt. Neben dem Befehl zeigt Restow ein einmaliges Token, nach dem das Installationsskript mit verdeckter Eingabe fragt. So steht das Token nie in einer Kommandozeile, und weitere Zugangsdaten tippen Sie auf dem Rechner nie ein.

Voraussetzungen

Auf dem Rechner

Linux: systemd, x86_64 oder aarch64, Root-Rechte (sudo), curl sowie sha256sum oder shasum. Für die Prüfung der Release-Signatur ssh-keygen aus OpenSSH 8.1 oder neuer oder OpenSSL 3. Debian ab 11, Ubuntu ab 20.04 und RHEL 9 bringen das mit. Für Systeme ohne beides siehe Systeme ohne Signaturwerkzeug.
macOS: macOS 13 (Ventura) oder neuer, Intel oder Apple Silicon, ein Administratorkonto (sudo) und curl. Das ssh-keygen jedes unterstützten macOS prüft die Release-Signatur.
HTTPS zu Restow. Der Rechner muss Ihre Restow-Instanz per HTTPS erreichen. Der Agent verbindet sich nur ausgehend. Ein eingehender Port wird weder gebraucht noch geöffnet.
Eine richtige Uhrzeit. Zertifikatsprüfungen scheitern auf einem Rechner, dessen Uhr stark abweicht.
Ein vertrauenswürdiges Zertifikat. Der Agent nutzt den Zertifikatsspeicher des Betriebssystems. Verwendet Ihre Instanz ein Zertifikat einer privaten Zertifizierungsstelle, muss diese CA in diesem Speicher liegen oder, unter Linux, in einer Datei, die SSL_CERT_FILE nennt (siehe Proxy und private CA). Der Agent hat dafür keine eigene Einstellung.

In Restow

Setzen Sie die öffentliche URL Ihrer Installation in den Einstellungen. Die Adresse im Installationsbefehl stammt daraus. Ist keine gesetzt, nimmt Restow die Adresse Ihres Browsers und warnt Sie, und der Rechner muss genau diese Adresse erreichen können.
Verwenden Sie eine https://-Adresse. Die Installationsskripte weisen eine Instanz mit reinem http:// ab. Die Oberfläche warnt Sie vor einer unverschlüsselten Adresse, bevor Sie einen Rechner verbinden, weil das Token und die Geheimnisse des Agents unverschlüsselt übertragen würden.

Den Installationsbefehl erstellen

Öffnen Sie Server & Clients → Inventar. Die Chips Alle, Server und Clients filtern die Liste.
Wählen Sie Neuer Server oder Neuer Client.
Wählen Sie das Betriebssystem: Linux oder macOS. Windows wird als „Geplant“ angezeigt und lässt sich nicht wählen.
Geben Sie dem Rechner optional einen Namen. Er wird in den Listen statt des Hostnamens angezeigt, und Sie können ihn später ändern.
Wählen Sie Installationsbefehl erstellen.

Das Fenster zeigt den Installationsbefehl und darunter das Token, jeweils mit eigener Schaltfläche zum Kopieren. Außerdem zeigt es den Befehl für eine unbeaufsichtigte Installation und die Befehle, um den Agent später zu entfernen. Das Fenster zeigt, wann sich der Rechner verbunden hat. Sie können es schließen und den Rechner später in der Liste finden.

Das Token wird nur einmal angezeigt und lässt sich nach dem Schließen des Fensters nicht mehr anzeigen. Haben Sie es verloren, erstellen Sie einen neuen Befehl. Befehle, die noch niemand verwendet hat, stehen unter Offene Anmeldungen, wo Sie sie widerrufen können.

Dieselben Schaltflächen, Neuer Server und Neuer Client, finden Sie unter Mandanten-Einstellungen → Agenten, neben den offenen Befehlen, dem Schalter für automatische Agent-Updates und, seit 0.4.0, der Richtlinie der Agenten des Mandanten.

Den Befehl ausführen

Führen Sie ihn auf dem Rechner aus, den Sie sichern wollen.

# Linux
curl -fsSL 'https://<your instance>/install/linux.sh' | sudo sh
# macOS
curl -fsSL 'https://<your instance>/install/macos.sh' | sudo sh

Restow trägt die Adresse Ihrer Instanz ein, wenn es Ihnen den Befehl anzeigt. Fragt das Skript nach dem Token, fügen Sie das Token aus dem Fenster ein. Die Eingabe bleibt verborgen.

Unbeaufsichtigte Installation (RMM, MDM, Skripte)

Ohne Terminal für die Eingabe liest das Skript das Token aus einer Datei, die nur root lesen kann. Schreiben Sie das Token in die Datei (Modus 0600, Eigentümer root), führen Sie den Befehl aus und löschen Sie die Datei danach.

# Linux
curl -fsSL 'https://<your instance>/install/linux.sh' | sudo RESTOW_TOKEN_FILE=/root/restow-enrollment.token sh
# macOS (der Home-Ordner von root ist /var/root)
curl -fsSL 'https://<your instance>/install/macos.sh' | sudo RESTOW_TOKEN_FILE=/var/root/restow-enrollment.token sh

Um die Datei unter Linux von Hand zu schreiben, führen Sie sudo sh -c 'umask 077; cat > /root/restow-enrollment.token' aus, fügen das Token ein und drücken Enter und danach Strg+D (unter macOS mit /var/root/restow-enrollment.token). Das Skript liest die erste Zeile der Datei und warnt, wenn andere Benutzer sie lesen können. Löschen Sie die Datei nach der Installation, zum Beispiel mit sudo rm /root/restow-enrollment.token.

Was das Skript tut

Das Skript liefert Ihre eigene Instanz aus, mit eingetragener Adresse, Agent-Version und dem öffentlichen Schlüssel der Agent-Releases.

Es erkennt die CPU-Architektur und lädt SHA256SUMS, die zugehörige Signatur SHA256SUMS.sig, restow-agent, restic und die Lizenzhinweise THIRD_PARTY_NOTICES.txt von <instance>/install/agent/<version>/. Die Dateien kommen von Ihrer Instanz, nicht aus dem Internet.
Bevor es irgendetwas ausführt, prüft es die Signatur des Maintainers über SHA256SUMS und danach das SHA-256 beider Binärdateien und der Lizenzhinweise gegen SHA256SUMS. Es gibt den Fingerabdruck des Release-Schlüssels aus, gegen den es geprüft hat (signature: OK (release key SHA256:...)). Ein unsigniertes Release, eine falsche Signatur oder eine abweichende Prüfsumme beendet das Skript, und nichts wird installiert. Siehe Signierte Releases.
Es prüft, dass jeder Ordner des Installationsorts root gehört und weder für die Gruppe noch für andere schreibbar ist, und verweigert sonst die Installation. Dann installiert es restow-agent und restic nach /opt/restow-agent/bin unter Linux bzw. /Library/Application Support/Restow/bin unter macOS, zuerst unter Zufallsnamen abgelegt und dann an ihren Platz umbenannt, und die Lizenzhinweise neben diesen Ordner als THIRD_PARTY_NOTICES.txt.
Es installiert und aktiviert den Dienst: die systemd-Unit restow-agent.service unter Linux, den LaunchDaemon com.restowbackup.agent unter macOS. Es verlinkt /usr/local/bin/restow-agent auf den Agent, aber nur, wenn /usr/local/bin root gehört.
Es führt restow-agent enroll aus. Das tauscht das Token gegen Zugangsdaten und prüft, dass die Instanz und das Backup-Repository sie annehmen. Das Skript übergibt das Token diesem einen Befehl in seiner Umgebung, nie in einer Kommandozeile.
Es startet den Dienst und gibt den Status aus.

Das Token

Es ist 24 Stunden gültig und lässt sich einmal verwenden.
Restow speichert nur einen SHA-256-Hash davon.
Es steht nicht im Befehl. Das Skript liest es mit verdeckter Eingabe oder aus der Token-Datei, die nur root lesen kann. So erscheint es weder in einer Kommandozeile noch in der Prozessliste oder der Shell-Historie. Es wird nie ausgegeben.
RESTOW_TOKEN in der Umgebung funktioniert ebenfalls, zum Beispiel in einer Root-Shell. Vermeiden Sie sudo RESTOW_TOKEN=... sh: Diese Form legt das Token in die Prozessliste des Rechners, solange der Befehl läuft.
Scheitert das Enrollment auf der Serverseite (zum Beispiel weil das Speicherziel nicht erreichbar ist), macht der Server alles rückgängig und gibt das Token wieder frei. Sie können denselben Befehl erneut ausführen. Auch eine ungültige Anfrage (zum Beispiel ein leerer Hostname) verbraucht das Token nicht.

Hooks bei der Installation

Befehle vor und nach dem Backup (Hooks) laufen als root, deshalb entscheidet der Rechner, ob er sie ausführt. Auf einem neuen Rechner sind sie aus. Um sie schon bei der Installation zu erlauben, hängen Sie --hooks=scripts (nur Skripte in /etc/restow-agent/hooks.d) oder --hooks=any (beliebige Befehle) an:

curl -fsSL 'https://<your instance>/install/linux.sh' | sudo sh -s -- --hooks=scripts

--hooks=off schaltet sie aus. Später ändern Sie die Regel auf dem Rechner mit sudo restow-agent hooks ....

Erneutes Ausführen ist sicher

Sie können den Befehl jederzeit erneut ausführen. Er repariert oder aktualisiert die Installation an Ort und Stelle, behält ein vorhandenes Enrollment und installiert nie doppelt. Auf einem Rechner, der schon angemeldet ist, wird das Token nicht gebraucht. Mit --hooks=... setzt er außerdem die Hook-Regel des angemeldeten Rechners.

Signierte Releases

Jedes Agent-Release (Agent und restic, für jede Plattform) ist vom Maintainer mit einem Ed25519-Schlüssel im OpenSSH-Signaturformat signiert. Die Signatur deckt die SHA256SUMS des Releases ab, die das SHA-256 jeder Binärdatei auflistet. Der öffentliche Schlüssel ist in den Agent einkompiliert und steht in den Installationsskripten. Das Installationsskript prüft die Signatur mit ssh-keygen -Y verify (OpenSSH 8.1 oder neuer) oder mit OpenSSL 3. Der Agent installiert nur Updates, die mit diesem Schlüssel signiert sind.

Den Fingerabdruck des Release-Schlüssels vergleichen

Die erste Installation vertraut dem Installationsskript, das Ihre Instanz ausliefert, wie bei jedem curl | sh. Um ein verändertes Skript auszuschließen, vergleichen Sie den Fingerabdruck, den das Skript in der Zeile signature: OK (release key SHA256:...) ausgibt, mit dem Fingerabdruck des Agent-Release-Schlüssels (ED25519, Schlüsselname restow-agent-release), der auch in den Release Notes der Version steht:

SHA256:2LB7RPpIS0wqbcZ2NA8MjuQN7ZfFPqBX3CwrGFSu76o

Weichen sie voneinander ab, nutzen Sie die Installation nicht: Entfernen Sie den Agent wieder (siehe Deinstallation) und prüfen Sie Ihre Instanz.

Systeme ohne Signaturwerkzeug

RHEL, Rocky Linux und AlmaLinux 8 sowie Amazon Linux 2 haben weder OpenSSH 8.1 noch OpenSSL 3. Das Skript bricht dort mit einer Erklärung ab und installiert nichts. Prüfen Sie die Signatur stattdessen auf einem anderen Rechner und geben Sie dem Skript das SHA-256 der geprüften SHA256SUMS:

Laden Sie auf einem Rechner mit OpenSSH 8.1 oder neuer SHA256SUMS und SHA256SUMS.sig von https://<your instance>/install/agent/<version>/ herunter (das GitHub-Release enthält dieselben Dateien als agent-SHA256SUMS und agent-SHA256SUMS.sig), dazu den öffentlichen Schlüssel agent/release-signing.pub aus dem Quellcode zum Release-Tag.

Prüfen Sie Schlüssel und Signatur und bilden Sie das SHA-256 der geprüften Datei:

ssh-keygen -l -f release-signing.pub    # muss SHA256:2LB7RPpIS0wqbcZ2NA8MjuQN7ZfFPqBX3CwrGFSu76o ausgeben
printf 'restow-agent-release %s\n' "$(cut -d ' ' -f 1-2 release-signing.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I restow-agent-release -n restow-agent-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum SHA256SUMS                    # unter macOS: shasum -a 256 SHA256SUMS

Übergeben Sie den Wert auf dem Rechner, den Sie sichern wollen, an das Skript:

curl -fsSL 'https://<your instance>/install/linux.sh' | sudo RESTOW_SHA256SUMS_SHA256=<sha256 of SHA256SUMS> sh

Das Skript nimmt dann nur eine SHA256SUMS mit genau diesem Hash an und prüft beide Binärdateien dagegen. Der Agent selbst prüft Signaturen ohne externes Werkzeug, seine Updates funktionieren auf diesen Systemen also. Wie Sie die Dateien eines Releases allgemein prüfen, steht unter Ein Release verifizieren.

macOS: Vollzugriff auf die Festplatte erteilen

macOS schützt Schreibtisch, Dokumente, Downloads, iCloud Drive und weitere Ordner. Ohne Zugriff überspringt der Agent diese Dateien, das Backup endet als Teilweise, und das Lauf-Protokoll sagt das.

Öffnen Sie System Settings > Privacy & Security > Full Disk Access. Die Bezeichnungen stehen hier englisch. In der deutschen Systemsprache heißen die Einträge entsprechend anders.
Fügen Sie /Library/Application Support/Restow/bin/restow-agent hinzu. Im Dateidialog öffnet Cmd+Shift+G ein Feld, in das Sie den Pfad einfügen können.
Werden danach weiterhin geschützte Ordner gemeldet, fügen Sie zusätzlich /Library/Application Support/Restow/bin/restic hinzu.

Das nächste Backup enthält diese Dateien dann.

Auf Macs, die über MDM verwaltet werden, verteilen Sie stattdessen ein Privacy Preferences Policy Control Profil. Es erteilt denselben Zugriff, ohne dass jemand durch die Systemeinstellungen klicken muss.

Den Status prüfen

Auf dem Rechner:

restow-agent status

Der Befehl zeigt den lokalen Zustand und braucht keine Root-Rechte. Mit sudo zeigt er außerdem die Hook-Regel, weil nur root das Enrollment lesen kann. Er nennt die laufende Binärdatei und sagt es, wenn die Installation nicht sicher ist. Seit 0.4.0 zeigt er außerdem die geltende Richtlinie der Agenten (Policy, nur was vom Standard abweicht) und, wenn eine fällige Sicherung wartet, warum (Waiting). --json liefert dasselbe für Skripte. In Restow erscheint der Endpoint in der Liste, und sein Status wechselt nach dem ersten Kontakt auf Online.

Der Befehl restow-agent ist der Link in /usr/local/bin, den das Skript nur anlegt, wenn dieser Ordner root gehört (auf einem Intel-Mac mit Homebrew gehört er einem Benutzer, dort gibt es keinen Link). Der volle Pfad funktioniert immer:

# Linux
sudo /opt/restow-agent/bin/restow-agent status
# macOS
sudo '/Library/Application Support/Restow/bin/restow-agent' status

Seit 0.2.1 wird ein frisch angemeldeter Rechner erst gesichert, wenn er Mitglied eines Backup-Jobs ist: Bis dahin markiert ihn das Inventar mit Ohne Backup und bietet Job anlegen und Zu Job hinzufügen… an. Ist er in einem Job, folgt er dessen Zeitplan. Um das erste Backup sofort zu starten, öffnen Sie den Rechner unter Server & Clients → Inventar und wählen Jetzt sichern. Der Rechner holt die Anfrage bei seinem nächsten Kontakt ab, meist innerhalb weniger Minuten. Pausiert gerade ein Restow-Update neue Läufe, bleibt die Anfrage auf dem Server in der Warteschlange, bis die Pause vorbei ist.

Kommandozeile

restow-agent enroll        Enroll this machine (RESTOW_TOKEN and RESTOW_URL from the environment)
restow-agent run           The service main loop (what systemd / launchd execute)
restow-agent status        Local state, no root needed (--json for scripts)
restow-agent backup-now    Run one backup in the foreground (exit 0 ok, 3 partial, 1 failed)
restow-agent update        Install the release the server offers, at once (since 0.4.2)
restow-agent service ...   install | start | stop | restart | status
restow-agent hooks ...     status | off | scripts | any: whether hooks from the server run here
restow-agent uninstall     Remove the agent (--yes, --keep-logs)
restow-agent version       Version, commit, build date (--short for the number only)

Die Ausgabe des Agents ist englisch. Zur Orientierung: enroll meldet den Rechner an, run ist die Hauptschleife des Dienstes, status zeigt den lokalen Zustand, backup-now führt ein Backup im Vordergrund aus (Exit-Code 0 erfolgreich, 3 teilweise, 1 fehlgeschlagen; es wartet, solange ein Update neue Läufe pausiert), update installiert das Release, das der Server anbietet, sofort (seit 0.4.2), service steuert den Dienst, hooks legt fest, ob Hooks vom Server hier laufen, uninstall entfernt den Agent, version zeigt die Version.

Seit 0.4.2 installiert update das Release, das Ihre Instanz anbietet, sofort, wie restow-pve update auf einem Proxmox-VE-Knoten: Die signierte SHA256SUMS wird mit dem im Agent eingebauten Schlüssel geprüft, dann jede Datei gegen ihren signierten Hash, und erst danach wird etwas ersetzt. Es startet den Dienst neu, damit die neue Version läuft, und sagt, was es getan hat (aktualisiert von und auf, oder „No newer release is offered“). Es hält die Lauf-Sperre, solange es arbeitet, sodass keine Sicherung startet. Solange eine Sicherung, eine Wiederherstellung oder ein Restore-Test läuft, lehnt es ab („A backup is running; the update waits“, Exit-Code 1), und der Dienst installiert das Update selbst, sobald er frei ist. Führen Sie es als root aus (sudo).
--debug oder RESTOW_DEBUG=1 schaltet ausführliches Logging ein.
enroll --force meldet den Rechner mit einem neuen Token erneut an. Der alte Endpoint bleibt in Restow, bis Sie ihn sperren, und seine Backups bleiben gespeichert, bis Sie ihn aus Restow entfernen und sie löschen. Siehe Deinstallation.
enroll --hooks=off|scripts|any setzt die Hook-Regel einer neuen Anmeldung (Standard off). Eine erneute Anmeldung eines angemeldeten Rechners behält seine Regel.
hooks braucht Root-Rechte. Siehe Profile, Zeitplan und Hooks.
enroll --allow-insecure-http gibt es nur für die lokale Entwicklung. Die Installationsskripte verweigern es, außer RESTOW_ALLOW_INSECURE_HTTP=1 ist gesetzt, und der Agent gibt jedes Mal eine Warnung aus.

Dateien

Pfad	Inhalt
`/opt/restow-agent/bin/restow-agent`, `/opt/restow-agent/bin/restic` (macOS: `/Library/Application Support/Restow/bin/`)	Die Binärdateien, in einem Ordner, den nur root ändern kann. `restow-agent.prev` ist der vorherige Agent nach einem Update.
`/opt/restow-agent/THIRD_PARTY_NOTICES.txt` (macOS: `/Library/Application Support/Restow/THIRD_PARTY_NOTICES.txt`)	Die Lizenzhinweise des Agents, von Go, von restic und von den Go-Modulen, die in restic einkompiliert sind. Für alle lesbar, wie die Binärdateien gegen die signierte `SHA256SUMS` geprüft, bei jedem Selbst-Update ersetzt.
`/usr/local/bin/restow-agent`	Ein Link auf den Agent für Administratoren, nur wenn `/usr/local/bin` root gehört.
`/etc/restow-agent/state.json`	Enrollment: Instanz-URL, Endpoint-ID, Agent-Secret, Repository-URL und -Passwort, Hook-Regel. Modus 0600.
`/etc/restow-agent/hooks.d/`	Die Hook-Skripte, die root für die Regel `scripts` freigegeben hat.
`/var/lib/restow-agent/status.json`	Laufzeitstatus für `restow-agent status`. Keine Geheimnisse.
`/var/lib/restow-agent/cache`	Der restic-Cache. Er enthält Metadaten des Repositorys, kann bei großen Repositorys auf einige GB wachsen und darf gelöscht werden.
`/var/lib/restow-agent/{tmp,restic-tmp,outbox}`	Temporäre Restore-Kopien, restic-Optionsdateien und Lauf-Berichte, die noch nicht zugestellt werden konnten.
`/var/log/restow-agent/agent.log`	Das Agent-Log, bei 5 MB rotiert, 3 Dateien bleiben erhalten. Unter Linux steht es auch im Journal. Unter macOS enthält `launchd.log` Absturzspuren.
`/etc/systemd/system/restow-agent.service`	Die systemd-Unit (Linux).
`/Library/LaunchDaemons/com.restowbackup.agent.plist`	Der LaunchDaemon (macOS).

Proxy und private CA

Der Agent reicht Proxy-Einstellungen und ein privates CA-Bundle weiter, wenn sie in der Umgebung des Dienstes gesetzt sind. Die Variablen heißen HTTPS_PROXY, NO_PROXY und, unter Linux, SSL_CERT_FILE. Unter Linux setzen Sie sie mit einem systemd-Drop-in:

sudo systemctl edit restow-agent

Tragen Sie zum Beispiel ein:

[Service]
Environment="HTTPS_PROXY=http://proxy.example.com:3128"
Environment="NO_PROXY=localhost,127.0.0.1"
Environment="SSL_CERT_FILE=/etc/ssl/certs/company-ca.pem"

Starten Sie den Dienst danach neu:

sudo systemctl restart restow-agent

Eine private CA in den Zertifikatsspeicher des Betriebssystems aufzunehmen, ist der einfachere Weg, wenn Sie es können. Dieselben Variablen erreichen auch restic und Ihre Hooks, weil sie auf der kurzen Liste der Variablen stehen, die der Agent weitergibt.

Nach der Installation

Profile, Zeitplan und Hooks: festlegen, was gesichert wird und wann.
Fehlerbehebung: wenn das Skript oder das erste Backup nicht funktioniert.