Nagios

---
name: nagios
description: "Expert agent for Nagios Core and Nagios XI covering check-based monitoring architecture, plugin system, NRPE, configuration patterns, alerting, and migration guidance to modern platforms (Zabbix, Prometheus). Legacy-focused agent providing operational expertise and clear migration paths. WHEN: \"Nagios\", \"nagios\", \"NRPE\", \"check_http\", \"check_disk\", \"check_load\", \"check_nrpe\", \"check_ping\", \"check_procs\", \"Nagios Core\", \"Nagios XI\", \"NSCA\", \"nagios.cfg\", \"Nagios plugin\"."
license: MIT
---

# Nagios Technology Expert

This skill covers Nagios Core and Nagios XI: the check-based monitoring architecture, plugin system, NRPE, configuration patterns, and alerting. It also covers migration guidance for organizations moving from Nagios to modern platforms.

Nagios Core is open-source (GPL v2). Nagios XI is commercial, licensed per monitored node. For new deployments, recommend evaluating Zabbix or Prometheus -- Nagios remains relevant for legacy maintenance and migration.

## How to Approach Tasks

When you receive a request:

1. **Classify** the request by domain:
   - **Architecture / configuration / plugins** -- Load `references/architecture.md`
   - **Migration to modern platforms** -- Load `references/migration.md`

2. **Determine Core vs XI** -- Core is config-file-driven and minimal. XI adds a web UI, wizards, and dashboards. Configuration advice differs significantly.

3. **Check if migration is appropriate** -- For new monitoring requirements, recommend evaluating Zabbix or Prometheus rather than extending a Nagios deployment. Provide honest migration guidance.

4. **Think plugins** -- Nagios power comes from its plugin ecosystem. Any executable returning 0/1/2/3 with a one-line output is a valid plugin.

## Core Expertise

You have deep knowledge across these Nagios areas:

- **Architecture:** Nagios Core vs XI, active checks, passive checks, NRPE, NSCA, external command file, scheduling engine
- **Configuration:** Object definitions (hosts, services, contacts, commands, timeperiods), templates and inheritance, hostgroups/servicegroups, `nagios.cfg`, `resource.cfg`, check intervals
- **Plugins:** Standard plugin set (check_http, check_disk, check_load, check_procs, check_snmp, check_tcp, check_nrpe), return codes (0/1/2/3), performance data format, writing custom plugins
- **Alerting:** Notifications, escalations, dependencies, flap detection, acknowledgements, scheduled downtime
- **Migration:** Nagios-to-Zabbix mapping, Nagios-to-Prometheus mapping, plugin reuse strategies

## Architecture Overview

### Execution Model

```
Nagios Scheduler -> Plugin binary -> Exit code (0/1/2/3) -> State determination -> Notification
                                                                                       |
                   NRPE daemon (remote) <-- check_nrpe (local)                    Contacts/Groups
```

**Active checks:** Nagios initiates on schedule. Runs plugin binary directly or via NRPE for remote hosts.

**Passive checks:** External processes submit results to the External Command File (`/var/nagios/rw/nagios.cmd`). Used for event-driven systems and firewalled hosts.

**NRPE:** Daemon on remote hosts (port 5667). Nagios sends command name via `check_nrpe`; NRPE executes the plugin locally and returns the result.

### Core vs XI

| Aspect | Nagios Core | Nagios XI |
|--------|------------|-----------|
| Interface | Minimal CGIs (read-only status) | Full PHP/MySQL web UI |
| Configuration | Manual `.cfg` file editing | GUI wizards write configs |
| Dashboards | None built-in | Dashboard builder |
| Autodiscovery | None | Network scanning wizards |
| Reporting | None | SLA reports, capacity planning |
| License | GPL v2 (free) | Per-node commercial |

## Plugin System

### Return Codes

| Code | State | Meaning |
|------|-------|---------|
| 0 | OK | Service functioning normally |
| 1 | WARNING | Degraded but not failed |
| 2 | CRITICAL | Failed or threshold exceeded |
| 3 | UNKNOWN | Could not determine state |

### Key Standard Plugins

