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
  • SSH — ssh_command, ssh_cpu, ssh_mem, ssh_disk
  • HTTP / HTTPS — http, ssl_certificate
  • Discovery — nmap scans

Push-based: fetches config from server (GET /api/v1/config/collector/<id>), runs checks, sends results back (POST /receiver/check-result).

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 –

nmap is auto-installed by the installer.

Step 1 — Register collector in Vesana

Admin → Collectors → New:

Field Example
Name acme-collector-01
Tenant Acme GmbH
Description Customer LAN, HQ

After Save, Vesana shows an API key once:

vesana_<custom-prefix>_<32-bytes>

Copy immediately — only the hash is visible afterwards.

Step 2 — Install collector

One-command installer on the Linux VM, as root:

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

What happens:

  1. Distro detection (Debian / RHEL / AlmaLinux / SUSE / Arch)
  2. Packages: nmap, snmp (client), ca-certificates, curl
  3. Binary into /usr/local/bin/vesana-collector
  4. Config: /etc/vesana/collector.env 
    VESANA_SERVER=https://your-domain.tld
VESANA_API_KEY=vesana_xxxxx_yyyy...
VESANA_LOG_LEVEL=info
  5. systemd unit /etc/systemd/system/vesana-collector.service
  6. systemctl enable --now vesana-collector

Re-run safe — overwrites binary + config.

Step 3 — Verify

In Vesana: Admin → 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

Step 4 — Assign hosts to collector

When creating a host with passive checks: pick collector from dropdown. Existing hosts: Host detail → Assign 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.

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 /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.

Increase logging

sudo sed -i 's|^VESANA_LOG_LEVEL=.*|VESANA_LOG_LEVEL=debug|' /etc/vesana/collector.env
sudo systemctl restart vesana-collector

debug is verbose — switch back to info for production.

Multiple collectors

Larger environments or multiple sites: any number of collectors. One per site is common. Hosts are assigned per service to a collector — services of one host can split across collectors.

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.

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 -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.

Discovery finds nothing

sudo nmap -sn 192.168.1.0/24

-sn is ping scan. If that finds nothing either, subnet visibility is the issue.

Uninstall

sudo systemctl stop vesana-collector
sudo systemctl disable vesana-collector
sudo rm /etc/systemd/system/vesana-collector.service
sudo rm -rf /etc/vesana
sudo rm /usr/local/bin/vesana-collector
sudo systemctl daemon-reload

In Vesana: Admin → Collectors → Delete. Hosts assigned to the deleted collector must be reassigned, otherwise their services go NO_DATA.

Next