Agent (Linux / Windows)¶

Der Vesana Agent ist ein einzelnes, statisch gelinktes Go-Programm ohne Laufzeit-Abhängigkeiten. Er läuft als systemd-Dienst (Linux) oder Windows-Dienst.

Voraussetzungen¶

Ausgehend HTTPS zum Vesana-Server — Port 443 bzw. der Port der Agent-Server-Adresse (z. B. 8443 beim Agent-Gateway). Einen HTTP-Proxy nutzt der Agent nicht (siehe Proxy).
Linux: amd64, arm64 oder armv6/armv7 (z. B. Raspberry Pi, LoxBerry) mit systemd (Debian, Ubuntu, RHEL, Rocky, AlmaLinux, SUSE, Arch); Installation als root
Windows: Server 2016+ oder Windows 10+ (amd64)

Schritt 1 — Host in Vesana anlegen¶

Wenn nicht schon passiert: Host anlegen. Siehe Hosts anlegen.

Schritt 2 — Agent-Token erzeugen¶

Host öffnen → Host verwalten → Reiter Verbindung → unter „Monitoring-Quellen" Agent einrichten (dafür braucht es das Recht „Agents verwalten"):

Der Token wird genau einmal angezeigt — sofort kopieren.
Darunter stehen die fertigen Installationsbefehle für Windows und Linux, mit Token und Server-Adresse schon eingesetzt. Am einfachsten kopierst du den passenden Befehl von dort.

Schritt 3 — Agent installieren¶

Linux (One-Command)Linux (manuell)Windows (Setup-Assistent)Windows (PowerShell)Windows (manuell)

Auf der Zielmaschine als root:

wget -qO- https://deine-domain.tld/agent/install.sh | bash -s -- TOKEN https://deine-domain.tld

