Gerät hinzufügen

Der PiPort-Agent ist ein kleiner Dienst auf deinem Gerät. Er hält eine ausgehende, verschlüsselte Verbindung zu PiPort, sodass du das Gerät von überall erreichst, ohne Ports zu öffnen.

Unterstützte Systeme

• Raspberry Pi OS Bookworm und Trixie, 32 und 64 Bit (jeder Raspberry Pi, auch Zero und 1)
• Debian 11, 12 und 13
• Ubuntu 22.04 und 24.04, Server und Desktop, auch Ubuntu für Raspberry Pi

Das Gerät braucht ausgehenden Internetzugang (HTTPS) und einen Benutzer, der sudo verwenden darf.

Gerät hinzufügen

Öffne im Dashboard Geräte → Gerät hinzufügen, wähle „Ein Gerät“ und erstelle das Token. Führe dann die beiden angezeigten Befehle auf dem Gerät aus, im Terminal oder per SSH:

(curl -fsSL https://get.piport.io/install.sh || wget -qO- https://get.piport.io/install.sh) > install.sh
sudo bash install.sh ppe_…

Die erste Zeile lädt den Installer (mit wget, falls curl fehlt, wie bei Ubuntu Desktop). Die zweite installiert den Agent aus dem PiPort-Paketrepository, verbindet das Gerät mit dem Token und startet den Agent. Nach wenigen Sekunden erscheint das Gerät im Dashboard. Das Token wird einmal verwendet und nicht auf dem Gerät gespeichert.

Mehrere Geräte und geklonte SD-Karten

Mit „Mehrere Geräte“ bekommst du ein Token für bis zu 25 Geräte, das 7 Tage gültig ist. Führe auf jedem Gerät dieselben beiden Befehle aus; der Installer fragt nach dem Token, damit es nicht in der Shell-History landet. Widerrufe das Token danach in der Token-Liste.

Um eine SD-Karte vorzubereiten und zu kopieren, führe den Installer als letzten Schritt mit --golden-image aus, fahre herunter und kopiere die Karte, ohne sie noch einmal zu starten:

sudo bash install.sh --golden-image
sudo poweroff

Jede Kopie verbindet sich beim ersten Start als eigenes Gerät. Eine Karte, die von einem schon verbundenen Gerät kopiert wurde, wird als Kopie erkannt und verlangt ein neues Token, statt das Original zu übernehmen.

Aktualisieren

Führe den Installer erneut aus, ohne Token. Er installiert den neuesten Agent und lässt alles andere, wie es ist:

(curl -fsSL https://get.piport.io/install.sh || wget -qO- https://get.piport.io/install.sh) > install.sh
sudo bash install.sh

Entfernen

sudo bash install.sh --uninstall

Die Identität des Geräts bleibt erhalten, eine erneute Installation verbindet es ohne Token. Mit --purge wird auch sie gelöscht. Entferne das Gerät auch im Dashboard.

Was der Installer ändert

• das Paket piport-agent und das (signierte) PiPort-APT-Repository
• den Dienst piport-agent, der als eigener Benutzer piport läuft, nicht als root
• /etc/sudoers.d/piport: Dieser Benutzer darf genau drei Dinge: das Gerät neu starten, ein Agent-Update installieren und auf einem Desktop einen Screenshot als Desktop-Benutzer aufnehmen. Unter GNOME oder KDE mit Wayland (z. B. Ubuntu Desktop) werden Screenshots nicht eingerichtet, weil diese sie von außerhalb der Sitzung nicht erlauben.
• /etc/piport/agent.env (Einstellungen, z. B. HTTPS_PROXY=… für einen Proxy) und /var/lib/piport (die Identität des Geräts)

Fehlersuche

systemctl status piport-agent
journalctl -u piport-agent -f

• „PiPort did not accept the token“: Es ist abgelaufen, aufgebraucht oder widerrufen. Erstelle ein neues.
• Root-Dateisystem ist ein Overlay: Mit dem „Overlay File System“ des Raspberry Pi übersteht nichts auf der Karte einen Neustart. Schalte es in raspi-config aus, installiere und schalte es danach wieder ein.
• Der Installer schreibt ein Log nach /var/log/piport-install.log.

Andere Distributionen

Für Systeme ohne APT gibt es ein Tarball mit dem Agent und seiner Service-Datei, ohne automatische Updates. Lade es für deine Architektur von https://get.piport.io/agent/stable/piport-agent_linux_<arm64|armv6|amd64>.tar.gz, entpacke es und führe darin sudo bash install.sh --local ppe_… aus.