raspi-agent

Lightweight HTTPS REST Agent for Raspberry Pi

Version 0.0.7

---

Beschreibung

raspi-agent ist ein in Go entwickelter HTTPS-REST-Agent für Raspberry-Pi-Systeme.

Der Agent stellt Systeminformationen über eine REST-API im JSON-Format zur Verfügung und bildet die Grundlage für spätere Fernüberwachungs- und Fernsteuerungsfunktionen. Der raspi-agent ist ein Read-Only-Systemagent. Alle REST-Endpunkte verwenden ausschließlich die HTTP-Methode GET und verändern niemals den Zustand des Systems.

Bei der Entwicklung stehen folgende Ziele im Vordergrund:

• einfache Installation
• geringer Ressourcenverbrauch
• Verwendung der Go-Standardbibliothek, soweit möglich
• klar strukturierter Quellcode
• modulare Erweiterbarkeit
• vollständige Unit-Tests
• stabile, versionierte Entwicklung

---

Funktionen

Version 0.0.7 unterstützt:

• HTTPS-Webserver
• REST-API
• JSON-Ausgabe
• Konfigurationsdatei
• Health-Check
• Versionsinformationen
• Hostinformationen
• Betriebssysteminformationen
• Systemlaufzeit
• Arbeitsspeicher
• CPU-Informationen
• CPU-Auslastung
• CPU-Status
• CPU-Temperatur
• Dateisysteminformationen
• Netzwerkschnittstellen
• Netzwerkadressen

---

Voraussetzungen

• Raspberry Pi OS
• Linux
• Go 1.24 oder neuer
• Git

---

Installation

Repository klonen

git clone https://git.lang-dieter.de/dieter/raspi-agent.git

Projekt wechseln

cd raspi-agent

Build erstellen

./scripts/build.sh

Das Build-Skript erzeugt alle unterstützten Linux-Builds im Verzeichnis build/.

Anschließend wird das Deployment auf das Zielsystem durchgeführt:

./scripts/deploy.sh afu 100.64.0.1

Das Deployment überträgt alle verfügbaren Linux-Builds, die Konfiguration, vorhandene Zertifikate, die systemd-Vorlage und das Installationsskript auf das Zielsystem.

Die Dateien werden zunächst nach /tmp/raspi-agent übertragen.

Anschließend wird install.sh auf dem Zielsystem automatisch ausgeführt.

Das Installationsskript ermittelt die vorhandene Systemarchitektur und wählt die passende Binärdatei aus. Die Binärdatei wird nach /opt/raspi-agent/bin/raspi-agent installiert.

Die Konfigurationsdatei wird nach /opt/raspi-agent/config/config.json übernommen und steht damit bereits beim ersten Start zur Verfügung.

Der systemd-Dienst wird eingerichtet, aktiviert und gestartet.

Die Versionsinformationen werden beim Build aus dem Git-Repository ermittelt und über den Go-Linker in die Binärdateien eingebettet. Während der Installation ist deshalb kein Zugriff auf das Git-Repository erforderlich.

---

Konfiguration

Die Konfiguration erfolgt über

configs/config.json

Beispiel:

{
    "listen": ":8443",
    "cert_file": "cert.pem",
    "key_file": "key.pem",
    "read_timeout": 10,
    "write_timeout": 10
}

Die Konfigurationsdatei wird beim Deployment auf das Zielsystem übertragen und steht damit bereits beim ersten Start zur Verfügung.

Nach der Installation befindet sie sich unter:

/opt/raspi-agent/config/config.json

---

HTTPS-Zertifikate

Für den HTTPS-Betrieb können vorhandene Zertifikate verwendet werden.

Sind beim Deployment Zertifikate vorhanden, werden diese auf das Zielsystem übertragen.

Sind keine Zertifikate vorhanden, erzeugt der raspi-agent beim Start temporäre selbstsignierte Zertifikate.

---

Start

Nach der Installation wird der raspi-agent als systemd-Dienst betrieben.

systemctl status raspi-agent

Die Protokollausgabe kann mit

journalctl -u raspi-agent

angezeigt werden.

---

REST-API

Alle Antworten werden im JSON-Format geliefert.

Methode	Endpunkt	Beschreibung
GET	/	Startseite
GET	/api/v1/health	Status des Agenten
GET	/api/v1/version	Versionsinformationen
GET	/api/v1/system	Hostinformationen
GET	/api/v1/os	Betriebssystem
GET	/api/v1/uptime	Systemlaufzeit
GET	/api/v1/memory	Arbeitsspeicher
GET	/api/v1/cpu	CPU-Informationen
GET	/api/v1/temperature	CPU-Temperatur
GET	/api/v1/storage	Dateisysteminformationen
GET	/api/v1/network	Netzwerkschnittstellen
GET	/api/v1/address	Netzwerkadressen

---

Projektstruktur

raspi-agent/
├── cmd/
│   └── raspi-agent/
│       └── main.go
│
├── configs/
│   └── config.json
│
├── internal/
│   ├── api/
│   ├── config/
│   ├── https/
│   ├── system/
│   └── version/
│
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   ├── install.sh
│   └── uninstall.sh
│
├── systemd/
│   └── raspi-agent.service.in
│
├── build/
│   ├── linux-amd64/
│   ├── linux-arm64/
│   ├── linux-arm-v6/
│   └── linux-arm-v7/
│
├── go.mod
└── README.md

---

Entwicklungsprinzipien

Der raspi-agent wird in kleinen, nachvollziehbaren Schritten entwickelt.

Grundsätze:

• stabile Zwischenversionen
• vollständige Unit-Tests
• möglichst Verwendung der Go-Standardbibliothek
• klar strukturierte Pakete
• saubere Dokumentation
• Git-Tags für stabile Versionen
• Versionsinformationen werden beim Build aus Git übernommen
• keine Abhängigkeit von Git während der Installation

---

Roadmap

Version 0.0.4

• Systemdienste
• Prozessinformationen

Version 0.0.5

• Logdateien
• Journal

---

Lizenz

Dieses Projekt steht unter der GNU General Public License Version 3 oder neuer (GPL-3.0-or-later).

Weitere Informationen befinden sich in der Datei LICENSE.