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

Schritt 4 — Verifizieren¶

Auf der Host-Detail-Seite in der UI: Agent-Status sollte innerhalb von 30 s auf online wechseln (grüner Punkt).

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.

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)

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 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 Programme & Features. Oder:

"C:\Program Files\Vesana\Agent\vesana-agent.exe" uninstall
rmdir /s /q "C:\Program Files\Vesana\Agent"
rmdir /s /q "C:\ProgramData\Vesana\Agent"

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