Skip to content

Check type reference

This page is the reference of all check types Vesana knows — sorted by who runs them.

Every check runs in exactly one of three modes: passive (collector in the customer network), agent (agent on the target machine) or active (the Vesana server checks itself — the active collector, called "Active-Checker" in the UI). A network check returns the same result everywhere — only the executor changes. A passive check on a host without a collector is automatically moved to active mode instead of staying unexecutable.

Each check type has exactly one set of fields — "Add check", the profile editor and "Edit check" show the same fields. What is not listed there is not read by the execution either. The Target field only appears for types that read it (HTTP checks bring their own target as a URL).

Server checks stay outside

Checks the Vesana server runs itself cannot reach server-internal addresses (loopback, Docker networks, the server's own interface addresses) — unless the check was saved by a super admin. A dedicated collector in the customer network checks its own network without restriction (from v1.9.437). Details: Active collector.

How a check forms its status

Every type judges in one of four ways. This decides whether the Threshold Warning/Critical fields can be used at all:

Verdict Meaning Threshold fields
Thresholds The check delivers a number; Warning/Critical decide. visible, effective
Judges itself The check knows its status (port open/closed, service active/inactive). There is no usable number. hidden — they would have no effect
Judges itself + measured value Command and script checks: the check sets the status itself and delivers a number. Thresholds additionally apply to the measured value and can only sharpen the status, never soften it. visible; locked with a reason as long as the script delivers no numeric value
Own limits in the configuration SSL certificate (days until expiry) and internet line (percent of the booked rate) carry their limits in type-specific fields. locked — the generic thresholds would produce permanent CRITICAL here

In the check view and in the configuration, the verdict is one sentence in the "Threshold verdict" block, right next to what is measured: 71 % ≥ 50 % ⇒ WARNING · Warning from 50 % · Critical from 80 % — from profile "Generic Linux Server". The check message carries the same reasoning whenever the threshold explains the status — even when the agent or collector already set the status itself.

Network checks

Catalog cleanup (v1.9.449)

Some types no longer appear under "Single checks" but keep running for existing checks and stay editable: vsphere (legacy, replaced by api_script), snmp_storage (created by the device scan; snmp with a reference OID does the same by hand), snmp_disk_status/snmp_disk_temp (hard-coded Synology OIDs — the "Synology NAS" hub profile reads disks via walk) and ssh_command (identical to ssh_custom).

Run via the collector (passive) or the active collector (active). No agent needed.

ping — Ping

ICMP ping to the device: reachability and response time (ms). The measured value is the response time; thresholds Warning 100 ms / Critical 500 ms (default). Also runs in agent mode — the agent then pings the Target (agent mode only) field (target) from the machine.

port — Port check

Checks whether a TCP port is reachable. Field Port (port). Judges itself.

Field Expectation (expect): Port must be reachable (default, open = OK) or Port must be closed — an open port is then CRITICAL. For services that are deliberately switched off (e.g. SSH on a NAS): the closed port is the intended state there, not the exception.

http — HTTP/HTTPS

Calls a URL (url) and checks the status code. The measured value is the response time (ms), thresholds 1000 / 5000 ms (default). {host} in the URL is replaced by the device address.

The message always states what was checked: GET https://example.com → HTTP 200 in 12 ms (expected 2xx/3xx). The expectation is configurable (since v1.9.449):

Field Effect
Expected status code (expected_status) Empty: 2xx/3xx are OK, 4xx WARNING, 5xx CRITICAL. Set (200, 200-299, 2xx, 200,204, 401, any): only the listed codes are OK, everything else CRITICAL. A page that rejects anonymous visitors with 403 is checked with 403.
Response must contain (content_match, regex) If the pattern is missing from the body the check is CRITICAL — even on HTTP 200 (“something answers” is not “the application works”).
Method (method) GET (default) or HEAD (no body, no content check).
Do not follow redirects (no_redirects) The 3xx response itself counts; otherwise up to 10 redirects are followed.
Skip TLS verification (tls_skip_verify), Timeout (timeout, default 10 s) for self-signed device UIs and slow endpoints.

The check details show URL, final URL after redirects, status code, expectation, response time, Server and Content-Type headers, size, the certificate's remaining validity for HTTPS and the result of the content check.

http_json — HTTP API (JSON/text)

Calls a URL and extracts one scalar value from the response. Usually comes via device profiles with a pre-filled configuration (e.g. Proxmox VE, Sonos) and is not selectable in the free catalog; it can be edited like any other check.

Field Key Meaning
URL url {host} is replaced by the device address, {host_hostname} by its hostname
Method method GET (default) or POST
Authentication auth empty (default) or device_api — logs in with the username + password from the host's device API access via HTTP Basic (e.g. OPNsense, TrueNAS, UniFi: key + secret instead of a token header). If no account is stored on the device, the check honestly reports UNKNOWN instead of a 401 that looks like a device outage
Value path (JSON) value_path path to the measured value (notation below)
Value pattern (regex) value_regex alternative to the JSON path for text/XML responses; the first capture group is the value
Aggregate multiple matches value_regex_aggregate first match (default), number of matches, sum, maximum, minimum, average
Divisor path (JSON) divisor_path value ÷ this value — e.g. used ÷ total
Scale factor value_scale factor applied to the value
Unit · Label unit · label display
Response must contain content_match if the text is missing from the response, the check is CRITICAL — verifies that the expected device really answers
Skip TLS verification tls_skip_verify for self-signed internal endpoints
Request body body POST only

Credentials such as an API token or the device API account belong to the host, not the check — see Proxmox for an example.

Scalar values only

A numeric hit becomes the measured value (graph, thresholds); a text hit lands in the message and can be judged via a comparison with an expected value. Objects and lists are not supported — except as a count (#, see below).

Aggregating multiple matches — what sets \"number of matches\" apart

Number of matches counts how often the pattern occurs in the response — with no match the measured value is 0, not UNKNOWN: "no match" is the statement here (e.g. how many services report "running":0). Sum / maximum / minimum / average instead evaluate the NUMBERS found and need at least one — no numeric match stays UNKNOWN.

value_path notation

Not full JSONPath, but a small, predictable subset:

Notation Meaning
a.b field in an object
a.0 / a[0] list element (negative indices count from the end)
a[k=v] filter a list: only elements whose field k equals v
a[k!=v] the same, negated
a[k^v] field k is text and starts with v
a[k!^v] the same, negated
a# count of elements (or length of object/text)

Filters can be chained; they then all apply at once (AND). This turns a list into countable values:

data[type=qemu][status=running]#                            # running VMs
data[type=vzdump][saved=1][status!=OK][status!^WARNINGS]#   # failed backups

Prefix instead of equality when the text contains a number

Proxmox writes OK, an error text or WARNINGS: 3 into status — with the count in the text. Such a value cannot be matched by equality; [status^WARNINGS] matches it regardless of the number.

ssl_certificate — SSL certificate

Checks a TLS certificate and monitors its expiry. Runs passive, active or via the agent. Default interval 6 hours.

Field Key Default Meaning
Hostname / domain hostname – name the certificate is issued for — connected and verified (SNI). Empty = DNS name or IP of the device
Port port 443
Connection target (optional) connect_to – only if the connection should go to a different address; verification still uses the hostname
WARNING below remaining days warn_days 30
CRITICAL below remaining days crit_days 14
Allow self-signed certificates allow_self_signed off no alarm for self-signed certificates or name/chain mismatches; expiry is still monitored
OCSP revocation check check_ocsp off additionally ask the issuer whether the certificate was revoked
Timeout (seconds) timeout – under "Advanced"

The limits live in the day fields

The measured value is the remaining lifetime in days. The generic threshold fields are locked for this type — values set via API, bulk edit or profile import do not reach the execution either. They used to produce permanent CRITICAL.

internet_line — Internet line (speed test)

Down-/upload against the booked bandwidth, ping under load, packet loss, public IP. Own page: Monitoring internet lines. Here too, the limits (WARNING/CRITICAL below % of target) live in their own fields; the generic thresholds are locked.

vsphere — VMware ESXi (API) (legacy)

Reads an ESXi host via the vSphere API — CPU, memory, datastores, VMs, uplinks, hardware health; needs no shell access, an account with the "Read-only" role is enough. Stays in place for existing ESXi profiles and keeps running. New ESXi checks use api_script (see below) instead — the same route via the API, but as a script in the library rather than a hard-wired Go type, so the body can be read and adjusted.

api_script — Script (API)

An editable script from the script library that the collector runs locally and that logs in to a device API itself — for devices with an API but no (usable) shell. Typical example: ESXi — a monitoring account with the "Read-only" role may log in via the API but not into the shell (ESXi access rights hang on the role, not on a "shell access" checkbox). ssh_script is out (the body would run ON the target device, which doesn't grant that shell); agent_script is out because the device cannot carry an agent (appliance). api_script closes the gap: the collector runs the body itself, and the body talks to the device API on its own.

The body reaches the API itself over HTTP(S) (SOAP on ESXi); target and credentials arrive as environment variables:

Environment variable Source
VESANA_TARGET address of the device
VESANA_API_USER / VESANA_API_PASSWORD the host's device API account; without one, the host's SSH credentials are used as a fallback
VESANA_API_PORT field API port (port, default 443)
VESANA_API_INSECURE field Skip TLS verification (tls_skip_verify) — for appliances with a self-signed certificate (ESXi out of the box)

Evaluation and value extraction follow the same contract as the command/script checks — see Evaluation of command and script checks. Default interval 5 min.

SNMP checks

What the value MEANS lives in one place

snmp, snmp_oid and snmp_string have an Interpretation block in their configuration: mapping a state value (value → label → status), converting a metric (factor, offset, unit, display) and evaluating a text — with preview and OID catalog. The fields listed below are the technical underpinning of it. Operation, examples and symptoms: SNMP interpretation.

Prerequisite: host with an IP address and SNMP credentials. All SNMP types have the field Community (override) (community) under "Advanced" — only fill it in if exactly this check needs a different community than the device.

snmp, snmp_oid and snmp_string additionally have the field Value display (value_format) — converts the raw numeric value for the MESSAGE only; the measured value itself (and therefore the thresholds) stays unchanged:

Value Meaning
Number as measured (default) no conversion
Duration from timeticks duration_ticks — timeticks (1/100 s, e.g. sysUpTime) become seconds; "17993930" becomes "2d 1h 58m". The legacy notation unit: ticks keeps working
Duration from seconds duration_s — value stays in seconds, message shown as a duration
Bytes, human-readable (KB/MB/GB) bytes — value stays in bytes (thresholds apply in bytes)
SI prefix on the unit si — k/M/G/T in front of the unit, 1000000000 bit/s becomes "1.0 Gbit/s"

Every walked row visible under \"Details\"

SNMP checks that query a table column (snmp with walk_oid, snmp_row_watch) show every row with its label and value under "Details" in the status panel (up to 50, with the count of remaining rows shown above that). For maximum/minimum aggregation, the row that decided the status is marked.

snmp — SNMP query

Query a single OID or a whole table column and condense it to one numeric value. Thresholds decide.

Field Key Meaning
OID oid a single OID
Table column (walk OID) walk_oid read a whole column instead of one OID and condense it to one value
Aggregation aggregate maximum (default), minimum, average, sum, row count
Unit · Scale factor · Offset unit · scale · offset display, or e.g. 0.001 for mW → W; offset applies AFTER the scale factor (Kelvin → °C: −273.15) — only for a SINGLE OID, not for a table walk
Value display value_format see above — for a table walk, not with "row count" aggregation and not when a reference column (percent) is set

Under "Advanced" the rest of the walk contract that makes the good device profiles:

Field Key Meaning
Reference column (walk OID) · Reference OID (single) total_walk_oid · total_oid second quantity as reference — the value then becomes percent (value ÷ reference × 100)
Invert reference (free instead of used) invert computes 100 − percent, for columns that report the free share
Skip rows up to this value skip_below for tables that report −1 or 0 when a sensor is absent
Name column (OID) label_column_oid plain-text names of the rows — prerequisite for filtering and labelling
Exclude names (contains) label_exclude rows whose name contains one of the terms are dropped
Monitor only this name label_match watch exactly this row; if it is missing, that is CRITICAL, not UNKNOWN
Merge rows with the same name distinct_label

snmp_string — SNMP text

Read an OID as text and check it against an expected value. Judges itself.

Field Key Meaning
OID oid
Expected value match_value
Treat expected value as regex is_regex without the checkbox the text must match exactly
CRITICAL when it matches fail_if_match inverts the logic: match = failure
Status per value / Label per value value_map / value_labels numeric value → status resp. → plain text for the message; a value with no mapping gets Status without mapping (unmapped_status, default WARNING), never a silent OK
Unit · Scale factor · Offset · Value display unit · scale · offset · value_format for numeric values — display as above

Evaluating bitmasks

For OCTET-STRING bitmasks (e.g. hrPrinterDetectedErrorState) the check carries plain text and severity per set bit: Bitmask: bit → text (bit_labels), Bitmask: bit → severity (bit_severity, WARNING or CRITICAL per bit) and Bitmask: message with no bit set (bits_ok_message). These three fields are only ever filled in via profile import — existing checks without a bitmask behave unchanged.

snmp_oid — SNMP state / single value (OID)

Created by the SNMP sensor picker (discovery walk → "Adopt as check"). Branches on the Value type (value_type):

  • gauge (default): numeric value, thresholds apply as with snmp. Field Value display (value_format, see above) converts the message.
  • status: the value is a category — OK values / WARNING values / CRITICAL values (ok_values/warn_values/crit_values) determine the status, an unlisted value gets Status without mapping (unmapped_status, default WARNING). The threshold fields are ignored in this mode.

The number → text mapping (value_labels) arrives via profile import.

snmp_storage — SNMP storage (hrStorage) (no longer in the catalog)

Created by the sensor picker: usage of a volume in percent from three OIDs (OID used / OID total size / OID block size — oid_used/oid_size/oid_unit). Thresholds 80 / 90 % (default), interval 5 min.

snmp_interface — SNMP interface status

Operational state of an interface (ifOperStatus) via the Interface index (if_index). Judges itself; comes via profiles and the sensor picker.

snmp_table — SNMP table dump

Reads a whole SNMP table as a snapshot (device snapshot) — the basis for the port map, NAS disk bay, UPS and firewall panels. Field Snapshot type (snapshot_type). Comes via profiles.

snmp_table_state — Worst state of a table

Reads a status column (walk_oid) and reports the worst entry based on Values meaning OK/WARNING/CRITICAL. Under "Advanced": name column, Name filter (name_filter, with Filter effect include/exclude) and Skip row indexes (ignore_indexes). Comes via profiles. Under "Details" ALL entries of the table are listed, not just the ones with a problem.

snmp_row_watch — SNMP row watcher

CRITICAL when a named entry disappears from an SNMP table — typically a SonicWall VPN tunnel. Default OIDs are pre-filled; you only enter the Name of the entry (label_match, e.g. the VPN policy name). Comes via device profiles.

snmp_disk_status / snmp_disk_temp — Disks (SNMP) (no longer in the catalog)

Status or temperatures of all disks via SNMP walk (Synology). Status judges itself; temperature with thresholds 45 / 55 °C (default).

SSH checks

The collector logs in to the device via SSH and runs a command. SSH credentials are maintained on the host; every SSH check has the fields SSH user / SSH password / SSH port / SSH target (override) under "Advanced" — only fill them in if exactly this check should log in differently (e.g. via a jump target in the same network).

Rejected credentials and unreachable devices

If the SSH credentials are rejected, the collector remembers this per device and attempts no further login for 15 → 30 → 60 minutes — previously several failed attempts ran per check and interval, which devices treat as an attack (account lockout, blocklist). Affected checks stay Unknown with plain text (user, target, end of the pause); changed credentials or an immediate check lift the pause at once. If the device is not reachable via SSH at all (connection refused/timeout), the check is Critical, not Unknown (from v1.9.437).

ssh_cpu, ssh_mem, ssh_disk — CPU, RAM, disk (SSH)

Standard commands for Linux devices without an agent. Thresholds 80 / 95 % (CPU, RAM) or 80 / 90 % (disk). ssh_disk has the field Mountpoint (mount, default /).

Not for ESXi

ESXi only allows accounts with the "Admin" role into the shell — a read-only monitoring account would need admin rights just to get in. For ESXi, use api_script (see the "Script (API)" section above): the same metrics via the vSphere API, with a read-only account.

ssh_process, ssh_service — Process, service (SSH)

Checks whether a Process name (process) is running or a systemd Service name (service) is active. Judge themselves.

ssh_custom, ssh_command — Custom command, command with evaluation (SSH) (ssh_command no longer in the catalog)

Run a custom Command (command) via SSH. Both read the same evaluation contract (below: Evaluation of command and script checks).

ssh_script — Script (SSH)

Run a script from the script library via SSH — centrally managed, with configurable values. Evaluated according to the output format declared on the script, exactly as on the agent; Python scripts run with the Python interpreter, shell scripts fall back to sh when the device has no bash (ESXi, appliances).

Agent checks

Prerequisite: agent installed and host agent-managed. The rich types (disks, services, process, eventlog, containers) have their own guided editors with suggestions from the host inventory.

agent_cpu, agent_memory — CPU, RAM

Usage in %, thresholds 80 / 95 (default).

agent_disk — Disks

Monitor all partitions automatically; limits as percent or as free space in GB, per-drive overrides, excluded drives. A single unreadable volume does not pull the check to UNKNOWN — the status comes from the readable drives, the unreadable one is named in the message. Interval 5 min.

agent_service — Service

Service name (service, systemd unit or Windows service). OK when active, otherwise CRITICAL.

agent_services_auto — Services (automatic)

All services with startup type "Automatic" — every one not running is CRITICAL. Exclusions (also with wildcards) match name and display name.

agent_process — Process

Is a process running (minimum/maximum count)?

agent_eventlog — Eventlog

Filter and count the Windows event log or the Linux journal (journald) — log, level, time window, event IDs (Windows only), sources or systemd units. The measured value is the number of entries in the window; thresholds 1 / 5 (default), interval 5 min.

agent_containers — Containers (Docker)

Monitor all Docker containers automatically (status, health, CPU/RAM/network) via the Docker socket; Docker socket (override) (socket) only for rootless Docker. Interval 2 min. Details: Host detail → Docker.

agent_custom — Custom command

Run a Command (command) on the machine. OK pattern (ok_pattern, default .) — if it matches the output, the check is OK; CRITICAL pattern (crit_pattern) takes precedence.

agent_script — Script

Run a script from the script library. Alternatively a local path on the machine or an inline script directly on the check — both with interpreter and output format on the check. Interval 5 min (default).

Nagios plugin

plugin_local — Plugin (Nagios)

Run a Nagios-compatible plugin via the active collector. Comes via the script library (interpreter "plugin_local"); details: NSCA & Nagios migration.

Special

nsca_passive

Packets from the NSCA receiver land in the pipeline as virtual checks. Detail: NSCA migration.

Evaluation of command and script checks

ssh_custom, ssh_command, ssh_script, api_script, agent_custom, agent_script and plugin_local judge themselves and deliver a measured value. For the SSH and API types you set the evaluation in plain language — no regex knowledge required:

When is this check OK?

Choice Meaning
The script decides via its exit code: 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN. The usual way.
Based on the output Reads as a sentence: The output must / must not · be exactly / contain · active. If the expectation does not hold (or the failure pattern matches), the check reports CRITICAL. The generated pattern is shown openly.
Own pattern for experts: a regex (match_regex) plus "When the pattern matches: the check is OK / CRITICAL" (fail_if_match). An existing pattern that cannot be expressed as a plain-language rule stays here unchanged.

Which number from the output is the measured value? — The first number in the output (default), The number at the start of the output, The number after a specific text or an own pattern with a capture group (extract_value); plus Unit of the value (value_unit). If the check finds no number, it stays valid — it just has no value, and the threshold fields are locked with a reason.

What applies:

  • When the output decides the status, the message says why: 0 · pattern "^0$" matches instead of a bare 0. Multi-line outputs are condensed to one line for this.
  • Empty output stays UNKNOWN — without output no result can be justified.
  • Library scripts are evaluated via SSH and on the agent according to the output format declared on the script (Nagios, text, JSON); with Nagios the measured value is the first perfdata metric.
  • Besides the measured value, a script can deliver multiple series (Nagios perfdata or JSON series) and a free details object — the series appear individually selectable in the history graph, the details when clicking the check. Details: Monitoring scripts.

Twelve bundled checks could never turn red

Until v1.9.358 the collector did not read the evaluation rule of SSH script checks; commands ending in || echo 0 always reported OK — affected were, among others, "Nginx service running", "Postgres service running", "WAN reachability (ICMP)" and "DNS recursion test". Since the update the rules apply. After updating, take a look at the error overview: what is red now was already broken before. Fields without effect were removed or renamed in the process ("Mount point" on Disk (SSH) silently measured /; "Process name"/"Service name" on the SSH checks; the expiry limits on the SSL certificate) — stored values keep working automatically.

Thresholds

Numeric checks usually do not evaluate themselves — the server compares the incoming value against Warning/Critical and sets the status.

  • Direction: high = bad (default) or low = bad — e.g. for free disk space or uptime since the last restart. Previously only adjustable on the profile, it can now also be switched on the individual check of a device — handy when only that one device needs the reversed direction.
  • Empty means inherited. On the host check the field only shows an own value for this device; the profile value stands next to it as a placeholder. What you leave empty follows along when the profile is updated. Only what you really change is pinned to the device — this applies to thresholds as to all other fields.
  • Takes effect with the next result, at the latest after five minutes (server cache) — the agent or collector does not need to reload anything. The server checks every incoming result against the currently valid limits, but only escalating: a hard failure (port closed, HTTP 500) is never downgraded by a harmless numeric value.
  • For script checks the limits apply in addition to the script's verdict and can only sharpen it. Limits belong on the check, not in the script — a number value on the script is meant for time windows, minimum counts and ports (Configurable values).
  • Confirmations: a first failure initially goes to PROBING — the worker repeats the confirmation as often as configured under "Advanced" (default 1× / 10 s) before treating the failure as confirmed. Details: State model.

"Check now" & intervals

"Check now" triggers a single check immediately, independent of the interval — handy when testing a new configuration. It requires the permission "Reschedule checks" (Operator and Admin have it, Viewer does not — from v1.9.437). Checks whose status comes from the check logic (interface/port status) keep it; changed thresholds take effect immediately.

What actually happens depends on where the check runs:

  • Active-Checker (check_mode='active'): measures synchronously and shows the result right away.
  • Agent or collector check: "Check now" does NOT run on the server what the agent or collector is actually supposed to run — an agent check doesn't exist on the server at all, and a passive target in the customer network is unreachable from the server anyway. Instead, the job goes to the agent or collector (picked up within roughly 60 s); the check stays on PENDING ("Waiting for data", blue) until the REAL result arrives.

Until the first result arrives, a freshly created check also shows the status PENDING — not an error, just "no data yet". This is now reliable: a new agent or collector check no longer flips to an UNKNOWN a few seconds later that actually came from the server being unable to run it.

The interval can be chosen between 10 seconds and 7 days; the check type cannot be changed after creation.

Common fields (all check types)

Field Meaning
Interval (s) how often (10 s ≤ x ≤ 7 days)
Confirmations · Confirmation interval (s) number and spacing of confirmation attempts in the PROBING state ("Advanced")
Threshold Warning / Critical numeric limits — only usable where they apply
Value type gauge / counter / status / info / duration — info means statistics only, never alerts
Use as reachability hint if this check fails, the device counts as unreachable; follow-up alerts are suppressed (normally the ping takes this role)

Which check type for which problem

Problem Recommendation
Is the device reachable? ping
Is the website up? http
Is Apache running? agent_service (with agent) or ssh_service (without)
CPU load? agent_cpu
Disk filling up? agent_disk
Events in journald/eventlog? agent_eventlog
Switch port status? device profile with port map (snmp_table)
UPS battery voltage? snmp with an OID from the UPS MIB
VPN tunnel monitored? snmp_row_watch (via a matching device profile)
Values from a REST API (e.g. Proxmox)? http_json with value_path
Backup successful yesterday? agent_script / ssh_script with a script from the library
Own logic? agent_custom / ssh_custom
Monitor an ESXi host (no shell access)? api_script with a vSphere API script (read-only account)
Bandwidth of the internet line? internet_line

Next