Skip to content

Monitoring scripts

When the built-in check types are not enough — a custom backup tool, a vendor-specific CLI, a REST API — monitoring scripts are the way.

Concept

Scripts live centrally in Vesana (script library) and are delivered to the agent or collector at runtime. Nothing is stored on the machine itself.

A script is a script — no matter where it runs. The same library script can run as agent_script (agent on the machine) or as ssh_script (collector via SSH); both evaluate according to the output format declared on the script. Via SSH, Python scripts run with the Python interpreter, and shell scripts automatically fall back to sh when the device has no bash (ESXi, appliances).

One script feeds many checks. Whatever differs per device (path, time window, exclusion list) the script declares as a configurable value — every check fills in its own fields. Copying the script body per check is no longer necessary; an improvement to the original reaches all checks.

Limits belong on the check, not in the script. Warning/Critical live in the check's "Threshold verdict" block — overridable per device, effective immediately. The script only prints the measured value.

Bundled and custom scripts

Bundled Custom
Origin Vesana itself or an imported community profile created yourself or as a copy of a bundled script
Visibility global — for all tenants belong to the tenant; a script of another tenant cannot be attached to your own checks (from v1.9.437)
Editing yes — afterwards the script is "modified" and receives no more updates yes

A script from a community profile is updated along with a profile update as long as you have not changed its content yourself. Locally adapted scripts stay untouched and are listed separately in the update result (Community hub).

Creating a script

Scripts (main navigation; super admins see the library page) → New script, or from a check via As own script (see below).

Field Meaning
Name unique per tenant
Description what the script is for
Interpreter PowerShell, Bash, Python — determines which hosts the script is offered to (Windows: PowerShell/Python, Linux: Bash/Python)
Output format Nagios, Text, JSON (see below)
Script the content, in the large editor window with line numbers; lines with # @vesana-param are highlighted

Next to the code, the editor window shows the detected configurable values and warns when a declared value is never read in the script (the field would have no effect).

Output formats

Nagios

The exit code determines the status: 0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN. Optional perfdata after |:

STATUS - description | label1=value;warn;crit label2=value

#!/bin/bash
LOAD=$(awk '{print $1}' /proc/loadavg)
if (( $(echo "$LOAD > 5" | bc -l) )); then
  echo "CRITICAL - Load $LOAD | load1=$LOAD;1;5"; exit 2
elif (( $(echo "$LOAD > 1" | bc -l) )); then
  echo "WARNING - Load $LOAD | load1=$LOAD;1;5"; exit 1
fi
echo "OK - Load $LOAD | load1=$LOAD;1;5"; exit 0

The first perfdata metric is the check's measured value (graph, thresholds). Perfdata is not part of the message.

Text

Free text, status only via the exit code (0 = OK, anything else CRITICAL). The first number in the output is taken as the measured value.

#!/bin/bash
if [ -f /tmp/maintenance ]; then
  echo "Maintenance mode active"; exit 1
fi
echo "Normal operation"; exit 0

JSON

Structured output, status freely chosen:

import json
print(json.dumps({
  "status": "OK",              # OK / WARNING / CRITICAL / UNKNOWN
  "message": "Backup from yesterday at 02:14",
  "value": 42,                 # optional, measured value
  "unit": "%",                 # optional
  "series": {"C:": 42, "D:": 13.5},          # optional, see below
  "details": {"jobs": [{"name": "Daily", "status": "ok"}]}   # optional, see below
}))

Series and details

A script can report more than one value:

  • Series — several numbers that appear in the history graph as individually selectable series (compare by clicking the legend). With Nagios: all perfdata tokens (| 'C:'=42% 'D:'=13%), with JSON the series key. The main value stays the first metric or value.
  • Details — a free details object in the JSON output (list of running websites, backup jobs, replication partners …). Clicking the check renders it generically: lists of objects as a table, single values as key/value. "What did the check actually see?" instead of just good/bad.
  • Device snapshot — if the check configuration carries a snapshot_type, the details feed the device visualization (e.g. the NAS disk-bay panel in the UGREEN profile, without any SNMP). Details: Device compatibility.

Both work via agent and SSH.

Binding a script to a check

Check type Script (agent_script) or Script (SSH) (ssh_script) → select the script under Configuration. The selection has a search and only shows scripts matching the host's operating system. Below the selected script are the configurable values and the preview "What the script receives".

If a check points to a script in the trash, it immediately shows "Script not found" — instead of a name that no longer applies.

For agent_script there are additionally Local path (a script already on the machine) and Inline script (content directly on the check) — both with interpreter and output format on the check. For anything that concerns more than one device, the library is the better place.

Editing the content directly on the check

The pencil on the script card opens the content in the large editor window. Before saving, it shows how many checks depend on this script, and you choose Save for:

Choice Effect
All checks changes the library script — improvements reach everyone (the normal case)
As own script creates a copy in the library and attaches only this check to it
Only this device own body for this check only; receives no more updates

A script from a community profile becomes a locally modified script through All checks and receives no more hub updates — for an addition only one device needs, Only this device is the more suitable way.

On the agent, a script change takes effect immediately (the host is nudged); collectors fetch their configuration every round.

Permissions

Scripts run with the privileges of the agent service — typically root on Linux, LocalSystem on Windows. Via SSH they run as the SSH user stored on the host.

Whoever may create scripts runs code on the devices

Creating and editing scripts is controlled by the permissions monitoring_scripts.create / .edit / .delete. Whether a user may create script-capable checks on a host is additionally controlled by their Script permissions (Users → Script permissions: all reachable tenants, a selection by tenant/tag/host, or none; without an explicit setting the role default applies — Admin: all accessible tenants, otherwise none). They apply to script checks as well as to checks with their own command ("Custom command" on the agent, "Command with evaluation" via SSH, Nagios plugins) — from v1.9.437 also to the latter. Ping, HTTP and SNMP checks do not need them. Details: Roles & permissions, Hardening.

Duplicate, delete, trash

  • Duplicate (Scripts page) creates your own copy — the usual way to adapt a bundled script without detaching it from updates.
  • Delete moves the script to the trash; afterwards it is neither retrievable via direct links nor editable and can be restored from the trash (from v1.9.437). Checks pointing to it do not run until then.

Audit

Script changes land in the audit log (Admin → Logs & Support → Audit log) with old and new values.

Next