@cryptotaxi247 / netdata-1 / commits / de0013ce3

Regenerate integrations docs (#22150)

Co-authored-by: ilyam8 <22274335+ilyam8@users.noreply.github.com>

Netdata bot committed Apr 7, 2026 at 12:29 UTC de0013ce3c26f69c9c39606eee72d2402f7243e1

5 files changed +628 -529

src/collectors/COLLECTORS.md

+1 -1

@@ -575,7 +575,7 @@ Need a dedicated integration? [Submit a feature request](https://github.com/netd

575 | [IOPing](https://github.com/netdata/netdata/blob/master/src/collectors/ioping.plugin/integrations/ioping.md) | Monitor IOPing metrics for efficient disk I/O latency tracking. |

576 | [Monit](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/monit/integrations/monit.md) | This collector monitors status of Monit's service checks. |

577 | [MQTT Blackbox](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/mqtt_blackbox.md) | Track MQTT message transport performance using blackbox testing methods. |

578 -| [Nagios Plugins](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md) | This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts. |

578 +| [Nagios Plugins and Custom Scripts](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins_and_custom_scripts.md) | This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts in any language (Bash, PowerShell, Python, Go, etc.). |

579 | [Ping](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/ping/integrations/ping.md) | This module measures round-trip time and packet loss by sending ping messages to network hosts. |

580 | [Site 24x7](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/prometheus/integrations/site_24x7.md) | Monitor Site24x7 website and infrastructure monitoring metrics for efficient performance tracking and management. |

581 | [TCP/UDP Endpoints](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/portcheck/integrations/tcp-udp_endpoints.md) | Collector for monitoring service availability and response time. |

src/collectors/windows.plugin/integrations/active_directory_federation_service.md

@@ -129,6 +129,7 @@ Metrics:

129 | adfs.db_config_failures | connection | failures/s |

130 | adfs.db_config_query_time_seconds | query_time | seconds/s |

131 | adfs.device_authentications | authentications | authentications/s |

132 +| adfs.extranet_account_lockouts | lockouts | lockouts/s |

133 | adfs.external_authentications | success, failure | authentications/s |

134 | adfs.federated_authentications | authentications | authentications/s |

135 | adfs.federation_metadata_requests | requests | requests/s |

src/go/plugin/scripts.d/collector/nagios/README.md

+1 -1

@@ -1 +1 @@

1 -integrations/nagios_plugins.md

\ No newline at end of file

1 +integrations/nagios_plugins_and_custom_scripts.md

\ No newline at end of file

src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins.md

-527

@@ -1,527 +0,0 @@

1 -<!--startmeta

2 -custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/README.md"

3 -meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/metadata.yaml"

4 -sidebar_label: "Nagios Plugins"

5 -learn_status: "Published"

6 -learn_rel_path: "Collecting Metrics/Collectors/Synthetic Testing"

7 -keywords: ['nagios', 'plugins', 'checks', 'scripts', 'monitoring']

8 -message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"

9 -endmeta-->

10 -

11 -# Nagios Plugins

12 -

13 -

14 -<img src="https://netdata.cloud/img/nagios.png" width="150"/>

15 -

16 -

17 -Plugin: scripts.d.plugin

18 -Module: nagios

19 -

20 -<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

21 -

22 -## Overview

23 -

24 -This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts. It provides:

25 -

26 -- **Check state monitoring** — tracks whether each check returns OK, WARNING, CRITICAL, or UNKNOWN

27 -- **Execution metrics** — measures run duration, CPU time, and memory usage of each check

28 -- **Automatic performance data charts** — any [Nagios performance data](https://nagios-plugins.org/doc/guidelines.html) in the check output is parsed and charted automatically

29 -- **Threshold-based alerting** — when performance data includes warning/critical thresholds, Netdata derives threshold state and creates built-in alerts

30 -

31 -

32 -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.

33 -

34 -:::tip

35 -

36 -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.

37 -

38 -:::

39 -

40 -<details open><summary><strong>Nagios Plugin Output Format</strong></summary>

41 -

42 -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).

43 -

44 -#### Exit Codes

45 -

46 -The exit code is the **only** thing that determines the check state — the output text is for display purposes only.

47 -

48 -| Exit Code | State | Meaning |

49 -|:---------:|:------|:--------|

50 -| 0 | **OK** | Check passed |

51 -| 1 | **WARNING** | Above warning threshold or degraded |

52 -| 2 | **CRITICAL** | Above critical threshold or service down |

53 -| 3 | **UNKNOWN** | Invalid arguments or internal error |

54 -

55 -#### Standard Output

56 -

57 -The output follows this structure:

58 -

59 -```text

60 -STATUS TEXT | perfdata1=val;warn;crit;min;max perfdata2=val

61 -LONG OUTPUT LINE 1

62 -LONG OUTPUT LINE 2 | more_perfdata=val

63 -```

64 -

65 -| Part | Description |

66 -|:-----|:------------|

67 -| **Status text** | Text before the pipe on the first line. Shown as the job's status message. |

68 -| **Performance data** | Text after the pipe on any line. Parsed into charts automatically. |

69 -| **Long output** | Lines 2+ before the pipe. Additional detail text. |

70 -

71 -> **Note:** The pipe separator is optional. Without it, the entire first line is the status text and no performance data charts are created.

72 -

73 -#### Performance Data Format

74 -

75 -Each performance data metric uses this format:

76 -

77 -```text

78 -'label'=value[UOM];[warn];[crit];[min];[max]

79 -```

80 -

81 -| Field | Required | Description |

82 -|:------|:--------:|:------------|

83 -| `label` | Yes | Metric name. Quote with single quotes if it contains spaces. |

84 -| `value` | Yes | Numeric value. |

85 -| `UOM` | No | Unit of measurement (see table below). |

86 -| `warn` | No | Warning threshold range. |

87 -| `crit` | No | Critical threshold range. |

88 -| `min` | No | Minimum possible value. |

89 -| `max` | No | Maximum possible value. |

90 -

91 -Separate multiple metrics with spaces.

92 -

93 -**Supported Units of Measurement (UOM):**

94 -

95 -| UOM | Meaning | How Netdata charts it |

96 -|:----|:--------|:----------------------|

97 -| *(none)* | Unitless number | Charted as-is |

98 -| `s` | Seconds (also `ms`, `us`, `ns`) | Normalized to seconds |

99 -| `%` | Percentage | Charted as percentage |

100 -| `B` | Bytes (also `KB`, `MB`, `GB`, `TB`) | Charted in bytes |

101 -| `b` | Bits (also `Kb`, `Mb`, `Gb`, `Tb`) | Charted in bits |

102 -| `c` | Continuous counter | Charted as incremental rate |

103 -

104 -#### Threshold Ranges

105 -

106 -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):

107 -

108 -| Range | Alert when... |

109 -|:------|:--------------|

110 -| `10` | value < 0 or value > 10 |

111 -| `10:` | value < 10 |

112 -| `~:10` | value > 10 |

113 -| `10:20` | value < 10 or value > 20 |

114 -| `@10:20` | 10 ≤ value ≤ 20 |

115 -

116 -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.

117 -

118 -**Common threshold patterns:**

119 -

120 -| I want to alert when... | `warn` | `crit` |

121 -|:------------------------|:-------|:-------|

122 -| Value exceeds a limit (e.g., response time > 2s) | `~:2` | `~:5` |

123 -| Value drops below a floor (e.g., free space < 10%) | `10:` | `5:` |

124 -| Value is outside a band (e.g., temperature 20–80) | `20:80` | `10:90` |

125 -

126 -#### Example

127 -

128 -A minimal Nagios-compatible script:

129 -

130 -```bash

131 -#!/bin/sh

132 -echo "OK - 85% free memory | free_pct=85%;20:;10:;0;100 used_kb=2380912KB;;;0;16380000"

133 -exit 0

134 -```

135 -

136 -This produces:

137 -- **Check state**: OK (exit code 0)

138 -- **Status text**: `OK - 85% free memory`

139 -- **Charts**: `free_pct` (percentage with warning/critical thresholds) and `used_kb` (bytes)

140 -

141 -</details>

142 -

143 -:::info

144 -

145 -**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.

146 -

147 -:::

148 -

149 -

150 -This collector is supported on all platforms.

151 -

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

153 -

154 -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.

155 -

156 -

157 -### Default Behavior

158 -

159 -#### Auto-Detection

160 -

161 -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.

162 -

163 -

164 -#### Limits

165 -

166 -Each job runs one configured command. Additional charts are created only when the check emits Nagios performance data.

167 -

168 -

169 -#### Performance Impact

170 -

171 -Each job starts an external command. The impact depends mostly on how often the job runs and how expensive the check command itself is.

172 -

173 -

174 -## Setup

175 -

176 -

177 -### Prerequisites

178 -

179 -#### Install check commands

180 -

181 -Install the Nagios plugins or other Nagios-compatible scripts that you want Netdata to run.

182 -

183 -Most Linux distributions provide Nagios plugin packages:

184 -

185 -```bash

186 -# Debian/Ubuntu

187 -apt install nagios-plugins

188 -

189 -# RHEL/CentOS/Fedora

190 -dnf install nagios-plugins-all

191 -```

192 -

193 -Make sure the configured command path exists and is executable by the `netdata` user.

194 -

195 -

196 -#### Prepare custom check scripts

197 -

198 -If you are writing your own check scripts instead of using packaged Nagios plugins:

199 -

200 -- Place scripts anywhere accessible to the `netdata` user (e.g., `/usr/local/lib/netdata/checks/`)

201 -- Make scripts executable: `chmod +x /path/to/script.sh`

202 -- Test as the `netdata` user to verify permissions and environment: `sudo -u netdata /path/to/script.sh`

203 -- Verify the exit code: `echo $?` (must be 0, 1, 2, or 3)

204 -- Verify the output matches the Nagios plugin output format described in the Overview above

205 -

206 -

207 -

208 -### Configuration

209 -

210 -#### Options

211 -

212 -Add jobs under `jobs:`. Each job runs one Nagios-compatible check command.

213 -

214 -

215 -<details open><summary>Config options</summary>

216 -

217 -

218 -

220 -|:------|:-----|:------------|:--------|:---------:|

221 -| **Collection** | update_every | How often the collector's internal scheduler ticks, in seconds. Controls chart granularity. In most cases you only need to set `check_interval`. | 10 | no |

222 -| **Target** | plugin | Absolute path to the Nagios-compatible executable to run. This can be a packaged Nagios plugin or your own executable. If you need a script interpreter, point `plugin` to that interpreter and pass the script path in `args`. The command should return exit code `0`, `1`, `2`, or `3` and may print performance data after <code>|</code>. | | yes |

223 -| | args | Arguments passed to the command. | | no |

224 -| | arg_values | Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. The first value maps to `$ARG1$`, the second to `$ARG2$`, and so on. | | no |

225 -| | working_directory | Working directory used when running the command. | | no |

226 -| **Scheduling** | timeout | Maximum time allowed for one command run. If the check exceeds this limit, the job state becomes `timeout`. | 5s | no |

227 -| | check_interval | Interval between regular checks. | 5m | no |

228 -| | retry_interval | Interval between retries while a check remains in a non-OK soft state. | 1m | no |

229 -| | max_check_attempts | Number of attempts before a non-OK result becomes a hard state. | 3 | no |

230 -| | check_period | Name of the [time period](https://github.com/netdata/netdata/blob/master/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`. | 24x7 | no |

231 -| | time_periods | Custom named [time periods](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/pkg/timeperiod/README.md) defined inside the same job. Supports `weekly`, `nth_weekday`, and `date` rule types. | | no |

232 -| **Environment** | [environment](#option-environment-environment) | Extra environment variables added on top of the collector's limited execution baseline. The check does not inherit the full Netdata process environment. | | no |

233 -| | [custom_vars](#option-environment-custom-vars) | Custom service variables exposed to the check as Nagios-style macros. | | no |

236 -

237 -<a id="option-environment-environment"></a>

238 -##### environment

239 -

240 -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.

241 -

242 -```yaml

243 -jobs:

244 - - name: oracle_check

245 - plugin: /usr/local/bin/check_oracle.sh

246 - environment:

247 - ORACLE_HOME: /opt/oracle/product/19c

248 - LD_LIBRARY_PATH: /opt/oracle/product/19c/lib

249 -```

250 -

251 -

252 -<a id="option-environment-custom-vars"></a>

253 -##### custom_vars

254 -

255 -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>$`.

256 -

257 -```yaml

258 -jobs:

259 - - name: check_db

260 - plugin: /usr/lib/nagios/plugins/check_pgsql

261 - args: ["-H", "$_SERVICEDBHOST$", "-d", "$_SERVICEDBNAME$"]

262 - custom_vars:

263 - DBHOST: db.example.com

264 - DBNAME: production

265 -```

266 -

267 -

268 -

269 -</details>

270 -

271 -

272 -

273 -#### via File

274 -

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

276 -

277 -

278 -You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the

279 -Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

280 -

281 -```bash

282 -cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata

283 -sudo ./edit-config scripts.d/nagios.conf

284 -```

285 -

286 -##### Examples

287 -

288 -###### Basic check

289 -

290 -Run a Nagios check command on a fixed interval.

291 -

292 -<details open><summary>Config</summary>

293 -

294 -```yaml

295 -jobs:

296 - - name: ping_localhost

297 - plugin: /usr/lib/nagios/plugins/check_ping

298 - args: ["-H", "127.0.0.1", "-w", "100.0,20%", "-c", "200.0,40%"]

299 - timeout: 5s

300 - check_interval: 1m

301 - retry_interval: 30s

302 - max_check_attempts: 3

303 -

304 -```

305 -</details>

306 -

307 -###### End-to-end custom script

308 -

309 -Write a custom check script, then configure Netdata to run it.

310 -

311 -**1. Create the script** (e.g., `/usr/local/lib/netdata/checks/check_api.sh`):

312 -

313 -```bash

314 -#!/bin/sh

315 -# Check HTTP endpoint health

316 -URL="http://localhost:8080/health"

317 -

318 -response=$(curl -s -o /dev/null -w "%{http_code} %{time_total}" --max-time 5 "$URL" 2>/dev/null)

319 -curl_exit=$?

320 -

321 -if [ "$curl_exit" -ne 0 ]; then

322 - echo "UNKNOWN - Could not connect to $URL (curl exit code $curl_exit)"

323 - exit 3

324 -fi

325 -

326 -http_code=$(echo "$response" | cut -d' ' -f1)

327 -response_time=$(echo "$response" | cut -d' ' -f2)

328 -

329 -if [ "$http_code" -ge 500 ]; then

330 - echo "CRITICAL - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

331 - exit 2

332 -elif [ "$http_code" -ne 200 ]; then

333 - echo "WARNING - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

334 - exit 1

335 -fi

336 -

337 -echo "OK - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

338 -exit 0

339 -```

340 -

341 -**2. Make it executable and test it:**

342 -

343 -```bash

344 -chmod +x /usr/local/lib/netdata/checks/check_api.sh

345 -sudo -u netdata /usr/local/lib/netdata/checks/check_api.sh

346 -echo "Exit code: $?"

347 -```

348 -

349 -**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.

350 -

351 -

352 -<details open><summary>Config</summary>

353 -

354 -```yaml

355 -jobs:

356 - - name: api_health

357 - plugin: /usr/local/lib/netdata/checks/check_api.sh

358 - timeout: 10s

359 - check_interval: 1m

360 - retry_interval: 30s

361 - max_check_attempts: 3

362 -

363 -```

364 -</details>

365 -

366 -###### Custom script (minimal)

367 -

368 -Run your own Nagios-compatible shell script with minimal configuration.

369 -

370 -<details open><summary>Config</summary>

371 -

372 -```yaml

373 -jobs:

374 - - name: custom_memory_check

375 - plugin: /opt/netdata/check_memory.sh

376 - timeout: 5s

377 - check_interval: 1m

378 -

379 -```

380 -</details>

381 -

382 -###### Check with a job-local schedule

383 -

384 -Run a check only during selected hours by defining time periods inside the job.

385 -

386 -<details open><summary>Config</summary>

387 -

388 -```yaml

389 -jobs:

390 - - name: business_hours_http

391 - plugin: /usr/lib/nagios/plugins/check_http

392 - args: ["-H", "example.com"]

393 - check_period: business_hours

394 - time_periods:

395 - - name: business_hours

396 - alias: Business hours

397 - rules:

398 - - type: weekly

399 - days: [monday, tuesday, wednesday, thursday, friday]

400 - ranges: ["09:00-18:00"]

401 -

402 -```

403 -</details>

404 -

405 -###### Check with virtual node macros

406 -

407 -Run a check against a virtual node and fill command arguments from Nagios-style macros.

408 -

409 -<details open><summary>Config</summary>

410 -

411 -```yaml

412 -jobs:

413 - - name: check_ssh

414 - plugin: /usr/lib/nagios/plugins/check_ssh

415 - args: ["-H", "$HOSTADDRESS$", "-p", "$ARG1$"]

416 - arg_values: ["22"]

417 - vnode: remote-server

418 - check_interval: 5m

419 -

420 -```

421 -</details>

422 -

423 -

424 -

425 -## Alerts

426 -

427 -

428 -The following alerts are available:

429 -

430 -| Alert name | On metric | Description |

431 -|:------------|:----------|:------------|

432 -| [ nagios_job_execution_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in WARNING state |

433 -| [ nagios_job_execution_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in CRITICAL state |

434 -| [ nagios_job_perfdata_threshold_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in WARNING threshold state |

435 -| [ nagios_job_perfdata_threshold_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in CRITICAL threshold state |

436 -

437 -

438 -## Metrics

439 -

440 -Metrics grouped by *scope*.

441 -

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

443 -

444 -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.

445 -

446 -

447 -### Per job

448 -

449 -These metrics refer to each configured check job.

450 -

451 -Labels:

452 -

453 -| Label | Description |

454 -|:-----------|:----------------|

455 -| nagios_job | Job name as defined in the configuration. |

456 -| perfdata_value | 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`. |

457 -

458 -Metrics:

459 -

460 -| Metric | Dimensions | Unit |

461 -|:------|:----------|:----|

462 -| nagios.job.execution_state | ok, warning, critical, unknown, timeout, paused, retry | state |

463 -| nagios.job.perfdata_threshold_state | no_threshold, ok, warning, critical, retry | state |

464 -| nagios.job.execution_duration | duration | seconds |

465 -| nagios.job.execution_cpu_total | total | seconds |

466 -| nagios.job.execution_max_rss | rss | bytes |

467 -

468 -

469 -

470 -## Troubleshooting

471 -

472 -### The command cannot be executed

473 -

474 -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.

475 -

476 -

477 -### No performance-data charts appear

478 -

479 -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.

480 -

481 -

482 -### Some performance-data values are ignored

483 -

484 -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.

485 -

486 -

487 -### The job state does not match the output text

488 -

489 -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.

490 -

491 -

492 -### Only the first output line appears as the main status

493 -

494 -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.

495 -

496 -

497 -### Macros are not expanded as expected

498 -

499 -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`.

500 -

501 -

502 -### The script works in a shell but fails under Netdata

503 -

504 -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.

505 -

506 -

507 -### Built-in alerts cover warning and critical states only

508 -

509 -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.

510 -

511 -

512 -### Configuration changes are not picked up

513 -

514 -After editing `scripts.d/nagios.conf`, restart the Netdata Agent for changes to take effect: `sudo systemctl restart netdata`.

515 -

516 -

517 -### Script stderr output is not visible

518 -

519 -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.

520 -

521 -

522 -### Windows checks need an executable entry point

523 -

524 -The collector runs the command named in `plugin` directly. On Windows, point `plugin` to an executable or to an interpreter such as `powershell.exe` and pass the script path in `args`.

525 -

526 -

527 -

src/go/plugin/scripts.d/collector/nagios/integrations/nagios_plugins_and_custom_scripts.md new

+625

@@ -0,0 +1,625 @@

1 +<!--startmeta

2 +custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/README.md"

3 +meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/scripts.d/collector/nagios/metadata.yaml"

4 +sidebar_label: "Nagios Plugins and Custom Scripts"

5 +learn_status: "Published"

6 +learn_rel_path: "Collecting Metrics/Collectors/Synthetic Testing"

7 +keywords: ['nagios', 'plugins', 'checks', 'scripts', 'monitoring']

8 +message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"

9 +endmeta-->

10 +

11 +# Nagios Plugins and Custom Scripts

12 +

13 +

14 +<img src="https://netdata.cloud/img/nagios.png" width="150"/>

15 +

16 +

17 +Plugin: scripts.d.plugin

18 +Module: nagios

19 +

20 +<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

21 +

22 +## Overview

23 +

24 +This collector runs [Nagios-compatible plugins](https://www.nagios-plugins.org/) and custom scripts in any language (Bash, PowerShell, Python, Go, etc.). It provides:

25 +

26 +- **Check state monitoring** — tracks whether each check returns OK, WARNING, CRITICAL, or UNKNOWN

27 +- **Execution metrics** — measures run duration, CPU time, and memory usage of each check

28 +- **Automatic performance data charts** — any [Nagios performance data](https://nagios-plugins.org/doc/guidelines.html) in the check output is parsed and charted automatically

29 +- **Threshold-based alerting** — when performance data includes warning/critical thresholds, Netdata derives threshold state and creates built-in alerts

30 +

31 +

32 +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.

33 +

34 +:::tip

35 +

36 +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.

37 +

38 +:::

39 +

40 +<details open><summary><strong>Nagios Plugin Output Format</strong></summary>

41 +

42 +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).

43 +

44 +#### Exit Codes

45 +

46 +The exit code is the **only** thing that determines the check state — the output text is for display purposes only.

47 +

48 +| Exit Code | State | Meaning |

49 +|:---------:|:------|:--------|

50 +| 0 | **OK** | Check passed |

51 +| 1 | **WARNING** | Above warning threshold or degraded |

52 +| 2 | **CRITICAL** | Above critical threshold or service down |

53 +| 3 | **UNKNOWN** | Invalid arguments or internal error |

54 +

55 +#### Standard Output

56 +

57 +The output follows this structure:

58 +

59 +```text

60 +STATUS TEXT | perfdata1=val;warn;crit;min;max perfdata2=val

61 +LONG OUTPUT LINE 1

62 +LONG OUTPUT LINE 2 | more_perfdata=val

63 +```

64 +

65 +| Part | Description |

66 +|:-----|:------------|

67 +| **Status text** | Text before the pipe on the first line. Shown as the job's status message. |

68 +| **Performance data** | Text after the pipe on any line. Parsed into charts automatically. |

69 +| **Long output** | Lines 2+ before the pipe. Additional detail text. |

70 +

71 +> **Note:** The pipe separator is optional. Without it, the entire first line is the status text and no performance data charts are created.

72 +

73 +#### Performance Data Format

74 +

75 +Each performance data metric uses this format:

76 +

77 +```text

78 +'label'=value[UOM];[warn];[crit];[min];[max]

79 +```

80 +

81 +| Field | Required | Description |

82 +|:------|:--------:|:------------|

83 +| `label` | Yes | Metric name. Quote with single quotes if it contains spaces. |

84 +| `value` | Yes | Numeric value. |

85 +| `UOM` | No | Unit of measurement (see table below). |

86 +| `warn` | No | Warning threshold range. |

87 +| `crit` | No | Critical threshold range. |

88 +| `min` | No | Minimum possible value. |

89 +| `max` | No | Maximum possible value. |

90 +

91 +Separate multiple metrics with spaces.

92 +

93 +**Supported Units of Measurement (UOM):**

94 +

95 +| UOM | Meaning | How Netdata charts it |

96 +|:----|:--------|:----------------------|

97 +| *(none)* | Unitless number | Charted as-is |

98 +| `s` | Seconds (also `ms`, `us`, `ns`) | Normalized to seconds |

99 +| `%` | Percentage | Charted as percentage |

100 +| `B` | Bytes (also `KB`, `MB`, `GB`, `TB`) | Charted in bytes |

101 +| `b` | Bits (also `Kb`, `Mb`, `Gb`, `Tb`) | Charted in bits |

102 +| `c` | Continuous counter | Charted as incremental rate |

103 +

104 +#### Threshold Ranges

105 +

106 +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):

107 +

108 +| Range | Alert when... |

109 +|:------|:--------------|

110 +| `10` | value < 0 or value > 10 |

111 +| `10:` | value < 10 |

112 +| `~:10` | value > 10 |

113 +| `10:20` | value < 10 or value > 20 |

114 +| `@10:20` | 10 ≤ value ≤ 20 |

115 +

116 +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.

117 +

118 +**Common threshold patterns:**

119 +

120 +| I want to alert when... | `warn` | `crit` |

121 +|:------------------------|:-------|:-------|

122 +| Value exceeds a limit (e.g., response time > 2s) | `~:2` | `~:5` |

123 +| Value drops below a floor (e.g., free space < 10%) | `10:` | `5:` |

124 +| Value is outside a band (e.g., temperature 20–80) | `20:80` | `10:90` |

125 +

126 +#### Example

127 +

128 +A minimal Nagios-compatible script:

129 +

130 +```bash

131 +#!/bin/sh

132 +echo "OK - 85% free memory | free_pct=85%;20:;10:;0;100 used_kb=2380912KB;;;0;16380000"

133 +exit 0

134 +```

135 +

136 +This produces:

137 +- **Check state**: OK (exit code 0)

138 +- **Status text**: `OK - 85% free memory`

139 +- **Charts**: `free_pct` (percentage with warning/critical thresholds) and `used_kb` (bytes)

140 +

141 +</details>

142 +

143 +:::info

144 +

145 +**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.

146 +

147 +:::

148 +

149 +

150 +This collector is supported on all platforms.

151 +

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

153 +

154 +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.

155 +

156 +

157 +### Default Behavior

158 +

159 +#### Auto-Detection

160 +

161 +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.

162 +

163 +

164 +#### Limits

165 +

166 +Each job runs one configured command. Additional charts are created only when the check emits Nagios performance data.

167 +

168 +

169 +#### Performance Impact

170 +

171 +Each job starts an external command. The impact depends mostly on how often the job runs and how expensive the check command itself is.

172 +

173 +

174 +## Setup

175 +

176 +

177 +### Prerequisites

178 +

179 +#### Install check commands

180 +

181 +Install the Nagios plugins or other Nagios-compatible scripts that you want Netdata to run.

182 +

183 +Most Linux distributions provide Nagios plugin packages:

184 +

185 +```bash

186 +# Debian/Ubuntu

187 +apt install nagios-plugins

188 +

189 +# RHEL/CentOS/Fedora

190 +dnf install nagios-plugins-all

191 +```

192 +

193 +Make sure the configured command path exists and is executable by the `netdata` user.

194 +

195 +

196 +#### Prepare custom check scripts

197 +

198 +If you are writing your own check scripts instead of using packaged Nagios plugins:

199 +

200 +- Place scripts anywhere accessible to the `netdata` user (e.g., `/usr/local/lib/netdata/checks/`)

201 +- Make scripts executable: `chmod +x /path/to/script.sh`

202 +- Test as the `netdata` user to verify permissions and environment: `sudo -u netdata /path/to/script.sh`

203 +- Verify the exit code: `echo $?` (must be 0, 1, 2, or 3)

204 +- Verify the output matches the Nagios plugin output format described in the Overview above

205 +

206 +

207 +

208 +### Configuration

209 +

210 +#### Options

211 +

212 +Add jobs under `jobs:`. Each job runs one Nagios-compatible check command.

213 +

214 +

215 +<details open><summary>Config options</summary>

216 +

217 +

218 +

220 +|:------|:-----|:------------|:--------|:---------:|

221 +| **Collection** | update_every | 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`. | 10 | no |

222 +| **Target** | check_name | 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). Set this when `plugin` points to an interpreter (e.g. `powershell.exe`, `/bin/bash`) — otherwise all jobs using the same interpreter share the same chart section. 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: - `nagios.perfdata.check_memory.job.execution_state` — check state (ok, warning, critical, unknown, timeout, paused, retry) - `nagios.perfdata.check_memory.bytes_caches` — perfdata value chart - `nagios.perfdata.check_memory.bytes_caches_threshold_state` — threshold state (if warn/crit thresholds are present) | | no |

223 +| | plugin | Absolute path to the Nagios-compatible command entry point to run. This can be a packaged Nagios plugin, your own executable, or an interpreter executable. When `plugin` points to an interpreter, pass the script path in `args` and set `check_name` to the actual check identity — otherwise all jobs using the same interpreter share the same chart section. The command should return exit code `0`, `1`, `2`, or `3` and may print performance data after <code>|</code>. | | yes |

224 +| | args | Arguments passed to the command. | | no |

225 +| | arg_values | Values exposed to `$ARG1$` through `$ARG32$` for macro expansion. The first value maps to `$ARG1$`, the second to `$ARG2$`, and so on. | | no |

226 +| | working_directory | Working directory used when running the command. | | no |

227 +| **Scheduling** | timeout | Maximum time allowed for one command run. If the check exceeds this limit, the job state becomes `timeout`. | 5s | no |

228 +| | check_interval | Interval between regular checks. | 5m | no |

229 +| | retry_interval | Interval between retries while a check remains in a non-OK soft state. | 1m | no |

230 +| | max_check_attempts | Number of attempts before a non-OK result becomes a hard state. | 3 | no |

231 +| | check_period | Name of the [time period](https://github.com/netdata/netdata/blob/master/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`. | 24x7 | no |

232 +| | time_periods | Custom named [time periods](https://github.com/netdata/netdata/blob/master/src/go/plugin/scripts.d/pkg/timeperiod/README.md) defined inside the same job. Supports `weekly`, `nth_weekday`, and `date` rule types. | | no |

233 +| **Environment** | [environment](#option-environment-environment) | Extra environment variables added on top of the collector's limited execution baseline. The check does not inherit the full Netdata process environment. | | no |

234 +| | [custom_vars](#option-environment-custom-vars) | Custom service variables exposed to the check as Nagios-style macros. | | no |

237 +

238 +<a id="option-environment-environment"></a>

239 +##### environment

240 +

241 +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.

242 +

243 +```yaml

244 +jobs:

245 + - name: oracle_check

246 + plugin: /usr/local/bin/check_oracle.sh

247 + environment:

248 + ORACLE_HOME: /opt/oracle/product/19c

249 + LD_LIBRARY_PATH: /opt/oracle/product/19c/lib

250 +```

251 +

252 +

253 +<a id="option-environment-custom-vars"></a>

254 +##### custom_vars

255 +

256 +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>$`.

257 +

258 +```yaml

259 +jobs:

260 + - name: check_db

261 + plugin: /usr/lib/nagios/plugins/check_pgsql

262 + args: ["-H", "$_SERVICEDBHOST$", "-d", "$_SERVICEDBNAME$"]

263 + custom_vars:

264 + DBHOST: db.example.com

265 + DBNAME: production

266 +```

267 +

268 +

269 +

270 +</details>

271 +

272 +

273 +

274 +#### via File

275 +

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

277 +

278 +

279 +You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the

280 +Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

281 +

282 +```bash

283 +cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata

284 +sudo ./edit-config scripts.d/nagios.conf

285 +```

286 +

287 +##### Examples

288 +

289 +###### Basic check

290 +

291 +Run a Nagios check command on a fixed interval.

292 +

293 +<details open><summary>Config</summary>

294 +

295 +```yaml

296 +jobs:

297 + - name: ping_localhost

298 + plugin: /usr/lib/nagios/plugins/check_ping

299 + args: ["-H", "127.0.0.1", "-w", "100.0,20%", "-c", "200.0,40%"]

300 + timeout: 5s

301 + check_interval: 1m

302 + retry_interval: 30s

303 + max_check_attempts: 3

304 +

305 +```

306 +</details>

307 +

308 +###### End-to-end custom script

309 +

310 +Write a custom check script, then configure Netdata to run it.

311 +

312 +**1. Create the script** (e.g., `/usr/local/lib/netdata/checks/check_api.sh`):

313 +

314 +```bash

315 +#!/bin/sh

316 +# Check HTTP endpoint health

317 +URL="http://localhost:8080/health"

318 +

319 +response=$(curl -s -o /dev/null -w "%{http_code} %{time_total}" --max-time 5 "$URL" 2>/dev/null)

320 +curl_exit=$?

321 +

322 +if [ "$curl_exit" -ne 0 ]; then

323 + echo "UNKNOWN - Could not connect to $URL (curl exit code $curl_exit)"

324 + exit 3

325 +fi

326 +

327 +http_code=$(echo "$response" | cut -d' ' -f1)

328 +response_time=$(echo "$response" | cut -d' ' -f2)

329 +

330 +if [ "$http_code" -ge 500 ]; then

331 + echo "CRITICAL - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

332 + exit 2

333 +elif [ "$http_code" -ne 200 ]; then

334 + echo "WARNING - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

335 + exit 1

336 +fi

337 +

338 +echo "OK - $URL returned HTTP $http_code | response_time=${response_time}s;2;5;0;"

339 +exit 0

340 +```

341 +

342 +**2. Make it executable and test it:**

343 +

344 +```bash

345 +chmod +x /usr/local/lib/netdata/checks/check_api.sh

346 +sudo -u netdata /usr/local/lib/netdata/checks/check_api.sh

347 +echo "Exit code: $?"

348 +```

349 +

350 +**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.

351 +

352 +

353 +<details open><summary>Config</summary>

354 +

355 +```yaml

356 +jobs:

357 + - name: api_health

358 + plugin: /usr/local/lib/netdata/checks/check_api.sh

359 + timeout: 10s

360 + check_interval: 1m

361 + retry_interval: 30s

362 + max_check_attempts: 3

363 +

364 +```

365 +</details>

366 +

367 +###### Custom script (minimal)

368 +

369 +Run your own Nagios-compatible shell script with minimal configuration.

370 +

371 +<details open><summary>Config</summary>

372 +

373 +```yaml

374 +jobs:

375 + - name: custom_memory_check

376 + plugin: /opt/netdata/check_memory.sh

377 + timeout: 5s

378 + check_interval: 1m

379 +

380 +```

381 +</details>

382 +

383 +###### End-to-end custom script (Windows PowerShell)

384 +

385 +Write a PowerShell check script, then configure Netdata to run it. Because `plugin` points to the PowerShell interpreter, `check_name` is required to keep charts grouped under the script identity instead of `powershell`.

386 +

387 +**1. Create the script** (e.g., `C:\Netdata\checks\check_service.ps1`):

388 +

389 +```powershell

390 +# Check if a Windows service is running

391 +param([string]$ServiceName = "W3SVC")

392 +

393 +$svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue

394 +

395 +if (-not $svc) {

396 + Write-Host "UNKNOWN - Service $ServiceName not found | running=0;;;0;1"

397 + exit 3

398 +}

399 +

400 +if ($svc.Status -eq 'Running') {

401 + Write-Host "OK - $ServiceName is running | running=1;;;0;1"

402 + exit 0

403 +} else {

404 + Write-Host "CRITICAL - $ServiceName is $($svc.Status) | running=0;;;0;1"

405 + exit 2

406 +}

407 +```

408 +

409 +**2. Test from PowerShell** (run as the user the Netdata service runs under):

410 +

411 +```powershell

412 +powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Netdata\checks\check_service.ps1"

413 +echo "Exit code: $LASTEXITCODE"

414 +```

415 +

416 +**3. Add the configuration below, then restart Netdata** (`Restart-Service netdata`).

417 +

418 +

419 +<details open><summary>Config</summary>

420 +

421 +```yaml

422 +jobs:

423 + - name: service_health_win

424 + check_name: check_service

425 + plugin: "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"

426 + args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "C:\\Netdata\\checks\\check_service.ps1"]

427 + timeout: 10s

428 + check_interval: 1m

429 +

430 +```

431 +</details>

432 +

433 +###### Interpreter-launched script (Bash)

434 +

435 +Run a Bash script through an interpreter. Without `check_name`, charts would be grouped under `bash`.

436 +

437 +

438 +<details open><summary>Config</summary>

439 +

440 +```yaml

441 +jobs:

442 + - name: db_health

443 + check_name: check_postgres

444 + plugin: /bin/bash

445 + args: ["/opt/netdata/checks/check_postgres.sh", "--host", "db.example.com"]

446 + timeout: 10s

447 + check_interval: 5m

448 +

449 +```

450 +</details>

451 +

452 +###### Remote check via NRPE

453 +

454 +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.

455 +

456 +

457 +<details open><summary>Config</summary>

458 +

459 +```yaml

460 +jobs:

461 + - name: remote_disk

462 + plugin: /usr/lib/nagios/plugins/check_nrpe

463 + args: ["-H", "192.168.1.10", "-c", "check_disk", "-a", "20% 10% /"]

464 + timeout: 30s

465 + check_interval: 5m

466 +

467 +```

468 +</details>

469 +

470 +###### Check with a job-local schedule

471 +

472 +Run a check only during selected hours by defining time periods inside the job.

473 +

474 +<details open><summary>Config</summary>

475 +

476 +```yaml

477 +jobs:

478 + - name: business_hours_http

479 + plugin: /usr/lib/nagios/plugins/check_http

480 + args: ["-H", "example.com"]

481 + check_period: business_hours

482 + time_periods:

483 + - name: business_hours

484 + alias: Business hours

485 + rules:

486 + - type: weekly

487 + days: [monday, tuesday, wednesday, thursday, friday]

488 + ranges: ["09:00-18:00"]

489 +

490 +```

491 +</details>

492 +

493 +###### Check with virtual node macros

494 +

495 +Run a check against a virtual node and fill command arguments from Nagios-style macros.

496 +

497 +<details open><summary>Config</summary>

498 +

499 +```yaml

500 +jobs:

501 + - name: check_ssh

502 + plugin: /usr/lib/nagios/plugins/check_ssh

503 + args: ["-H", "$HOSTADDRESS$", "-p", "$ARG1$"]

504 + arg_values: ["22"]

505 + vnode: remote-server

506 + check_interval: 5m

507 +

508 +```

509 +</details>

510 +

511 +

512 +

513 +## Alerts

514 +

515 +

516 +The following alerts are available:

517 +

518 +| Alert name | On metric | Description |

519 +|:------------|:----------|:------------|

520 +| [ nagios_job_execution_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in WARNING state |

521 +| [ nagios_job_execution_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.execution_state | Nagios job ${label:nagios_job} is in CRITICAL state |

522 +| [ nagios_job_perfdata_threshold_state_warn ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in WARNING threshold state |

523 +| [ nagios_job_perfdata_threshold_state_crit ](https://github.com/netdata/netdata/blob/master/src/health/health.d/nagios.conf) | nagios.job.perfdata_threshold_state | Nagios job ${label:nagios_job} perfdata ${label:perfdata_value} is in CRITICAL threshold state |

524 +

525 +

526 +## Metrics

527 +

528 +Metrics grouped by *scope*.

529 +

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

531 +

532 +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.

533 +

534 +

535 +### Per job

536 +

537 +These metrics refer to each configured check job.

538 +

539 +Labels:

540 +

541 +| Label | Description |

542 +|:-----------|:----------------|

543 +| nagios_job | Job name as defined in the configuration. |

544 +| perfdata_value | 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`. |

545 +

546 +Metrics:

547 +

548 +| Metric | Dimensions | Unit |

549 +|:------|:----------|:----|

550 +| nagios.job.execution_state | ok, warning, critical, unknown, timeout, paused, retry | state |

551 +| nagios.job.perfdata_threshold_state | no_threshold, ok, warning, critical, retry | state |

552 +| nagios.job.execution_duration | duration | seconds |

553 +| nagios.job.execution_cpu_total | total | seconds |

554 +| nagios.job.execution_max_rss | rss | bytes |

555 +

556 +

557 +

558 +## Troubleshooting

559 +

560 +### The command cannot be executed

561 +

562 +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.

563 +

564 +

565 +### No performance-data charts appear

566 +

567 +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.

568 +

569 +

570 +### Some performance-data values are ignored

571 +

572 +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.

573 +

574 +

575 +### The job state does not match the output text

576 +

577 +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.

578 +

579 +

580 +### Only the first output line appears as the main status

581 +

582 +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.

583 +

584 +

585 +### Macros are not expanded as expected

586 +

587 +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`.

588 +

589 +

590 +### The script works in a shell but fails under Netdata

591 +

592 +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.

593 +

594 +

595 +### Built-in alerts cover warning and critical states only

596 +

597 +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.

598 +

599 +

600 +### Configuration changes are not picked up

601 +

602 +After editing `scripts.d/nagios.conf`, restart the Netdata Agent for changes to take effect: `sudo systemctl restart netdata`.

603 +

604 +

605 +### Script stderr output is not visible

606 +

607 +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.

608 +

609 +

610 +### Job state is always timeout

611 +

612 +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`).

613 +

614 +

615 +### Check works as root but fails under Netdata

616 +

617 +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.

618 +

619 +

620 +### Windows checks need an executable entry point

621 +

622 +The collector runs the command named in `plugin` directly. On Windows, point `plugin` to the absolute path of a compiled executable or an interpreter (e.g. `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`). When using an interpreter, pass the script path in `args` and always set `check_name` — without it, all jobs using the same interpreter share the same chart section (e.g. `Perfdata/powershell`).

623 +

624 +

625 +