Agent (Linux / Windows)¶

Der Vesana Agent ist ein Single-Binary in Go — statisch gelinkt (CGO_ENABLED=0), ~6.5 MB, keine Runtime-Dependencies. Er läuft als systemd-Service (Linux) oder Windows-Service.

Voraussetzungen¶

Outbound HTTPS 443 zum Vesana-Server
Linux: systemd (Debian, Ubuntu, RHEL, AlmaLinux, SUSE, Arch alle ok); muss als root installiert werden
Windows: Server 2016+ oder Windows 10+ (amd64)

Schritt 1 — Host in Vesana anlegen¶

Wenn nicht schon passiert: Host mit agent_capable-Profil anlegen. Siehe Hosts anlegen.

Schritt 2 — Agent-Token generieren¶

Auf der Host-Detail-Seite:

Agent einrichten
Token wird genau einmal angezeigt
Sofort kopieren

Schritt 3 — Agent installieren¶

Linux (One-Command)Linux (manuell)Windows (NSIS-Wizard)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.

Was passiert:

Distro-Detection (Debian/RHEL/SUSE/Arch)
Binary nach /usr/local/bin/vesana-agent legen
Config nach /etc/vesana-agent/config.yaml schreiben (chmod 600)
systemd-Unit unter /etc/systemd/system/vesana-agent.service
systemctl enable --now vesana-agent

Re-run safe — überschreibt Binary + Config.

# 1. Binary herunterladen
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 anlegen
sudo mkdir -p /etc/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 Agent
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/vesana-agent --config /etc/vesana-agent/config.yaml
Restart=on-failure
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target
EOF

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

Download von der Server-Downloads-Seite: vesana-agent-setup.exe
Doppelklick — der Wizard öffnet sich
Eingabe:
- Server-URL: https://deine-domain.tld
- Agent-Token aus Schritt 2
Installieren — der Wizard installiert Binary nach C:\Program Files\Vesana Agent\, schreibt Config, registriert Windows-Service

Service heißt VesanaAgent und startet automatisch beim Boot.

Eingabeaufforderung als Administrator:

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

REM 2. Installation
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

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-Detail-Seite in der UI: Agent-Status sollte innerhalb kurzer Zeit auf online wechseln (grüner Punkt). 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

Event Viewer → Windows Logs → Application → Source „VesanaAgent"

Oder PowerShell:

Get-EventLog -LogName Application -Source VesanaAgent -Newest 20

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`/`warn_pattern`/`crit_pattern`
`agent_script`	Server-managed Script	`script_id`
`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-Detail-Seite → Agent → Token widerrufen
Alter Agent meldet sich nicht mehr (401)
Neues Token erzeugen
Auf der Maschine /etc/vesana-agent/config.yaml (oder C:\ProgramData\Vesana\Agent\config.yaml) neu setzen
Service neu starten

Alternativ: Re-Install mit neuem Token via One-Command-Installer.

Proxy / DNS¶

Wenn der Agent über HTTPS-Proxy raus muss:

LinuxWindows

sudo mkdir -p /etc/systemd/system/vesana-agent.service.d
sudo tee /etc/systemd/system/vesana-agent.service.d/proxy.conf > /dev/null <<'EOF'
[Service]
Environment="HTTPS_PROXY=http://proxy.local:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF
sudo systemctl daemon-reload
sudo systemctl restart vesana-agent

Service-Config über sc.exe setzen:

sc.exe config VesanaAgent type= own
powershell -Command "Set-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\VesanaAgent' -Name Environment -Value @('HTTPS_PROXY=http://proxy.local:8080','NO_PROXY=localhost,127.0.0.1')"
Restart-Service VesanaAgent

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 einem anderen Host zugeordnet
`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: Outbound 443 zum Server offen?
DNS-Auflösung: getent hosts deine-domain.tld (Linux) / nslookup deine-domain.tld (Windows)
TLS-Cert: Self-signed? Dann --insecure in der Config setzen oder Cert ins System-Trust-Store
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 — Cert ungültig oder self-signed
`401 Unauthorized`	Token falsch
`403 Forbidden`	Token gehört zu anderem Host (in DB neu vergeben?)
`connection refused`	Server nicht da oder Port falsch

Service startet nicht¶

# Linux: gibt der Binary direkten Run im Vordergrund:
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
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.

Anschluss¶

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 generieren¶

Schritt 3 — Agent installieren¶

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 / DNS¶

Troubleshooting¶

agent.log — erste Anlaufstelle¶

Agent meldet sich nicht¶

Service startet nicht¶

Auto-Update klemmt¶

Deinstallation¶

Anschluss¶

Checks sofort testen — `vesana-agent test`¶