Info

License: Free — part of the universal collection tier.

Warning

The configured program runs as the agent user (root on Linux, LocalSystem on Windows). Read the security notes below before enabling this probe.

Exec Probe

The exec probe runs an operator-supplied program on interval and turns its output into metrics — the custom-check long tail. Two output contracts are supported:

• Nagios plugin convention (default): exit code carries the status, perfdata after the | carries the measurements. Existing check_* plugins work unchanged.
• JSON contract: a structured document for new scripts.

Quick start

# probes.d/10-exec.yaml — each file under probes.d/ is a YAML array of probes
- name: raid-status
  type: exec
  params:
    command: /usr/lib/nagios/plugins/check_raid
    args: ["-p", "1"]
    interval: 120
    timeout: 30

Parameters

Parameter	Must set	Default	Description
command	Yes	-	Absolute path of the program; no shell, no PATH lookup. Example: /usr/local/bin/check_backup
args	No	-	Arguments passed verbatim; anything secret here is stored as typed
format	No	nagios	Output format. One of nagios, json
interval	No	60	Seconds between runs; keep it above the timeout
timeout	No	10	Seconds before the process group is killed
workdir	No	-	Working directory; the agent's by default
env	No	-	Extra environment variables; values named like credentials are sealed

env entries are added on top of the agent's own environment, which the program inherits.

Nagios contract

$ ./check_queue
WARN - queue depth high | depth=42;10;50 'wait time'=230ms
$ echo $?
1

• Exit code 0/1/2 maps to ok/warning/critical; anything else (and a timeout kill) is unknown (3). Reported as senhub.exec.status.
• Each perfdata token becomes a metric named senhub.exec.<label> (label lowercased and sanitized). Time units are normalized to seconds (230ms becomes 0.23), byte units to bytes, and the c UOM marks the value as a counter. Warn/crit/min/ max thresholds are accepted and ignored — thresholds belong in your alerting layer.
• Malformed perfdata tokens are skipped; one bad token never voids the check.

JSON contract

{
  "status": 0,
  "metrics": [
    {"name": "queue.depth", "value": 12, "tags": {"queue": "orders"}},
    {"name": "processed", "value": 4012, "type": "counter"}
  ]
}

• status (0..3) is optional; without it the exit code is mapped exactly like the Nagios contract.
• type is gauge (default) or counter. tags become metric tags. Names are namespaced under senhub.exec.* and sanitized.

Self-metrics

Metric	Description
senhub.exec.status	0 ok, 1 warning, 2 critical, 3 unknown
senhub.exec.duration	Wall-clock run time
senhub.exec.timeout	1 when the run was killed on the deadline
senhub.exec.skipped	1 when a cycle was skipped because the previous run was still going

Security notes

This probe executes whatever the configuration points at, with the agent's privileges. The probe enforces what it can:

• Absolute paths only. PATH lookup is refused, so a writable directory earlier in PATH cannot shadow your check.
• World-writable executables are refused on Linux/macOS at probe start: a script any local user can rewrite is a privilege escalation, not a check.
• No shell. command + args go straight to the OS. Pipelines and redirections belong inside a script file that you own.

What remains your responsibility:

• Keep check scripts owned by root (or an admin account on Windows) and not group-writable; treat their directory the same way.
• Review what the script itself calls — the probe cannot audit transitive trust.
• Prefer read-only checks. A "check" that mutates state will run every cycle, forever.
• On Windows, lock down ACLs on the script; the world-writable test is Unix-only.

Operational notes

• Overlap protection. If a run outlives the interval, the next cycle is skipped and reported via senhub.exec.skipped — processes never pile up.
• Output caps. stdout/stderr are captured up to 1 MiB each.
• One probe instance per check. Each check gets its own probe block with its own interval and timeout, and shows up under its own probe name.

Metric reference

Every metric this probe can emit. Metric is the OpenTelemetry name the OTLP, Prometheus and Zabbix outputs derive theirs from. Name is what a Nagios check and the API metrics= filter match. PRTG channel is the label PRTG shows, placeholders filled from the series' tags.

Metric	Name	PRTG channel	Unit	Description
senhub.exec.status	senhub.exec.status	Check Status	#	Nagios plugin status: 0 ok, 1 warning, 2 critical, 3 unknown
senhub.exec.duration	senhub.exec.duration	Check Duration	ms	Wall-clock run time of the check
senhub.exec.timeout	senhub.exec.timeout	Check Timed Out	#	1 when the run was killed on the hard timeout
senhub.exec.skipped	senhub.exec.skipped	Cycle Skipped	#	1 when a cycle was skipped because the previous run was still going