Skip to content

Collector

The collector is a Linux VM in the customer network running remote checks:

  • SNMP (v1/v2c/v3) — switches, routers, firewalls, UPSes, storage
  • Ping — reachability
  • Port — TCP reachability
  • SSH — ssh_command, ssh_cpu, ssh_mem, ssh_disk, ssh_process, ssh_service
  • HTTP / HTTPS — http, http_json, ssl_certificate
  • vSphere/ESXi, internet line, API scripts and plugins
  • Discovery — network scans with its own scanner (ARP, ICMP, TCP, service detection)

Push-based: fetches config from server (GET /api/v1/config/collector/<id>), runs checks, sends results back (POST /receiver/api/v1/results). It does not run as root but under its own system account vesana-collector.

Prerequisites

What Min Recommended
OS Debian 12, Ubuntu 22.04, RHEL 9, AlmaLinux 9, SUSE 15, Arch Debian 13
Architecture amd64 amd64
RAM 1 GB 2 GB at ~500 hosts
Disk 5 GB 20 GB
Outbound 443 to Vesana server –
Network sight to monitored subnet –

Discovery needs no extra package — the scanner is part of the collector.

Step 1 — Register collector in Vesana

Collectors belong to a tenant and are created there: Tenants → expand the tenant → Collectors section → New Collector. The only field is the Name (e.g. acme-collector-01); Create Collector creates it.

Vesana then shows the API key (vesana_…) once, together with the ready-made install command. Copy it immediately — only a hash is stored. Later, Installer → Regenerate Key on the collector creates a new key (the old one stops working immediately).

Step 2 — Install collector

Copy the command from the dialog and run it as root on the Linux VM. The dialog has three tabs: Online (one-liner), Online (interactive) (prompts for server URL and key, nothing ends up in the shell history) and Offline bundle (archive with binary and installer for VMs without internet). Options above them:

  • Server URL (reachable from the customer VM) — the address the collector writes into its configuration.
  • Server has a self-signed certificate (skip TLS verification) — only for servers without a certificate pin. If a certificate is pinned on the server (agent gateway behind your own proxy), the command carries the pin itself (VESANA_CERT_PIN=… VESANA_CERT_SPKI_PIN=…) and downloads via curl --pinnedpubkey — curl is then required on the VM.
  • Protect this server from Vesana (Agent Lock) — sets VESANA_LOCK=1, see Agent Lock.

Basic form without options:

wget -qO- https://your-domain.tld/collector/install.sh | bash -s -- API_KEY https://your-domain.tld

What happens:

  1. Optional packages: Nagios/monitoring plugins via the available package manager (apt, dnf/yum, zypper, pacman). If that fails you get a warning and the installation continues.
  2. Resolve the collector ID from the API key, download and verify the binary (Linux executable, trial run). A running collector is only stopped after that.
  3. Create the system account vesana-collector; state under /var/lib/vesana-collector.
  4. Root-owned program file at /opt/vesana-collector/vesana-collector — neither the service nor scripts it runs can replace it. An old copy under /usr/local/bin is removed.
  5. Config file /etc/vesana/collector.env (mode 600, owned by the service account): 
    VESANA_API_URL=https://your-domain.tld
VESANA_RECEIVER_URL=https://your-domain.tld/receiver
VESANA_API_KEY=vesana_…
VESANA_COLLECTOR_ID=<uuid>
    Plus, depending on the options, VESANA_SERVER_CERT_SHA256 (certificate pin) or VESANA_INSECURE_SKIP_VERIFY=true.
  6. systemd service vesana-collector (own account, read-only system, only the network capabilities for ping and discovery) plus two helpers: vesana-collector-update.path (installs signed updates as root) and vesana-collector-uninstall.path (self-uninstall on instruction from Vesana).
  7. Enable and start the service.

Re-run safe — running it again updates binary and config.

Step 3 — Verify

In Vesana: Tenants → open the tenant → Collectors — the collector should send a heartbeat within 60 s (timestamp updates). „Online" means: last seen less than 3 minutes ago — the same window applies consistently across the dashboard tile, collector list, and tenant statistics.

On the collector VM:

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

Which machine does the collector run on?

Each collector shows "Runs on:". With every heartbeat the collector reports its hostname and the addresses of its network interfaces.

  • If the machine exists in Vesana as a host — same IP or same hostname, in the same tenant — you get a link to that host.
  • Otherwise the hostname and IP addresses are shown.
  • If several hosts match equally well, there is no link; the tooltip says so.
  • Older collector versions do not report their machine yet — until they update, the address their requests arrive from is shown. Behind a NAT firewall that is the firewall's address, not the VM's.

Only the collector's own tenant is searched on purpose: customer networks overlap, the same IP at another customer is a different device. The Active Collector belongs to no tenant and is searched across all tenants you can see.

Step 4 — Assign hosts to collector