| Plugin | Purpose |
|--------|---------|
| `check_ping` | ICMP reachability and RTT |
| `check_http` | HTTP/HTTPS response, content, SSL cert expiry |
| `check_disk` | Filesystem usage (space, inodes) |
| `check_load` | 1/5/15-minute load averages |
| `check_procs` | Process count, state, CPU, memory |
| `check_snmp` | SNMP OID polling |
| `check_tcp` | TCP port open/response time |
| `check_nrpe` | Proxy check to remote NRPE daemon |

### Performance Data

Plugins append perfdata after a pipe character:
```
OK - Load: 0.42|load1=0.42;5;10;0; load5=0.38;4;8;0;
```

Format: `label=value[UOM];[warn];[crit];[min];[max]`

### Writing Custom Plugins

Any executable (bash, Python, Go). Requirements:
1. Print single line of output (optionally with `|perfdata`)
2. Exit with 0/1/2/3

```bash
#!/bin/bash
COUNT=$(pgrep -c "myapp" 2>/dev/null)
if [ "$COUNT" -ge 1 ]; then
    echo "OK - myapp running ($COUNT processes)|procs=$COUNT;1;1;0;"
    exit 0
else
    echo "CRITICAL - myapp not running|procs=0;1;1;0;"
    exit 2
fi
```

## Configuration Quick Reference

### Templates and Inheritance

```cfg
define host {
    name            linux-server
    use             generic-host
    check_command   check-host-alive
    register        0
}

define host {
    use         linux-server
    host_name   web01
    address     192.168.1.20
}
```

### Service Definition

```cfg
define service {
    use                 generic-service
    hostgroup_name      web-servers
    service_description HTTP
    check_command       check_http
}
```

### NRPE Configuration

```ini
# /etc/nagios/nrpe.cfg on remote host
allowed_hosts=192.168.1.10
command[check_disk]=/usr/lib/nagios/plugins/check_disk -w 20% -c 10% -p /
command[check_load]=/usr/lib/nagios/plugins/check_load -w 5,4,3 -c 10,8,6
```

## Common Pitfalls

**1. Configuration syntax errors block all monitoring**
A single syntax error in any `.cfg` file prevents Nagios from starting. Always run `nagios -v /etc/nagios/nagios.cfg` before reloading.

**2. NRPE allowed_hosts not configured**
NRPE silently rejects connections from unlisted IPs. Every Nagios server and proxy IP must be in `allowed_hosts`.

**3. No template inheritance strategy**
Without templates, every host and service duplicates directives. Use `register 0` templates with `use` directive for DRY configuration.

**4. Missing host dependencies for network topology**
Without dependencies, a router failure generates alerts for every host behind it. Define host dependencies to suppress child alerts.

**5. Flap detection disabled**
Without `enable_flap_detection=1`, unstable services generate continuous notification storms.

**6. Performance data not processed**
Nagios generates perfdata but does not graph it. Requires PNP4Nagios, Graphite, or InfluxDB integration for visualization.

## Migration Guidance

Nagios expertise translates directly to Zabbix (similar mental model) and partially to Prometheus (paradigm shift from check-based to metric-based).

**Quick migration mapping:**

| Nagios Concept | Zabbix Equivalent | Prometheus Equivalent |
|----------------|-------------------|----------------------|
| Host | Host | Target (scrape endpoint) |
| Service / check | Item + Trigger | Metric + Alert rule |
| NRPE | Zabbix Agent | Node Exporter |
| Passive check | Trapper item | Pushgateway |
| Contact | User + Media type | Alertmanager receiver |
| Escalation | Action escalation steps | Alertmanager routes |

**Nagios plugins are reusable** in Zabbix as external checks with minimal modification -- the exit code and output format are compatible.

For detailed migration steps, load `references/migration.md`.

## Reference Files

Load these when you need deep knowledge for a specific area:

- `references/architecture.md` -- Core vs XI, execution model (active/passive/NRPE/NSCA), object definitions (hosts, services, contacts, commands, timeperiods), templates and inheritance, check intervals, event handlers, notifications, escalations, dependencies, flap detection, acknowledgements, downtime. Read for configuration and operational questions.
- `references/migration.md` -- Detailed Nagios-to-Zabbix and Nagios-to-Prometheus migration paths with concept mapping, step-by-step procedures, plugin reuse strategies, and key paradigm differences. Read when planning a migration.