TOKEN durch das aus Schritt 2 ersetzen, deine-domain.tld durch deinen Server. Ohne Token und Adresse (bash <(wget -qO- https://deine-domain.tld/agent/install.sh)) fragt der Installer beides interaktiv ab — der Token landet dann nicht in der Shell-History.

Was passiert:

Binary herunterladen und prüfen (echte Linux-Binary, Probelauf mit --version) — scheitert das, bricht der Installer ab und ein laufender Agent bleibt unberührt
Binary nach /usr/local/bin/vesana-agent
Config nach /etc/vesana-agent/config.yaml (chmod 600), Zustand unter /var/lib/vesana-agent
systemd-Unit unter /etc/systemd/system/vesana-agent.service
Dienst aktivieren und starten; startet er nicht, zeigt der Installer Status und Journal

Mehrfach ausführbar — überschreibt Binary und Config.

# 1. Binary herunterladen (amd64 · arm64 · arm für 32-bit-ARM)
wget https://deine-domain.tld/agent/vesana-agent-linux-amd64 -O /tmp/vesana-agent
chmod +x /tmp/vesana-agent
sudo mv /tmp/vesana-agent /usr/local/bin/vesana-agent

# 2. Config und Verzeichnisse anlegen
sudo mkdir -p /etc/vesana-agent /var/lib/vesana-agent /var/log/vesana-agent
sudo chmod 700 /var/lib/vesana-agent
sudo tee /etc/vesana-agent/config.yaml > /dev/null <<'EOF'
server: "https://deine-domain.tld"
token: "vesana_agent_DEIN_TOKEN_HIER"
log_level: "info"
EOF
sudo chmod 600 /etc/vesana-agent/config.yaml

# 3. systemd-Unit
sudo tee /etc/systemd/system/vesana-agent.service > /dev/null <<'EOF'
[Unit]
Description=Vesana Monitoring Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 4. Aktivieren
sudo systemctl daemon-reload
sudo systemctl enable --now vesana-agent

Restart=always ist Pflicht: nach einem Selbst-Update beendet sich der Agent sauber und verlässt sich darauf, dass systemd ihn neu startet. Mit Restart=on-failure bliebe er nach dem ersten Update aus.

Im Dialog „Agent einrichten" auf vesana-agent-setup.exe klicken. Der Download trägt die Server-Adresse schon vorausgefüllt (und bei Bedarf den Zertifikats-Fingerabdruck, siehe unten).
Als Administrator ausführen — der Assistent öffnet sich.
Eingabe:
- Server-URL (vorausgefüllt)
- Agent-Token aus Schritt 2
- Haken „Self-signed Zertifikat (TLS-Pruefung ueberspringen)" nur, wenn der Server ein selbstsigniertes Zertifikat ohne Fingerabdruck hat
Installieren — der Assistent legt das Programm nach C:\Program Files\Vesana Agent\, die Config nach C:\ProgramData\Vesana\Agent\config.yaml (nur SYSTEM und Administratoren), registriert den Dienst und startet ihn.

Der Dienst heißt VesanaAgent und startet automatisch beim Boot.

Ohne Oberfläche (z. B. Server Core) geht derselbe Installer still: vesana-agent-setup.exe /S /TOKEN=vesana_agent_xxx /SERVER=https://deine-domain.tld (optional /INSECURE=1). Fehlt Token oder Server, endet er mit Exit-Code 2.

In einer Administrator-PowerShell (der fertige Befehl mit Token steht im Dialog „Agent einrichten"):

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create(
    (New-Object Net.WebClient).DownloadString('https://deine-domain.tld/agent/install.ps1')
)) -Token 'vesana_agent_xxx' -Server 'https://deine-domain.tld'

Läuft auch auf Server Core (PowerShell 5.1 und 7). Mehrfach ausführbar: ein vorhandener Agent wird erst nach erfolgreichem Download ersetzt. Weitere Parameter: -Lock (Agent Lock gleich einschalten), -SkipTlsCheck (selbstsigniertes Zertifikat ohne Fingerabdruck), -Instance (zweiter Agent).

Eingabeaufforderung als Administrator:

REM 1. Download
cd %TEMP%
curl -O https://deine-domain.tld/agent/vesana-agent-windows-amd64.exe

REM 2. Installation
mkdir "C:\Program Files\Vesana Agent"
move vesana-agent-windows-amd64.exe "C:\Program Files\Vesana Agent\vesana-agent.exe"

REM 3. Config (PowerShell)
powershell -Command "New-Item -ItemType Directory -Force 'C:\ProgramData\Vesana\Agent'"
powershell -Command "@'
server: ""https://deine-domain.tld""
token: ""vesana_agent_DEIN_TOKEN_HIER""
log_level: ""info""
'@ | Set-Content -Path 'C:\ProgramData\Vesana\Agent\config.yaml'"

REM 4. Service installieren und starten
"C:\Program Files\Vesana Agent\vesana-agent.exe" install
net start VesanaAgent

Beim manuellen Weg behält die Config die Rechte, die Windows vergibt. Setup-Assistent und PowerShell-Installer beschränken sie auf SYSTEM und Administratoren — wenn möglich einen davon nehmen.

Selbstsigniertes Zertifikat: Zertifikats-Pin¶

Hat dein Vesana-Server unter der Agent-Server-Adresse ein Zertifikat, dem ein normaler Client nicht vertraut (selbstsigniertes Stack-Zertifikat, eigene CA, Agent-Gateway-Port), bringen die Installationsbefehle aus Vesana automatisch einen Zertifikats-Pin mit — den SHA-256-Fingerabdruck genau dieses Zertifikats:

Linux: der Download läuft über curl --pinnedpubkey, der Befehl setzt VESANA_CERT_PIN=… VESANA_CERT_SPKI_PIN=… (dafür muss curl installiert sein, wget kennt keinen Pin).
Windows: der PowerShell-Befehl prüft schon den Download des Installers gegen den Fingerabdruck und gibt -CertPin weiter; der Setup-Assistent bekommt den Pin beim Download eingebaut.
Der Agent schreibt ihn als server_cert_sha256 in seine Config und akzeptiert danach die normale Zertifikatskette oder genau dieses Zertifikat — nie „alles". Die TLS-Prüfung bleibt also an.

Hat der Server ein gültiges Zertifikat (auch ein eigener Reverse-Proxy mit gültigem Zertifikat vor der Agent-Server-Adresse), enthält der Befehl keinen Pin. Bricht der Linux-Installer mit „Zertifikats-Pin gesetzt, aber kein Schlüssel-Pin" ab, stammt der Befehl aus einer älteren Version — in Vesana neu kopieren.

Der Haken „Server hat ein selbst-signiertes Zertifikat (TLS-Prüfung überspringen)" schaltet die Prüfung dagegen ganz ab (insecure_skip_verify: true). Nur nehmen, wenn kein Pin angeboten wird.

Zweiter Agent auf demselben Rechner¶

Ein Rechner kann an zwei Vesana-Instanzen melden — etwa an die eigene Instanz und zusätzlich an eine zweite (Test, Dienstleister, app.vesana.org). Dafür läuft ein zweiter Agent mit eigenem Namen neben dem ersten: eigener Dienst, eigene Konfiguration, eigener Zustand. Der erste Agent bleibt unberührt. Der Agent-Token stammt aus der jeweils anderen Instanz (dort den Host anlegen, „Agent einrichten", Token kopieren).

Nicht der Normalfall

Ein Agent pro Rechner ist der Standard. Der zweite Agent ist für den Sonderfall gedacht — er wird nicht über die Oberfläche eingerichtet, sondern mit dem Installer-Parameter unten.

LinuxWindows

Der Installer bekommt einen Instanznamen (Kleinbuchstaben, Ziffern, Bindestrich — max. 32 Zeichen):

wget -qO- https://zweite-instanz.tld/agent/install.sh | VESANA_INSTANCE=zweite bash -s -- TOKEN https://zweite-instanz.tld

Der Name hängt sich an alles:

	erster Agent	zweiter Agent (`zweite`)
Dienst	`vesana-agent`	`vesana-agent-zweite`
Binary	`/usr/local/bin/vesana-agent`	`/usr/local/bin/vesana-agent-zweite`
Config	`/etc/vesana-agent/config.yaml`	`/etc/vesana-agent-zweite/config.yaml`
Zustand	`/var/lib/vesana-agent`	`/var/lib/vesana-agent-zweite`
Logs	`/var/log/vesana-agent`	`/var/log/vesana-agent-zweite`

Bedienen wie gewohnt, nur mit Namen:

systemctl status vesana-agent-zweite
journalctl -u vesana-agent-zweite -f
vesana-agent-zweite --config /etc/vesana-agent-zweite/config.yaml test

Entfernen: wie unter Deinstallation, mit -zweite an Dienst, Binary und Verzeichnissen.

Welche Agents laufen auf diesem Rechner? Der Instanzname steht im Dienst- und Ordnernamen — er ist nirgendwo sonst gespeichert:

systemctl list-units 'vesana-agent*' --type=service
ls -d /etc/vesana-agent*

Der PowerShell-Installer bekommt -Instance (Buchstaben, Ziffern, Bindestrich — max. 32 Zeichen). Der NSIS-Wizard kennt keinen zweiten Agent — dafür immer die PowerShell-Variante nehmen:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
& ([scriptblock]::Create(
    (New-Object Net.WebClient).DownloadString('https://zweite-instanz.tld/agent/install.ps1')
)) -Token 'vesana_agent_xxx' -Server 'https://zweite-instanz.tld' -Instance 'Zweite'

	erster Agent	zweiter Agent (`Zweite`)
Dienst	`VesanaAgent`	`VesanaAgent-Zweite`
Programm	`C:\Program Files\Vesana Agent`	`C:\Program Files\Vesana Agent-Zweite`
Config + Log	`C:\ProgramData\Vesana\Agent`	`C:\ProgramData\Vesana\Agent-Zweite`

Entfernen (Administrator-PowerShell):

& "$env:ProgramFiles\Vesana Agent-Zweite\vesana-agent.exe" --service-name VesanaAgent-Zweite uninstall
Remove-Item -Recurse -Force "$env:ProgramFiles\Vesana Agent-Zweite"
Remove-Item -Recurse -Force "$env:ProgramData\Vesana\Agent-Zweite"

Welche Agents laufen auf diesem Rechner?

Get-Service VesanaAgent*

Beide Agents aktualisieren sich unabhängig voneinander von ihrem jeweiligen Server. Die Checks laufen doppelt (jede Instanz misst selbst) — das ist gewollt und kostet auf dem Rechner kaum etwas.

Schritt 4 — Verifizieren¶

Auf der Host-Seite sollte der Agent-Chip innerhalb kurzer Zeit auf Online wechseln (unter „Host verwalten → Verbindung“ mit der Agent-Version dahinter). Der Agent schickt alle ~20 Sekunden einen Heartbeat — das ist die Basis für den Online-Status. Die eigentliche Check-Konfiguration (neue/geänderte Checks, Version) holt er separat alle ~5 Minuten ab.

Checks sofort testen — `vesana-agent test`¶

Direkt nach der Installation lohnt sich ein Testlauf, statt auf den ersten regulären Check-Zyklus zu warten. Der Befehl vesana-agent test führt alle vom Server konfigurierten Checks einmal aus, zeigt jedes Ergebnis live in der Konsole (Status, erste Zeile der Meldung, Dauer) und schickt den Batch anschließend an den Server. So siehst du sofort, ob die Konfiguration ankommt und die Checks plausible Werte liefern.

WindowsLinux

PowerShell als Administrator öffnen und ausführen:

& "C:\Program Files\Vesana Agent\vesana-agent.exe" test

Als Administrator, weil der Dienst als LocalSystem läuft — als normaler Benutzer können einzelne Checks (Dienste, Eventlog) anders ausfallen als im Dienstbetrieb.

sudo vesana-agent test

Die Config (Server-URL + Token) wird automatisch gefunden — Windows C:\ProgramData\Vesana\Agent\config.yaml, Linux /etc/vesana-agent/config.yaml. Liegt sie woanders: vesana-agent test --config <pfad>.

Typische Ausgabe: Server: …, Verbunden als Host "…" — N Checks konfiguriert, dann Zeile für Zeile die Ergebnisse und eine Zusammenfassung (Ergebnis: 2 OK, 1 WARNING …). Klartext-Diagnose bei Problemen: 401/403 = Token prüfen, 404 = Server-URL prüfen, „0 Checks" = im Portal erst Agent-Checks anlegen. Der laufende Dienst sendet parallel weiter — doppelte Datenpunkte sind im Push-Modell harmlos.

„unknown command: test"?

Dann ist der installierte Agent zu alt für den Befehl. Agents aktualisieren sich automatisch (~5 Min) — danach steht test zur Verfügung.

Logs prüfen:

LinuxWindows

sudo systemctl status vesana-agent
sudo journalctl -u vesana-agent -f

Der Windows-Dienst schreibt nicht ins Ereignisprotokoll, sondern in C:\ProgramData\Vesana\Agent\agent.log:

Get-Service VesanaAgent
Get-Content "$env:ProgramData\Vesana\Agent\agent.log" -Tail 50 -Wait

Schritt 5 — Checks zuweisen¶

Wenn das Profil auto_add Checks hat, sind sie schon da. Sonst manuell auf der Host-Detail-Seite Services hinzufügen.

Der Agent holt seine Konfiguration alle 5 Minuten — neue Checks erscheinen also mit kurzem Delay.

Schwellwert-Änderungen (Warn/Critical) wirken davon unabhängig sofort: der Server wendet geänderte Schwellwerte serverseitig auf jedes eingehende Ergebnis an, unabhängig davon, wann der Agent seine Config zuletzt geholt hat. Andere Config-Änderungen (z. B. Eventlog-Filter, Service-Ausschlüsse) brauchen dagegen den nächsten Config-Poll des Agents — im Regelfall die vollen 5 Minuten, der Server kann diesen Poll aber gezielt vorziehen, sodass die Änderung binnen ~60 Sekunden greift.

Verfügbare Agent-Check-Typen¶

Check-Type	Was es prüft	Config
`agent_cpu`	CPU-Auslastung in % (over time)	–
`agent_memory`	RAM-Auslastung in %	–
`agent_disk`	Disk-Usage pro Mount in %	`path` (z. B. `/`, `C:`)
`agent_service`	Status eines Service / systemd-Unit	`service` (Service-Name)
`agent_process`	Läuft ein Prozess?	`process` (Name oder Pattern)
`agent_eventlog`	Windows Event Log	`log`, `level`, `minutes`
`agent_custom`	Eigener Befehl ausführen	`command`, `ok_pattern`/`crit_pattern` (Regex); Exit-Code ungleich 0 = CRITICAL
`agent_script`	Script aus der Script-Bibliothek oder lokaler Pfad am Host	Script-Auswahl, Script-Werte
`agent_services_auto`	Alle Auto-Start-Services prüfen (Windows)	`exclude` (Liste)
`agent_containers`	Container (Docker) — unhealthy, Crashloops, beendete Pflicht-Container (nur Linux, liest den Docker-Socket)	Pflicht-/Ausnahme-Listen mit Platzhaltern, Schwellwerte auf die Problem-Anzahl

Die Eventlog-Prüfung läuft auch auf Linux (journald). Die CPU-Messung liest unter Windows direkt die Leistungsdaten — sprachneutral und auch auf Windows Server 2025 ohne wmic. PowerShell-Scripts werden mit UTF-8-Kennung abgelegt, damit Umlaute und Sonderzeichen im Script keinen Syntaxfehler auslösen. Hardware-Telemetrie (SMART, Temperaturen, Interface-Durchsatz) und der Docker-Tab brauchen einen aktuellen Agent — das Update kommt automatisch. Agents der alten 2.x-Linie, die dauerhaft festhingen, brauchen einmalig eine Neuinstallation.

Token-Rotation¶

Wenn ein Token kompromittiert wurde: Host öffnen → Host verwalten → Verbindung → beim Agent Token erneuern.

Der alte Token ist sofort ungültig; der Agent auf der Maschine bekommt ab jetzt 401.
Den neuen Token einmalig kopieren.
Auf der Maschine eintragen: vesana-agent reconfigure (fragt Server-URL und Token ab, siehe Befehle am Host) und den Dienst neu starten — oder den Installationsbefehl mit dem neuen Token erneut ausführen.

Token widerrufen (gleiche Stelle) entzieht den Zugang, ohne einen neuen auszustellen: der Agent hält an, der Host ist danach kein Agent-Host mehr.

Proxy¶

Der Agent verbindet sich immer direkt mit dem Vesana-Server. Proxy-Umgebungsvariablen wie HTTPS_PROXY wertet er nicht aus — auch nicht für Updates. Muss der Verkehr aus dem Netz über einen Proxy, braucht es eine Firewall-Freigabe für ausgehendes HTTPS zur Agent-Server-Adresse, oder einen Collector, der die Geräte von einem Netz mit Zugang aus prüft.

Troubleshooting¶

agent.log — erste Anlaufstelle¶

Bei „Agent läuft, aber es kommen keine Daten an" ist agent.log der schnellste Weg zur Ursache. Es liegt im Klartext (kein strukturiertes Log-Format), lokale Zeit, Level als Wort:

2026-07-04 10:15:03  INFO   Ergebnisse gesendet  checks=5

Ort der Datei:

Plattform	Pfad
Linux	neben der Config, also `/etc/vesana-agent/agent.log`
Windows	`C:\ProgramData\Vesana\Agent\agent.log`

Der Agent loggt typische Ursachen als klare Fehlermeldung statt sie stumm zu verschlucken:

Log-Inhalt	Bedeutung
`401`/`403`	Token prüfen — falsch, widerrufen oder durch „Token erneuern" ersetzt
`404`	Server-URL prüfen — Pfad/Domain stimmt nicht
„0 Checks"	Host hat noch keine Services zugewiesen — siehe Schritt 5 oben

Nicht-OK-Ergebnisse werden zusätzlich mit Klartext-Meldung geloggt (OK-Ergebnisse bleiben auf Debug-Level, um das Log nicht zu fluten).

Agent meldet sich nicht¶

Firewall: ausgehend 443 (bzw. Gateway-Port) zum Server offen?
DNS-Auflösung: getent hosts deine-domain.tld (Linux) / nslookup deine-domain.tld (Windows)
TLS-Zertifikat: selbstsigniert? Installationsbefehl aus Vesana verwenden (bringt den Zertifikats-Pin mit), das Zertifikat in den System-Zertifikatsspeicher aufnehmen oder notfalls insecure_skip_verify: true in die Config
Token: Exakt wie generiert, ohne Whitespace/Newlines
Logs prüfen

Häufige Fehlermeldungen:

Log-Zeile	Ursache
`dial tcp: lookup vesana.example: no such host`	DNS
`x509: certificate signed by unknown authority`	TLS — Zertifikat ungültig oder selbstsigniert ohne Pin
`401 Unauthorized`	Token falsch, widerrufen oder erneuert
`410 Gone`	Host in Vesana endgültig gelöscht — der Agent hält an (siehe Lebenszyklus)
`connection refused`	Server nicht da oder Port falsch

Service startet nicht¶

# Linux: Agent im Vordergrund starten (vorher den Dienst stoppen):
sudo /usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml

# Windows:
"C:\Program Files\Vesana Agent\vesana-agent.exe" --config "C:\ProgramData\Vesana\Agent\config.yaml"

Vordergrund-Output zeigt Probleme, die als Service unsichtbar bleiben.

Auto-Update klemmt¶

Siehe Agent-Versionierung.

Deinstallation¶

LinuxWindows

sudo systemctl stop vesana-agent
sudo systemctl disable vesana-agent
sudo rm /etc/systemd/system/vesana-agent.service
sudo rm -rf /etc/vesana-agent /var/lib/vesana-agent /var/log/vesana-agent
sudo rm /usr/local/bin/vesana-agent
sudo systemctl daemon-reload

NSIS-Uninstaller über Einstellungen → Apps → Installierte Apps → „Vesana Agent". Oder (PowerShell als Administrator):

& "$env:ProgramFiles\Vesana Agent\uninstall.exe" /S
Remove-Item -Recurse -Force "$env:ProgramData\Vesana\Agent" -ErrorAction SilentlyContinue

Vollständige Anleitung inkl. Dienst-Notfall-Entfernung: Deinstallation → Agent entfernen.

Nach Deinstallation: Token in Vesana widerrufen, sonst zählt der Host weiter als „Agent existiert" obwohl niemand mehr da ist.

Einfacher geht es aus Vesana heraus: Host löschen (oder am Agent-Chip „Agent entfernen“) und „Deinstallieren“ wählen — der Agent entfernt sich dann selbst. Was beim Deaktivieren, Löschen und Wiederherstellen mit dem Agent passiert: Deaktivieren, Löschen, Wiederherstellen.

Anschluss¶

Befehle am Host — alle vesana-agent-Befehle (Windows-PowerShell + Linux) auf einen Blick
Agent-Versionierung — Auto-Update verstehen
Monitoring → Check-Typen — alle Agent-Checks im Detail
Monitoring → Scripts — Custom-Scripts via agent_script

Agent (Linux / Windows)¶

Voraussetzungen¶

Schritt 1 — Host in Vesana anlegen¶

Schritt 2 — Agent-Token erzeugen¶

Schritt 3 — Agent installieren¶

Selbstsigniertes Zertifikat: Zertifikats-Pin¶

Zweiter Agent auf demselben Rechner¶

Schritt 4 — Verifizieren¶

Checks sofort testen — vesana-agent test¶

Schritt 5 — Checks zuweisen¶

Verfügbare Agent-Check-Typen¶

Token-Rotation¶

Proxy¶

Troubleshooting¶

agent.log — erste Anlaufstelle¶

Agent meldet sich nicht¶

Service startet nicht¶

Auto-Update klemmt¶

Deinstallation¶

Anschluss¶

Checks sofort testen — `vesana-agent test`¶