A host has exactly one collector (or none — then its network checks run via the Active Collector). When creating a host or adding checks, choose "Collector" as the execution path and the tenant's collector. Existing hosts: Host detail → Manage host → Connection → Collector (passive checks).

Checks created by the device scan on hosts with a collector also run via that collector.

The collector polls config every 60 s — new hosts/services appear with a small delay. Threshold changes (warn/critical) are exempt from that and take effect immediately: the server applies them server-side to every incoming result, regardless of the last config poll.

Hardening the collector VM

If the VM runs only the collector, it can be locked down much further than an ordinary server. A script does that — it shows every step beforehand and can be undone with one command: Hardening the collector VM.

Discovery from the collector

Discovery scans run via the collector. Workflow: Hosts → Discovery.

The collector automatically detects which subnets it can see (local network interfaces, routing table, and optionally an SNMP walk of the default gateway routes) and reports that back to the server — this makes it easier to pick sensible scan ranges without having to look up the subnet by hand.

Log ingestion via the collector

The collector's API key can also be used to ingest logs for multiple hosts at once (POST /receiver/api/v1/logs/ingest with X-API-Key instead of an agent token). Typical case: a central syslog receiver on the collector VM collects packets from switches, firewalls, and NAS systems; each log entry carries its own host_id so it's attributed to the right host. Cross-tenant attribution is rejected server-side.

Log

The collector logs to the journal (journalctl -u vesana-collector) at info level; there is no configurable log level. With LOG_FORMAT=json in /etc/vesana/collector.env and a restart, the log is written as JSON (running the installer again rewrites the file — add the line again afterwards).

Multiple collectors

Larger environments or multiple sites: any number of collectors. One per site is common. The assignment is per host — all collector checks of a host run via the same collector.

Load balancing isn't automatic — if a collector is overloaded, manually rebalance hosts.

Auto-update

Collector auto-updates on next config refresh (60 s) when the server reports a newer version. Same mechanism as agents: see Agent versioning.

The collector file is root-owned under /opt/vesana-collector/ — the service cannot replace it, and neither can a script it runs. It downloads and verifies the update (signature, version) and only stages it; the systemd helper vesana-collector-update.path installs it as root, verifies the signature again and restarts the service. A rejected or unapplied file replaces nothing: the collector stays on its version, logs the reason (journalctl -u vesana-collector, or journalctl -u vesana-collector-update) and tries the same version again only after an hour. Installations from older versions are switched over by running the installer again.

Troubleshooting

Collector not online

  1. Outbound 443 open?
  2. DNS resolvable?
  3. API key correct?
  4. journalctl -u vesana-collector --since '5 minutes ago'

Common issues mirror agent troubleshooting — same mechanics.

SNMP check failing

# On the collector VM (snmpwalk: package snmp or net-snmp-utils)
snmpwalk -v 2c -c <community> <target-ip> .1.3.6.1.2.1.1.1.0

If that fails, it's not the collector — it's network / SNMP config / community.

SSH check: "SSH key has changed"

On first contact Vesana remembers the device's SSH host key (fingerprint, per host or per differing target and port). Every later connection checks against it. If the device offers a different key, the check reports CRITICAL (SSH_HOST_KEY_MISMATCH) and does not log in.

The check view then shows "SSH key has changed" with the previous and the currently offered fingerprint. Accept new key pins exactly the fingerprint shown (requires permission to edit the host and a fresh identity confirmation). Only accept if the device was reinstalled — otherwise someone could be intercepting the connection.

Discovery finds nothing

# Ping a known device in the target network:
ping -c 3 192.168.1.10

If that gets no answer either, subnet visibility is the issue. Further steps: Discovery finds nothing.

Uninstall

Easiest from Vesana: Tenants → tenant → Collectors → Delete Collector and choose Uninstall at "What happens to the collector on its VM?". On its next contact the collector removes itself completely (service, program, configuration, service user). With Keep installed it only rests; details: Deactivate, delete, restore. With Agent Lock active it does not uninstall itself.

By hand on the VM:

sudo systemctl disable --now vesana-collector vesana-collector-update.path vesana-collector-uninstall.path
sudo rm -f /etc/systemd/system/vesana-collector.service \
  /etc/systemd/system/vesana-collector-update.{path,service} \
  /etc/systemd/system/vesana-collector-uninstall.{path,service} \
  /usr/local/sbin/vesana-collector-uninstall
sudo rm -rf /opt/vesana-collector /var/lib/vesana-collector /etc/vesana /etc/vesana-lock/collector
sudo userdel vesana-collector
sudo systemctl daemon-reload

Only remove /var/lib/vesana-active-collector if no Active Collector runs on the machine (custom plugins share that directory).

Deleting in Vesana releases the collector's hosts: their collector checks continue via the Active Collector right away. Restoring the collector from the trash does not bring that assignment back — reassign the hosts by hand.

Next