| 1 | plugin_name: scripts.d.plugin |
| 2 | modules: |
| 3 | - meta: |
| 4 | id: collector-scripts.d.plugin-nagios |
| 5 | plugin_name: scripts.d.plugin |
| 6 | module_name: nagios |
| 7 | monitored_instance: |
| 8 | name: Nagios Plugins and Custom Scripts |
| 9 | link: https://www.nagios-plugins.org/ |
| 10 | categories: |
| 11 | - data-collection.synthetic-testing |
| 12 | icon_filename: nagios.png |
| 13 | related_resources: |
| 14 | integrations: |
| 15 | list: [] |
| 16 | info_provided_to_referring_integrations: |
| 17 | description: "" |
| 18 | keywords: |
| 19 | - nagios |
| 20 | - plugins |
| 21 | - checks |
| 22 | - scripts |
| 23 | - monitoring |
| 24 | overview: |
| 25 | multi_instance: true |
| 26 | data_collection: |
| 27 | metrics_description: | |
| 28 | This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts in any language (Bash, PowerShell, Python, Go, etc.). It provides: |
| 29 | |
| 30 | - **Check state monitoring** — tracks whether each check returns OK, WARNING, CRITICAL, or UNKNOWN |
| 31 | - **Execution metrics** — measures run duration, CPU time, and memory usage of each check |
| 32 | - **Automatic performance data charts** — any [Nagios performance data](https://nagios-plugins.org/doc/guidelines.html) in the check output is parsed and charted automatically |
| 33 | - **Threshold-based alerting** — when performance data includes warning/critical thresholds, Netdata derives threshold state and creates built-in alerts |
| 34 | method_description: | |
| 35 | Netdata executes each configured command on a schedule, reads the process exit code to determine the check state, and parses the standard output for a status message and optional [performance data](https://nagios-plugins.org/doc/guidelines.html). Any performance data is automatically converted into charts. |
| 36 | |
| 37 | :::tip |
| 38 | |
| 39 | You can use packaged [Nagios plugins](https://www.nagios-plugins.org/) or write your own scripts — any executable that follows the Nagios plugin output format will work. |
| 40 | |
| 41 | ::: |
| 42 | |
| 43 | <details open><summary><strong>Nagios Plugin Output Format</strong></summary> |
| 44 | |
| 45 | A Nagios-compatible plugin communicates through two channels: the **process exit code** and **standard output**. For the full specification, see the [Nagios Plugin Development Guidelines](https://nagios-plugins.org/doc/guidelines.html). |
| 46 | |
| 47 | #### Exit Codes |
| 48 | |
| 49 | The exit code is the **only** thing that determines the check state — the output text is for display purposes only. |
| 50 | |
| 51 | | Exit Code | State | Meaning | |
| 52 | |:---------:|:------|:--------| |
| 53 | | 0 | **OK** | Check passed | |
| 54 | | 1 | **WARNING** | Above warning threshold or degraded | |
| 55 | | 2 | **CRITICAL** | Above critical threshold or service down | |
| 56 | | 3 | **UNKNOWN** | Invalid arguments or internal error | |
| 57 | |
| 58 | #### Standard Output |
| 59 | |
| 60 | The output follows this structure: |
| 61 | |
| 62 | ```text |
| 63 | STATUS TEXT | perfdata1=val;warn;crit;min;max perfdata2=val |
| 64 | LONG OUTPUT LINE 1 |
| 65 | LONG OUTPUT LINE 2 | more_perfdata=val |
| 66 | ``` |
| 67 | |
| 68 | | Part | Description | |
| 69 | |:-----|:------------| |
| 70 | | **Status text** | Text before the pipe on the first line. Shown as the job's status message. | |
| 71 | | **Performance data** | Text after the pipe on any line. Parsed into charts automatically. | |
| 72 | | **Long output** | Lines 2+ before the pipe. Additional detail text. | |
| 73 | |
| 74 | > **Note:** The pipe separator is optional. Without it, the entire first line is the status text and no performance data charts are created. |
| 75 | |
| 76 | #### Performance Data Format |
| 77 | |
| 78 | Each performance data metric uses this format: |
| 79 | |
| 80 | ```text |
| 81 | 'label'=value[UOM];[warn];[crit];[min];[max] |
| 82 | ``` |
| 83 | |
| 84 | | Field | Required | Description | |
| 85 | |:------|:--------:|:------------| |
| 86 | | `label` | Yes | Metric name. Quote with single quotes if it contains spaces. | |
| 87 | | `value` | Yes | Numeric value. | |
| 88 | | `UOM` | No | Unit of measurement (see table below). | |
| 89 | | `warn` | No | Warning threshold range. | |
| 90 | | `crit` | No | Critical threshold range. | |
| 91 | | `min` | No | Minimum possible value. | |
| 92 | | `max` | No | Maximum possible value. | |
| 93 | |
| 94 | Separate multiple metrics with spaces. |
| 95 | |
| 96 | **Supported Units of Measurement (UOM):** |
| 97 | |
| 98 | | UOM | Meaning | How Netdata charts it | |
| 99 | |:----|:--------|:----------------------| |
| 100 | | *(none)* | Unitless number | Charted as-is | |
| 101 | | `s` | Seconds (also `ms`, `us`, `ns`) | Normalized to seconds | |
| 102 | | `%` | Percentage | Charted as percentage | |
| 103 | | `B` | Bytes (also `KB`, `MB`, `GB`, `TB`) | Charted in bytes | |
| 104 | | `b` | Bits (also `Kb`, `Mb`, `Gb`, `Tb`) | Charted in bits | |
| 105 | | `c` | Continuous counter | Charted as incremental rate | |
| 106 | |
| 107 | #### Threshold Ranges |
| 108 | |
| 109 | Thresholds use the format `[@]start:end`, where a bare number like `10` is shorthand for `0:10` and `~` represents negative infinity (no lower bound). An alert triggers when the value falls **outside** the range (or **inside** with the `@` prefix): |
| 110 | |
| 111 | | Range | Alert when... | |
| 112 | |:------|:--------------| |
| 113 | | `10` | value < 0 or value > 10 | |
| 114 | | `10:` | value < 10 | |
| 115 | | `~:10` | value > 10 | |
| 116 | | `10:20` | value < 10 or value > 20 | |
| 117 | | `@10:20` | 10 ≤ value ≤ 20 | |
| 118 | |
| 119 | When `warn` and `crit` ranges are provided on non-counter metrics, Netdata automatically derives a threshold state (ok / warning / critical) and creates charts with built-in alerts. |
| 120 | |
| 121 | **Common threshold patterns:** |
| 122 | |
| 123 | | I want to alert when... | `warn` | `crit` | |
| 124 | |:------------------------|:-------|:-------| |
| 125 | | Value exceeds a limit (e.g., response time > 2s) | `~:2` | `~:5` | |
| 126 | | Value drops below a floor (e.g., free space < 10%) | `10:` | `5:` | |
| 127 | | Value is outside a band (e.g., temperature 20–80) | `20:80` | `10:90` | |
| 128 | |
| 129 | #### Example |
| 130 | |
| 131 | A minimal Nagios-compatible script: |
| 132 | |
| 133 | ```bash |
| 134 | #!/bin/sh |
| 135 | echo "OK - 85% free memory | free_pct=85%;20:;10:;0;100 used_kb=2380912KB;;;0;16380000" |
| 136 | exit 0 |
| 137 | ``` |
| 138 | |
| 139 | This produces: |
| 140 | - **Check state**: OK (exit code 0) |
| 141 | - **Status text**: `OK - 85% free memory` |
| 142 | - **Charts**: `free_pct` (percentage with warning/critical thresholds) and `used_kb` (bytes) |
| 143 | |
| 144 | </details> |
| 145 | |
| 146 | :::info |
| 147 | |
| 148 | **Retry behavior:** When a check returns a non-OK state, Netdata does not alert immediately. The check enters a **soft state** and retries at the `retry_interval` rate. Only after `max_check_attempts` consecutive failures does it become a **hard state** and trigger alerts. If the check recovers during retries, it returns to OK without alerting. The `retry` dimension on state charts indicates a soft state is in progress. |
| 149 | |
| 150 | ::: |
| 151 | default_behavior: |
| 152 | auto_detection: |
| 153 | description: | |
| 154 | No automatic detection is performed. Add one or more jobs explicitly and point each job to the script or executable you want Netdata to run. |
| 155 | limits: |
| 156 | description: | |
| 157 | Each job runs one configured command. Additional charts are created only when the check emits Nagios performance data. |
| 158 | performance_impact: |
| 159 | description: | |
| 160 | Each job starts an external command. The impact depends mostly on how often the job runs and how expensive the check command itself is. |
| 161 | additional_permissions: |
| 162 | description: | |
| 163 | No additional permissions are required by the collector itself. If a check needs access to protected files, sockets, or system commands, provide that access to the check command or helper it uses. |
| 164 | supported_platforms: |
| 165 | include: [] |
| 166 | exclude: [] |
| 167 | setup: |
| 168 | prerequisites: |
| 169 | list: |
| 170 | - title: Security requirements for plugin executables |
| 171 | description: | |
| 172 | Netdata validates the `plugin` path before execution. On Linux/macOS, the executable must meet these requirements: |
| 173 | |
| 174 | - Must be a regular file (not a directory or device node) |
| 175 | - Must be executable (at least one execute bit set) |
| 176 | - Owned by **root** |
| 177 | - Not writable by group or others (no `g+w` or `o+w`) |
| 178 | - All ancestor directories (up to and including `/`) owned by **root** |
| 179 | - All ancestor directories not writable by group or others |
| 180 | - Symlinks are resolved — the target must meet these rules |
| 181 | |
| 182 | On Windows, path validation is not enforced. Ensure executables are stored in directories with appropriate ACLs. |
| 183 | |
| 184 | This prevents local privilege escalation through a modified check script. If validation fails, the job will not start and an error is logged. |
| 185 | |
| 186 | :::caution |
| 187 | |
| 188 | **Linux/macOS:** Using an interpreter (e.g. `/bin/bash`) as `plugin` with a script path in `args` is **discouraged**. Netdata validates the interpreter binary but **cannot verify scripts passed via `args`**. A writable script in `args` is a privilege escalation vector. Instead, make scripts directly executable and point `plugin` to the script itself. |
| 189 | |
| 190 | **Windows:** Point `plugin` directly to a `.ps1`, `.bat`, or `.cmd` script — Netdata invokes the correct interpreter automatically. Path validation is not enforced on Windows — ensure scripts are stored in directories with appropriate ACLs. |
| 191 | |
| 192 | ::: |
| 193 | - title: Install check commands |
| 194 | description: | |
| 195 | Install the Nagios plugins or other Nagios-compatible scripts that you want Netdata to run. |
| 196 | |
| 197 | Most Linux distributions provide Nagios plugin packages: |
| 198 | |
| 199 | ```bash |
| 200 | # Debian/Ubuntu |
| 201 | apt install nagios-plugins |
| 202 | |
| 203 | # RHEL/CentOS/Fedora |
| 204 | dnf install nagios-plugins-all |
| 205 | ``` |
| 206 | |
| 207 | Packaged Nagios plugins are typically installed as root-owned executables, which satisfies the security requirements above. |
| 208 | - title: Prepare custom check scripts |
| 209 | description: | |
| 210 | If you are writing your own check scripts instead of using packaged Nagios plugins: |
| 211 | |
| 212 | - Place scripts in a root-owned directory (e.g., `/usr/local/lib/netdata/checks/`) |
| 213 | - Set ownership and permissions: `sudo chown root:root /path/to/script.sh && sudo chmod 755 /path/to/script.sh` |
| 214 | - Test as the `netdata` user to verify permissions and environment: `sudo -u netdata /path/to/script.sh` |
| 215 | - Verify the exit code: `echo $?` (must be 0, 1, 2, or 3) |
| 216 | - Verify the output matches the Nagios plugin output format described in the Overview above |
| 217 | configuration: |
| 218 | file: |
| 219 | name: scripts.d/nagios.conf |
| 220 | options: |
| 221 | description: | |
| 222 | Add jobs under `jobs:`. Each job runs one Nagios-compatible check command. |
| 223 | folding: |
| 224 | title: Config options |
| 225 | enabled: true |
| 226 | list: |
| 227 | - name: update_every |
| 228 | description: Minimum resolution of the collector's scheduler, in seconds. `check_interval` and `retry_interval` are rounded up to the nearest multiple of this value. For example, if `update_every` is 10 and `check_interval` is 25s, the check actually runs every 30s. In most cases the default is fine — just set `check_interval`. |
| 229 | default_value: 10 |
| 230 | required: false |
| 231 | group: Collection |
| 232 | |
| 233 | - name: check_name |
| 234 | description: | |
| 235 | Name that identifies this check type for chart grouping and metric naming. If omitted, Netdata derives it from the basename of `plugin` (removing any file extension). Use this when the plugin filename is generic and you want a more descriptive chart section — for example, when multiple jobs run `check_nrpe` against different remote checks, set `check_name` to distinguish them (`check_disk`, `check_load`, etc.). |
| 236 | |
| 237 | In the dashboard, charts appear under `Synthetic > Nagios > Perfdata > <check_name>`. For example, with `check_name: check_memory` and a script that outputs `caches=2380912KB`, Netdata creates: |
| 238 | |
| 239 | - `nagios.perfdata.check_memory.job.execution_state` — check state (ok, warning, critical, unknown, timeout, paused, retry) |
| 240 | - `nagios.perfdata.check_memory.bytes_caches` — perfdata value chart |
| 241 | - `nagios.perfdata.check_memory.bytes_caches_threshold_state` — threshold state (if warn/crit thresholds are present) |
| 242 | default_value: "" |
| 243 | required: false |
| 244 | group: Target |
| 245 | - name: plugin |
| 246 | description: Absolute path to the Nagios-compatible check command to run. This can be a packaged Nagios plugin or your own executable script. The executable must be root-owned and not writable by group or others (see prerequisites). The command should return exit code `0`, `1`, `2`, or `3` and may print performance data after <code>|</code>. |
| 247 | default_value: "" |
| 248 | required: true |
| 249 | group: Target |
| 250 | - name: args |
| 251 | description: Arguments passed to the command. |
| 252 | default_value: "" |
| 253 | required: false |
| 254 | group: Target |
| 255 | - name: arg_values |
| 256 | description: Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. The first value maps to `$ARG1$`, the second to `$ARG2$`, and so on. |
| 257 | default_value: "" |
| 258 | required: false |
| 259 | group: Target |
| 260 | - name: working_directory |
| 261 | description: Working directory used when running the command. |
| 262 | default_value: "" |
| 263 | required: false |
| 264 | group: Target |
| 265 | |
| 266 | - name: timeout |
| 267 | description: Maximum time allowed for one command run. If the check exceeds this limit, the job state becomes `timeout`. |
| 268 | default_value: 5s |
| 269 | required: false |
| 270 | group: Scheduling |
| 271 | - name: check_interval |
| 272 | description: Interval between regular checks. |
| 273 | default_value: 5m |
| 274 | required: false |
| 275 | group: Scheduling |
| 276 | - name: retry_interval |
| 277 | description: Interval between retries while a check remains in a non-OK soft state. |
| 278 | default_value: 1m |
| 279 | required: false |
| 280 | group: Scheduling |
| 281 | - name: max_check_attempts |
| 282 | description: Number of attempts before a non-OK result becomes a hard state. |
| 283 | default_value: 3 |
| 284 | required: false |
| 285 | group: Scheduling |
| 286 | - name: check_period |
| 287 | description: Name of the [time period](/src/go/plugin/scripts.d/pkg/timeperiod/README.md) that controls when the job is allowed to run. The built-in `24x7` period (always allowed) is the default. Outside the active period, the check does not execute and the job state becomes `paused`. |
| 288 | default_value: 24x7 |
| 289 | required: false |
| 290 | group: Scheduling |
| 291 | - name: time_periods |
| 292 | description: Custom named [time periods](/src/go/plugin/scripts.d/pkg/timeperiod/README.md) defined inside the same job. Supports `weekly`, `nth_weekday`, and `date` rule types. |
| 293 | default_value: "" |
| 294 | required: false |
| 295 | group: Scheduling |
| 296 | |
| 297 | - name: environment |
| 298 | description: Extra environment variables added on top of the collector's limited execution baseline. The check does not inherit the full Netdata process environment. |
| 299 | default_value: "" |
| 300 | required: false |
| 301 | group: Environment |
| 302 | detailed_description: | |
| 303 | A key-value map of environment variables injected into the check's process. Use this when your script depends on variables that are not part of the collector's default environment. |
| 304 | |
| 305 | ```yaml |
| 306 | jobs: |
| 307 | - name: oracle_check |
| 308 | plugin: /usr/local/bin/check_oracle.sh |
| 309 | environment: |
| 310 | ORACLE_HOME: /opt/oracle/product/19c |
| 311 | LD_LIBRARY_PATH: /opt/oracle/product/19c/lib |
| 312 | ``` |
| 313 | - name: custom_vars |
| 314 | description: Custom service variables exposed to the check as Nagios-style macros. |
| 315 | default_value: "" |
| 316 | required: false |
| 317 | group: Environment |
| 318 | detailed_description: | |
| 319 | A key-value map of custom service variables. Each entry is exposed as a `NAGIOS__SERVICE<UPPERCASE_KEY>` environment variable and can be referenced in `args` using the Nagios macro syntax `$_SERVICE<KEY>$`. |
| 320 | |
| 321 | ```yaml |
| 322 | jobs: |
| 323 | - name: check_db |
| 324 | plugin: /usr/lib/nagios/plugins/check_pgsql |
| 325 | args: ["-H", "$_SERVICEDBHOST$", "-d", "$_SERVICEDBNAME$"] |
| 326 | custom_vars: |
| 327 | DBHOST: db.example.com |
| 328 | DBNAME: production |
| 329 | ``` |
| 330 | |
| 331 | - name: vnode |
| 332 | description: Associate the job with a virtual node so the check can use host-specific labels and macros. |
| 333 | default_value: "" |
| 334 | required: false |
| 335 | group: Virtual Node |
| 336 | |
| 337 | - name: notes |
| 338 | description: Optional notes for the job definition. |
| 339 | default_value: "" |
| 340 | required: false |
| 341 | group: Misc |
| 342 | examples: |
| 343 | folding: |
| 344 | title: Config |
| 345 | enabled: true |
| 346 | list: |
| 347 | - name: Basic check |
| 348 | description: Run a Nagios check command on a fixed interval. |
| 349 | config: | |
| 350 | jobs: |
| 351 | - name: ping_localhost |
| 352 | plugin: /usr/lib/nagios/plugins/check_ping |
| 353 | args: ["-H", "127.0.0.1", "-w", "100.0,20%", "-c", "200.0,40%"] |
| 354 | timeout: 5s |
| 355 | check_interval: 1m |
| 356 | retry_interval: 30s |
| 357 | max_check_attempts: 3 |
| 358 | - name: End-to-end custom script |
| 359 | description: | |
| 360 | Write a custom check script, then configure Netdata to run it. |
| 361 | |
| 362 | **1. Create the script** (e.g., `/usr/local/lib/netdata/checks/check_api.sh`): |
| 363 | |
| 364 | ```bash |
| 365 | #!/bin/sh |
| 366 | # Check HTTP endpoint health |
| 367 | URL="http://localhost:8080/health" |
| 368 | |
| 369 | response=$(curl -s -o /dev/null -w "%{http_code} %{time_total}" --max-time 5 "$URL" 2>/dev/null) |
| 370 | curl_exit=$? |
| 371 | |
| 372 | if [ "$curl_exit" -ne 0 ]; then |
| 373 | echo "UNKNOWN - Could not connect to $URL (curl exit code $curl_exit)" |
| 374 | exit 3 |
| 375 | fi |
| 376 | |
| 377 | http_code=$(echo "$response" | cut -d' ' -f1) |
| 378 | response_time=$(echo "$response" | cut -d' ' -f2) |
| 379 | |
| 380 | if [ "$http_code" -ge 500 ]; then |
| 381 | echo "CRITICAL - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;" |
| 382 | exit 2 |
| 383 | elif [ "$http_code" -ne 200 ]; then |
| 384 | echo "WARNING - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;" |
| 385 | exit 1 |
| 386 | fi |
| 387 | |
| 388 | echo "OK - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;" |
| 389 | exit 0 |
| 390 | ``` |
| 391 | |
| 392 | **2. Set ownership, permissions, and test it:** |
| 393 | |
| 394 | ```bash |
| 395 | sudo chown root:root /usr/local/lib/netdata/checks/check_api.sh |
| 396 | sudo chmod 755 /usr/local/lib/netdata/checks/check_api.sh |
| 397 | sudo -u netdata /usr/local/lib/netdata/checks/check_api.sh |
| 398 | echo "Exit code: $?" |
| 399 | ``` |
| 400 | |
| 401 | **3. Add the configuration below, then restart Netdata** (`sudo systemctl restart netdata`). After restarting, look for `nagios.job.execution_state` and related charts in the Netdata dashboard. |
| 402 | config: | |
| 403 | jobs: |
| 404 | - name: api_health |
| 405 | plugin: /usr/local/lib/netdata/checks/check_api.sh |
| 406 | timeout: 10s |
| 407 | check_interval: 1m |
| 408 | retry_interval: 30s |
| 409 | max_check_attempts: 3 |
| 410 | - name: Custom script (minimal) |
| 411 | description: Run your own Nagios-compatible shell script with minimal configuration. |
| 412 | config: | |
| 413 | jobs: |
| 414 | - name: custom_memory_check |
| 415 | plugin: /opt/netdata/check_memory.sh |
| 416 | timeout: 5s |
| 417 | check_interval: 1m |
| 418 | - name: Windows PowerShell check |
| 419 | description: | |
| 420 | On Windows, point `plugin` directly to a `.ps1` script. Netdata automatically invokes it through `powershell.exe` with `-NoProfile -ExecutionPolicy Bypass -File`. The `.bat` and `.cmd` scripts are also supported (invoked via `cmd.exe /c`). |
| 421 | |
| 422 | **1. Create the script** (e.g., `C:\Netdata\checks\check_service.ps1`): |
| 423 | |
| 424 | ```powershell |
| 425 | # Check if a Windows service is running |
| 426 | param([string]$ServiceName = "W3SVC") |
| 427 | |
| 428 | $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue |
| 429 | |
| 430 | if (-not $svc) { |
| 431 | Write-Host "UNKNOWN - Service $ServiceName not found | running=0;;;0;1" |
| 432 | exit 3 |
| 433 | } |
| 434 | |
| 435 | if ($svc.Status -eq 'Running') { |
| 436 | Write-Host "OK - $ServiceName is running | running=1;;;0;1" |
| 437 | exit 0 |
| 438 | } else { |
| 439 | Write-Host "CRITICAL - $ServiceName is $($svc.Status) | running=0;;;0;1" |
| 440 | exit 2 |
| 441 | } |
| 442 | ``` |
| 443 | |
| 444 | **2. Test from PowerShell** (run as the user the Netdata service runs under): |
| 445 | |
| 446 | ```powershell |
| 447 | powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Netdata\checks\check_service.ps1" |
| 448 | echo "Exit code: $LASTEXITCODE" |
| 449 | ``` |
| 450 | |
| 451 | **3. Add the configuration below, then restart Netdata** (`Restart-Service netdata`). |
| 452 | config: | |
| 453 | jobs: |
| 454 | - name: service_health_win |
| 455 | plugin: C:\Netdata\checks\check_service.ps1 |
| 456 | timeout: 10s |
| 457 | check_interval: 1m |
| 458 | - name: Remote check via NRPE |
| 459 | description: | |
| 460 | Run a check on a remote host using `check_nrpe`. This works exactly like a Nagios NRPE configuration — install `nagios-nrpe-plugin` and point to the remote NRPE agent. Increase `timeout` if the remote host is slow to respond. |
| 461 | config: | |
| 462 | jobs: |
| 463 | - name: remote_disk |
| 464 | plugin: /usr/lib/nagios/plugins/check_nrpe |
| 465 | args: ["-H", "192.168.1.10", "-c", "check_disk", "-a", "20% 10% /"] |
| 466 | timeout: 30s |
| 467 | check_interval: 5m |
| 468 | - name: Check with a job-local schedule |
| 469 | description: Run a check only during selected hours by defining time periods inside the job. |
| 470 | config: | |
| 471 | jobs: |
| 472 | - name: business_hours_http |
| 473 | plugin: /usr/lib/nagios/plugins/check_http |
| 474 | args: ["-H", "example.com"] |
| 475 | check_period: business_hours |
| 476 | time_periods: |
| 477 | - name: business_hours |
| 478 | alias: Business hours |
| 479 | rules: |
| 480 | - type: weekly |
| 481 | days: [monday, tuesday, wednesday, thursday, friday] |
| 482 | ranges: ["09:00-18:00"] |
| 483 | - name: Check with virtual node macros |
| 484 | description: Run a check against a virtual node and fill command arguments from Nagios-style macros. |
| 485 | config: | |
| 486 | jobs: |
| 487 | - name: check_ssh |
| 488 | plugin: /usr/lib/nagios/plugins/check_ssh |
| 489 | args: ["-H", "$HOSTADDRESS$", "-p", "$ARG1$"] |
| 490 | arg_values: ["22"] |
| 491 | vnode: remote-server |
| 492 | check_interval: 5m |
| 493 | troubleshooting: |
| 494 | problems: |
| 495 | list: |
| 496 | - name: The command cannot be executed |
| 497 | description: | |
| 498 | Confirm that the path in `plugin` exists, is executable, and can be accessed by the `netdata` user. If the check depends on external files or helpers, verify those paths and permissions too. |
| 499 | - name: No performance-data charts appear |
| 500 | description: | |
| 501 | Performance-data charts are created only when the check prints Nagios performance data after the `|` separator. If the command returns only a status line without performance data, Netdata will still show the job state but no extra charts. |
| 502 | - name: Some performance-data values are ignored |
| 503 | description: | |
| 504 | Check that each metric uses the Nagios performance-data format `label=value[UOM];warn;crit;min;max` and that multiple metrics are separated by spaces. If a label contains spaces, quote it. Netdata charts the main value for every perfdata metric, and for non-counter metrics it derives threshold state from `warn` and `crit`; it does not create separate charts for raw `min`, `max`, or raw threshold bounds. |
| 505 | - name: The job state does not match the output text |
| 506 | description: | |
| 507 | The visible text does not decide the state. Netdata uses the process exit code instead: `0` for OK, `1` for WARNING, `2` for CRITICAL, and `3` for UNKNOWN. If the check exceeds the configured `timeout`, Netdata reports `timeout` even if the script never had a chance to print its own final state. If the current time is outside `check_period`, Netdata reports `paused` until the check is allowed to run again. |
| 508 | - name: Only the first output line appears as the main status |
| 509 | description: | |
| 510 | This is expected. Netdata uses the first line as the summary shown for the job. Additional lines are kept as long output, and any `|` sections found on later lines are also parsed for performance data. |
| 511 | - name: Macros are not expanded as expected |
| 512 | description: | |
| 513 | Check that positional values are provided in `arg_values`, custom service variables are defined in `custom_vars`, and any virtual-node labels needed for host macros are present on the selected `vnode`. |
| 514 | - name: The script works in a shell but fails under Netdata |
| 515 | description: | |
| 516 | Nagios checks run with a limited execution environment rather than inheriting the full Netdata process environment. If the script depends on extra variables, set them explicitly in `environment` instead of relying on ambient shell state. |
| 517 | - name: Built-in alerts cover warning and critical states only |
| 518 | description: | |
| 519 | This collector installs stock Netdata health alerts for the `warning` and `critical` states on `nagios.job.execution_state` and `nagios.job.perfdata_threshold_state`. Both stock alert families suppress soft retry states by checking that `retry` is not active. If you also want alerts for `unknown`, `timeout`, `paused`, or more specific perfdata behavior, build your own rules on top of these contexts. The `nagios.job.perfdata_threshold_state` chart uses the `perfdata_value` label to identify which perfdata metric each threshold state belongs to. |
| 520 | - name: Configuration changes are not picked up |
| 521 | description: | |
| 522 | After editing `scripts.d/nagios.conf`, restart the Netdata Agent for changes to take effect: `sudo systemctl restart netdata`. |
| 523 | - name: Script stderr output is not visible |
| 524 | description: | |
| 525 | Netdata captures the check's standard output for status and performance data parsing. Standard error (stderr) is logged by the collector but not used for state or charts. If your script writes errors to stderr, check the Netdata error log for details. |
| 526 | - name: Job state is always timeout |
| 527 | description: | |
| 528 | The default timeout is 5 seconds, which is too short for many checks — especially remote checks (`check_nrpe`, `check_ssh`) or HTTP checks with SSL negotiation. Increase the `timeout` value in your job configuration (e.g. `timeout: 30s`). |
| 529 | - name: Check works as root but fails under Netdata |
| 530 | description: | |
| 531 | The Netdata Agent runs as the `netdata` user. If a check needs to read protected files, access SNMP, or connect to local sockets, it must be accessible to the `netdata` user. Test as that user first: `sudo -u netdata /path/to/check`. Common fixes include adding the `netdata` user to the required system group or using `sudo` with a specific NOPASSWD rule for the check command. |
| 532 | - name: Windows script support |
| 533 | description: | |
| 534 | On Windows, point `plugin` directly to a `.ps1`, `.bat`, or `.cmd` script. Netdata automatically invokes `.ps1` scripts through `powershell.exe` and `.bat`/`.cmd` scripts through `cmd.exe`. Ensure scripts are stored in directories with appropriate ACLs. |
| 535 | alerts: |
| 536 | - name: nagios_job_execution_state_warn |
| 537 | metric: nagios.job.execution_state |
| 538 | info: "Nagios job ${label:nagios_job} is in WARNING state" |
| 539 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf |
| 540 | - name: nagios_job_execution_state_crit |
| 541 | metric: nagios.job.execution_state |
| 542 | info: "Nagios job ${label:nagios_job} is in CRITICAL state" |
| 543 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf |
| 544 | - name: nagios_job_perfdata_threshold_state_warn |
| 545 | metric: nagios.job.perfdata_threshold_state |
| 546 | info: "Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in WARNING threshold state" |
| 547 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf |
| 548 | - name: nagios_job_perfdata_threshold_state_crit |
| 549 | metric: nagios.job.perfdata_threshold_state |
| 550 | info: "Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in CRITICAL threshold state" |
| 551 | link: https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf |
| 552 | metrics: |
| 553 | folding: |
| 554 | title: Metrics |
| 555 | enabled: false |
| 556 | description: | |
| 557 | Each configured job produces execution state and resource usage charts. When a check emits Nagios performance data, additional charts are created automatically for each metric. Non-counter perfdata with warning/critical thresholds also get threshold state charts for alerting. |
| 558 | availability: [] |
| 559 | scopes: |
| 560 | - name: job |
| 561 | description: These metrics refer to each configured check job. |
| 562 | labels: |
| 563 | - name: nagios_job |
| 564 | description: Job name as defined in the configuration. |
| 565 | - name: perfdata_value |
| 566 | description: Identifies which performance data metric a threshold state belongs to. Format is `<unit_class>_<label>`, where `<unit_class>` is derived from the UOM (`time`, `bytes`, `bits`, `percent`, or `generic`) and `<label>` is the sanitized metric label from the check output. For example, `repl_lag=5s` produces `time_repl_lag`. |
| 567 | metrics: |
| 568 | - name: nagios.job.execution_state |
| 569 | description: Current state of the check job. Values are ok, warning, critical, unknown, timeout (check exceeded configured timeout), or paused (outside check_period). The retry dimension indicates the check is retrying before reaching hard state. |
| 570 | unit: state |
| 571 | chart_type: line |
| 572 | dimensions: |
| 573 | - name: ok |
| 574 | - name: warning |
| 575 | - name: critical |
| 576 | - name: unknown |
| 577 | - name: timeout |
| 578 | - name: paused |
| 579 | - name: retry |
| 580 | - name: nagios.job.perfdata_threshold_state |
| 581 | description: Threshold state derived from performance data warning/critical ranges. Use the `perfdata_value` label to identify the specific metric. Values are no_threshold (check provides no ranges), ok, warning, or critical. The retry dimension indicates the check is retrying. |
| 582 | unit: state |
| 583 | chart_type: line |
| 584 | dimensions: |
| 585 | - name: no_threshold |
| 586 | - name: ok |
| 587 | - name: warning |
| 588 | - name: critical |
| 589 | - name: retry |
| 590 | - name: nagios.job.execution_duration |
| 591 | description: How long the check command took to run. |
| 592 | unit: seconds |
| 593 | chart_type: line |
| 594 | dimensions: |
| 595 | - name: duration |
| 596 | - name: nagios.job.execution_cpu_total |
| 597 | description: CPU time (user + system) consumed by the check command. Available on non-Windows platforms. |
| 598 | unit: seconds |
| 599 | chart_type: line |
| 600 | dimensions: |
| 601 | - name: total |
| 602 | - name: nagios.job.execution_max_rss |
| 603 | description: Peak memory (RSS) used by the check command. Available on non-Windows platforms. |
| 604 | unit: bytes |
| 605 | chart_type: line |
| 606 | dimensions: |
| 607 | - name: rss |