Nagios Plugins

Plugin: scripts.d.plugin Module: nagios

Overview

This module runs unmodified Nagios plugins inside Netdata without any changes to the plugins themselves.

For each configured job it collects:

• Check state: OK / WARNING / CRITICAL / UNKNOWN (with soft/hard state tracking).
• Performance data: Every label=value;warn;crit;min;max metric emitted by the plugin is parsed and charted automatically, with unit normalization where possible.
• Execution telemetry: Runtime duration, scheduling latency, CPU time, peak RSS memory, and disk I/O per job.
• Scheduler health: Running / queued / scheduled job counts and throughput rates.

Jobs are executed via nd-run (the Netdata unprivileged helper) at the configured check_interval. Standard Nagios macros ($HOSTADDRESS$, $ARG1$, $USERn$, etc.) are expanded before execution. Plugin output is parsed according to the Nagios Plugin API: the first line provides the status and optional performance data after the | separator.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

Plugins run as the netdata user via nd-run. If a plugin requires elevated privileges, configure it through ndsudo or adjust filesystem permissions accordingly.

Default Behavior

Auto-Detection

No auto-detection. Each job must be explicitly configured with a plugin path pointing to the Nagios plugin executable.

Limits

The default configuration for this integration does not impose any limits on data collection.

Performance Impact

Each job spawns a subprocess via nd-run. Resource usage (CPU, memory, disk I/O) is tracked per execution and exposed as telemetry charts.

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Virtual Node Label Conventions

When a job references a vnode, the module reads Nagios macros from the virtual node's labels using prefix conventions:

Label key	Nagios macro	Environment variable	Description
_address	$HOSTADDRESS$	NAGIOS_HOSTADDRESS	IP address or DNS name of the host
_alias	$HOSTALIAS$	NAGIOS_HOSTALIAS	Human-readable host alias
_VARNAME	$_HOSTVARNAME$	NAGIOS__HOSTVARNAME	Custom host variable (any _ prefixed key except _address and _alias)
key	$_HOSTLABEL_KEY$	NAGIOS__HOSTLABEL_KEY	Regular label (no _ prefix)

Example vnode configuration (/etc/netdata/vnodes/hosts.yaml):

- hostname: web-server-1
  guid: 12345678-1234-1234-1234-123456789abc
  labels:
    _address: "192.168.1.10"
    _alias: "Web Server 1"
    _DATACENTER: "us-east-1"
    role: "frontend"
    environment: "production"

This produces:

Macro	Value
$HOSTADDRESS$	192.168.1.10
$HOSTALIAS$	Web Server 1
$_HOSTDATACENTER$	us-east-1
$_HOSTLABEL_ROLE$	frontend
$_HOSTLABEL_ENVIRONMENT$	production

Per job

Metrics for each configured Nagios plugin job.

Labels:

Label	Description
nagios_job	Job name as defined in the configuration.
nagios_plugin	Basename of the plugin executable.
nagios_vnode	Virtual node associated with the job (if any).
nagios_scheduler	Scheduler executing the job.

Metrics:

Metric	Dimensions	Unit
nagios.jobs.state	ok, warning, critical, unknown	state
nagios.jobs.runtime	running, retrying, skipped	boolean
nagios.jobs.latency	duration	seconds
nagios.jobs.cpu	cpu	seconds
nagios.jobs.mem	rss	bytes
nagios.jobs.disk	read, write	bytes

Per perfdata

Metrics extracted from the plugin's performance data output. Each label=value;warn;crit;min;max entry produces a separate chart.

Labels:

Label	Description
nagios_job	Job name.
nagios_plugin	Plugin executable.
perf_label	Performance data label as emitted by the plugin.

Metrics:

Metric	Dimensions	Unit
nagios.{script}.{label}	value	varies

Per scheduler

Scheduler-level metrics.

Labels:

Label	Description
nagios_scheduler	Scheduler name.

Metrics:

Metric	Dimensions	Unit
nagios.scheduler.jobs	running, queued, scheduled	jobs
nagios.scheduler.rate	started, finished, skipped	jobs
nagios.scheduler.next	next	seconds

Alerts

There are no alerts configured by default for this integration.

Setup

Prerequisites

Install Nagios plugins

Install the plugins you want to run. Most distributions provide packages:

# Debian/Ubuntu
apt install nagios-plugins

# RHEL/CentOS/Fedora
dnf install nagios-plugins-all

You can also use any script or binary that follows the Nagios Plugin API.

Configuration

Options

Each job defines a single Nagios plugin execution. Jobs are listed under the jobs key.

Config options

Group	Option	Description	Default	Required
General	plugin	Absolute path to the Nagios plugin executable.		yes
Arguments	args	Command-line arguments passed to the plugin. Nagios macros are expanded before execution.	[]	no
	arg_values	Values bound to positional $ARGn$ macros (max 32).	[]	no
General	vnode	Virtual node name to associate with this job. The vnode must be defined in the vnodes configuration directory.		no
	scheduler	Name of the scheduler that executes this job.	default	no
Timing	timeout	Maximum execution time before the plugin is killed. Duration string (e.g. 30s, 1m).	30s	no
	timeout_state	State reported when a timeout occurs.	critical	no
	check_interval	Base scheduling interval between executions. Duration string.	1m	no
	retry_interval	Interval between soft retries after a non-OK result. Duration string.	30s	no
	max_check_attempts	Number of soft-state attempts before transitioning to a hard state.	3	no
Environment	user_macros	Key/value pairs exposed as $USERn$ macros. For example, USER1 becomes $USER1$.	{}	no
	custom_vars	Key/value pairs exported as $_SERVICEvar$ environment variables (NAGIOS__SERVICEvar).	{}	no
	environment	Additional environment variables set before executing the plugin.	{}	no
General	working_directory	Working directory for plugin execution.		no

via File

The configuration file name for this integration is scripts.d/nagios.conf.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config scripts.d/nagios.conf

Examples

SSL certificate check

Check SSL certificate expiry for a host.

Config

jobs:
  - name: ssl_github
    plugin: /usr/lib/nagios/plugins/check_http
    args: ["-H", "github.com", "--ssl", "-C", "30,15"]
    timeout: 30s
    check_interval: 1h
    retry_interval: 5m
    max_check_attempts: 3

Check with macros and vnode

Run a plugin against a virtual node using Nagios macros. The $HOSTADDRESS$ and $ARG1$ macros are expanded from the vnode labels and arg_values.

Config

jobs:
  - name: check_ssh
    plugin: /usr/lib/nagios/plugins/check_ssh
    args: ["-H", "$HOSTADDRESS$", "-p", "$ARG1$"]
    arg_values: ["22"]
    vnode: my-server
    check_interval: 5m

Check with custom vars

Pass service-level custom variables to a plugin as $_SERVICEvar$ macros.

Config

jobs:
  - name: check_api
    plugin: /usr/local/bin/check_api
    args: ["-u", "$_SERVICEENDPOINT$"]
    custom_vars:
      ENDPOINT: "/health"

Troubleshooting

Plugin exits with "permission denied".

Macros like $HOSTADDRESS$ are not expanded.