FAQ¶

License and tester mode¶

We just want to try it — what does it cost?¶

Community edition covers 25 hosts and one tenant. Free. Setup as normal, no license key needed.

Difference between tester mode and Community?¶

Tester mode (VESANA_TESTER_MODE=true) gives all features, no license, with phone-home to license.vesana.org. Community is limited to specific features. Tester mode is for explicitly invited beta testers.

How long does an offline license run?¶

Standard 1 year. Renew before expiry — server warns 30 days ahead via banner.

Can I move a license to another instance?¶

Yes: deactivate old instance, switch the license in the portal to the new instance UUID.

Tenants and multi-tenancy¶

Do I need multi-tenant for single-org use?¶

No. One single tenant „Internal" is enough.

Can a user be in multiple tenants?¶

Currently one main role per user. Cross-tenant visibility via custom roles with tenant.cross_view.

Does a customer user see other customer tenants?¶

No. Tenant isolation at ORM level — a query without tenant filter raises a runtime error.

Agents¶

My agent shows „outdated" — what to do?¶

Auto-update happens on the next config refresh (5 min). Impatient: restart service triggers update immediately.

Agent token lost — now what?¶

Host detail → Revoke token → Regenerate. Re-install on the machine with the new token.

Can I build my own agent?¶

Yes — repo code, cd agent && make build-all VERSION=v1.X.Y. Auto-update via VERSION file for own builds: set VESANA_AUTO_UPDATE=false in agent config.

How much CPU/RAM does the agent use?¶

Idle: ~10 MB RAM, < 1 % CPU. With active logs slightly more. Negligible vs. the monitored app.

Can the agent run on macOS?¶

Currently Linux/Windows only. macOS support on the roadmap.

Collectors¶

Do I need a collector per location?¶

If locations are separated by VPN: yes, one collector per location.

What does the collector do when server is unreachable?¶

Buffers check results locally (disk queue, similar to agent), sends them once the connection is back.

Does a collector scale with the number of SNMP hosts?¶

Up to ~500 hosts per collector without issues. Beyond that, set up a second collector and split hosts.

Checks and profiles¶

Why are some check types grayed out?¶

Capability filter:

Agent checks need a profile with agent_capable = true + token created
SNMP checks need snmp_enabled = true
Network checks need ip_address

I want to change a check type — can't?¶

Correct. check_type is immutable after creation. Delete and recreate.

How do I get a modified builtin back?¶

Profile modal → Reset. Only available when is_modified = true.

Can I return multiple values from a script?¶

Yes — agent_script with expected output nagios and perfdata: OK - text | metric1=v1 metric2=v2 metric3=v3. All perfdata land in check_results.perfdata JSONB.

Dashboard¶

My custom dashboard is slow¶

Possible causes:

Many widgets with the same query → use query caching
Heatmap with too high resolution → enlarge bucket
Variable with multi=true and 1000 hosts → limit values

Edit mode → visibility to public, get token URL. Share URL.

Do public dashboards lose data on token rotation?¶

Yes. Rotate the token and the old link is dead.

Alerts and notifications¶

How do I prevent alert storms during major outages?¶

Three tools:

Grouping in alert rule (grouping.by)
Inhibition via dependencies (parent switch CRIT → suppress child alerts)
Rate limit per channel (throttle)

Alert arrives too late¶

Soft/hard model: default 3 attempts × 60 s = 3 min. With retry interval (15 s) shorter. Adjust per profile-check.

Will I get recovery notifications?¶

Default yes. Per channel disableable.

What about time periods („alert only Mon–Fri 8–18")?¶

Currently not directly. Workaround: cron filter in alert rule. Native time period on roadmap.

Mobile app¶

iOS?¶

No iOS build currently. On roadmap.

Sometimes happens — api.resetClient() sets the axios client to null. Restart app or disconnect server + re-pair.

Push delivered offline when server is back online?¶

Not automatically — FCM discards notifications the device didn't accept while offline. You see them later in the app's notification screen.

Updates¶

Update aborts with „Health check timeout"¶

Migrations are slow on big tables. Auto-rollback triggered — old version keeps running. Actions:

Set UPDATE_HEALTH_TIMEOUT=300 in .env
Run update outside business hours when DB is loaded
Suspect concrete migration issue: open issue with logs

When are columns dropped?¶

Earliest 2 majors after deprecation. Migrations are additive — rollback conditionally possible (within deprecation window).

Can I pin a specific version?¶

Yes: in .env VESANA_UPDATE_CHANNEL=pinned:0.18.5. GUI updater pulls only this version.

Backup and restore¶

How often do backups run?¶

With backup sidecar: default daily 02:00 UTC, 7 days retention. Configurable.

How do I get the `FIELD_ENCRYPTION_KEY` back if it's gone?¶

You don't. Encrypted DB fields are then lost. So: store the key in password manager + printed in a safe.

Can I export a single tenant?¶

Not directly — pg_dump is the whole DB. Workaround: custom script exporting tenant data via API.

API¶

Does Vesana offer a read-replica endpoint?¶

No. Spin up API replicas behind pgbouncer if needed.

Can I batch PATCH operations?¶

Currently each PATCH separately. Bulk operations only for tags and profile apply.

What's the rate limit?¶

600 req/min per user for regular endpoints, 10 req/min/IP for login/2FA.

AI¶

What happens to our data at Anthropic?¶

Request content goes to Anthropic API. For privacy concerns: switch provider to local Ollama — nothing leaves the stack.

How much does AI cost?¶

Anthropic: a few cents per request. With many requests, can be tens of euros monthly — set a cost cap in Anthropic dashboard.

Do I need internet for AI?¶

Only with cloud providers. For local Ollama: only for model download.

Other¶

Can I put Vesana behind a VPN/bastion?¶

Yes, all web endpoints are pure HTTPS — any reverse proxy / VPN topology in front.

Does Vesana do telemetry?¶

Optional update check against license.vesana.org. Tester mode also has phone-home with {instance_id, hostname, version}. That's all. Content (hosts, checks, values) never leaves the server automatically.

Is ESXi supported?¶

Via SSH (ssh_command, ssh_cpu, ssh_mem, ssh_disk). Direct vSphere API access currently as custom script.

Can I run Vesana on Kubernetes?¶

Currently we support Docker Compose. Helm chart on roadmap. If you DIY: Compose file is the template, migration to manifests is mechanical.

Next¶

Troubleshooting — structured symptom list
System health