> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/inbound-integrations/nagios.md).

# Nagios Integration

Send Nagios notifications to ilert with the ilert notification plugin: a problem opens an alert, an acknowledgment accepts it, and a recovery resolves it.

[Nagios](https://www.nagios.org/) runs host and service checks and sends a notification when a state changes. The ilert plugin adds a Nagios contact and notification command that pass each notification to an ilert alert source. A problem opens an alert, an acknowledgment accepts it, and a recovery resolves it.

## Requirements <a href="#requirements" id="requirements"></a>

* Python 3.7 or later on the Nagios server. If the server only has Python 2, see [Use Python 2](#use-python-2).
* Outbound HTTPS from the Nagios server to `api.ilert.com`.

These steps use the paths of the `nagios4` package on Ubuntu 24.04, and were last run against Nagios Core 4.4.6 with Python 3.12. A source install keeps its configuration under `/usr/local/nagios/etc`, so adjust the paths to match.

## In ilert: Create a Nagios alert source <a href="#create-alarm-source" id="create-alarm-source"></a>

1. Go to **Alerting** → **Alert sources** and click **Create new alert source**.
2. Search for **Nagios**, click the **Nagios / Icinga** tile, and click **Next**.
3. Give your alert source a name, optionally assign teams, and click **Next**.
4. Choose who gets notified: select **Use existing escalation policy** and pick a policy, or **Generate new escalation policy** to start with a basic one that notifies you first. Click **Next**.

   <figure><img src="https://3394882078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M76ygPnS4HUcFSX8ulm%2Fuploads%2Fgit-blob-8a281bf3931f5a1a531951ce97984d50989dd875%2Falert-source-escalation-step.png?alt=media" alt="The escalation step of the ilert alert source wizard, headed Who should be notified about alerts, with an escalation policy selected and a preview of its escalation rules below."><figcaption><p>Pick an existing escalation policy, or generate a basic one without leaving the wizard.</p></figcaption></figure>
5. Select **Default grouping** and click **Continue setup**. It groups events by the [alert key](#what-each-notification-does-in-ilert) the plugin sets; the other [grouping options](/alerting/configure-alerting/alert-sources.md#event-grouping) are easier to judge once events are arriving.
6. The next page shows more settings, such as notification priority and alert templates. Click **Finish setup** for now; you can change them later.
7. On the final page, ilert shows the integration key for this alert source. Copy it; you will put it in the Nagios contact in the next section.

## In Nagios: Install the notification plugin <a href="#installation-guide" id="installation-guide"></a>

{% stepper %}
{% step %}

### Install the plugin

Download the plugin and copy it to `/usr/local/bin`. Nagios and cron both run it from there.

```bash
curl -sSLO https://github.com/iLert/ilert-nagios/archive/refs/tags/v1.7.1.tar.gz
tar xzf v1.7.1.tar.gz
cd ilert-nagios-1.7.1
sudo install -m 755 ilert_nagios.py /usr/local/bin/ilert_nagios.py
```

{% endstep %}

{% step %}

### Turn on environment macros

The plugin reads the details of each notification from environment macros. The `nagios4` package turns them off by default.

```bash
sudo sed -i 's/^enable_environment_macros=0/enable_environment_macros=1/' /etc/nagios4/nagios.cfg
```

To keep them off, for example on a large installation where they add load, use the second `notify-ilert` command in `ilert_nagios.cfg` instead. It passes the macros as arguments. Uncomment it and delete the first one.
{% endstep %}

{% step %}

### Add the ilert contact

`ilert_nagios.cfg` defines a contact called `ilert` and the `notify-ilert` command. Put your integration key in the contact's `pager` field, then copy the file into a directory that Nagios reads.

```bash
sed -i 's/<YOUR API KEY>/YOUR_INTEGRATION_KEY/' ilert_nagios.cfg
sudo install -m 640 -o root -g nagios ilert_nagios.cfg /etc/nagios4/conf.d/ilert_nagios.cfg
```

The package already lists `/etc/nagios4/conf.d` as a `cfg_dir`. If you put the file somewhere that `nagios.cfg` does not read, add a `cfg_file=` line for it.
{% endstep %}

{% step %}

### Add the contact to a contact group

Nagios notifies a contact only if the host or service names it, usually through a contact group. In `/etc/nagios4/objects/contacts.cfg`, add `ilert` to the members of the group your hosts and services use. In the default configuration, that is `admins`:

```
define contactgroup {
    contactgroup_name       admins
    alias                   Nagios Administrators
    members                 nagiosadmin,ilert
}
```

{% endstep %}

{% step %}

### Add the retry job

The plugin keeps an event it could not send in `/tmp/ilert_nagios`. This cron job for the `nagios` user sends those events every minute:

```bash
(sudo crontab -u nagios -l 2>/dev/null; echo '* * * * * python3 /usr/local/bin/ilert_nagios.py -m send') | sudo crontab -u nagios -
```

{% endstep %}

{% step %}

### Check the configuration and restart Nagios

```bash
sudo /usr/sbin/nagios4 -v /etc/nagios4/nagios.cfg
sudo systemctl restart nagios4
```

The check ends with `Total Warnings: 0` and `Total Errors: 0`.
{% endstep %}

{% step %}

### Test the plugin

{% hint style="warning" %}
This step and the next open real alerts in ilert, and the alert source's escalation policy notifies whoever it names.
{% endhint %}

Run the plugin as the `nagios` user. Running it as root creates `/tmp/ilert_nagios` owned by root, and Nagios then [cannot write events there](#the-log-shows-could-not-write-event).

```bash
sudo -u nagios python3 /usr/local/bin/ilert_nagios.py -m save -a YOUR_INTEGRATION_KEY NOTIFICATIONTYPE=PROBLEM HOSTNAME=ilert-test HOSTADDRESS=ilert-test HOSTSTATE=DOWN HOSTOUTPUT="Test alert from the Nagios plugin"
```

The alert appears under **Alerts** with the summary `PROBLEM Host Alert: ilert-test is DOWN - Test alert from the Nagios plugin`. Resolve it:

```bash
sudo -u nagios python3 /usr/local/bin/ilert_nagios.py -m save -a YOUR_INTEGRATION_KEY NOTIFICATIONTYPE=RECOVERY HOSTNAME=ilert-test HOSTADDRESS=ilert-test HOSTSTATE=UP HOSTOUTPUT="Test recovery from the Nagios plugin"
```

{% endstep %}

{% step %}

### Test a notification from Nagios

The last test skipped Nagios itself. This one sends a failing result for a service, four times because the default `local-service` template needs four failures before it notifies. It uses the `PING` service on `localhost` from the default configuration, so change those two names if you do not have it.

```bash
for i in 1 2 3 4; do
  printf '[%s] PROCESS_SERVICE_CHECK_RESULT;localhost;PING;2;Test from Nagios\n' "$(date +%s)" | sudo tee /var/lib/nagios4/rw/nagios.cmd > /dev/null
  sleep 15
done
```

The alert appears with the summary `PROBLEM Service Alert: localhost/PING is CRITICAL - Test from Nagios`. The next real check of the service resolves it. To resolve it right away, send a passing result:

```bash
printf '[%s] PROCESS_SERVICE_CHECK_RESULT;localhost;PING;0;Test recovery from Nagios\n' "$(date +%s)" | sudo tee /var/lib/nagios4/rw/nagios.cmd > /dev/null
```

If no alert appears, see [Troubleshooting](#troubleshooting).
{% endstep %}
{% endstepper %}

## What each notification does in ilert

| Nagios notification type                                             | What ilert does                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PROBLEM`                                                            | Opens an alert and starts its escalation policy. If an alert with the same key is still open, the event goes to that alert and its summary does not change. If someone resolved the alert by hand and the problem is still there, the next notification opens a new alert |
| `ACKNOWLEDGEMENT`                                                    | Accepts the alert, which stops its escalation, and records it on the alert's timeline                                                                                                                                                                                     |
| `RECOVERY`                                                           | Resolves the alert                                                                                                                                                                                                                                                        |
| Any other type, such as `CUSTOM`, `DOWNTIMESTART` or `FLAPPINGSTART` | Nothing. ilert takes the event and opens no alert, so a custom notification from Nagios is not a usable test                                                                                                                                                              |

The contact's notification options decide which of these Nagios sends. The defaults in `ilert_nagios.cfg` are `w,u,c,r` for services and `d,r` for hosts, so a service that goes to WARNING opens an alert too. Remove `w` to stop that, and keep `r`, because without recoveries no alert resolves by itself. An acknowledgment reaches ilert only if you keep the option to send a notification on when you acknowledge the problem.

The **alert key** is `HOSTADDRESS` for a host and `HOSTADDRESS-SERVICEDESC` for a service, for example `127.0.0.1-PING`. With **Default grouping**, events with the same key belong to one alert, so two hosts with the same address share their host alert.

## Use Python 2

Python 2 is end of life, so use this only on a server that cannot run Python 3. The plugin needs Python 2.7.9 or later, and the `python` command must start it. The files are in the `python2` folder of the download, and their commands call the script directly instead of through `python3`.

Replace the steps [Install the plugin](#installation-guide) and **Add the retry job** with this, run from the folder of the download:

```bash
cd python2
sudo install -m 755 ilert_nagios.py /usr/local/bin/ilert_nagios.py
(sudo crontab -u nagios -l 2>/dev/null; echo '* * * * * /usr/local/bin/ilert_nagios.py -m send') | sudo crontab -u nagios -
```

Follow the other steps as written, with the `ilert_nagios.cfg` from the `python2` folder, and leave `python3` out of the test commands.

## Troubleshooting

Start with the logs. The plugin writes to the system log, such as `/var/log/syslog` or `/var/log/messages`, with the tag `ilert_nagios.py`. The Nagios log is `/var/log/nagios4/nagios.log`. If the entries below do not explain what you see, contact <support@ilert.com>.

### The log shows `parameter apikey is required`

The Nagios log shows `ilert_nagios.py: error: parameter apikey is required in save mode` and no event reaches ilert. The plugin got no details from Nagios, because environment macros are off. Turn them on and restart Nagios, or use the second `notify-ilert` command in `ilert_nagios.cfg`.

### The log shows `invalid API key`

The system log shows `event not accepted by iLert` and `HTTP 400 invalid API key`. The key in the contact's `pager` field is wrong, or the alert source's key has been rotated. Correct it and restart Nagios. The plugin deletes an event that ilert rejects, so that notification does not come back.

### The log shows `could not send event`

The system log shows `could not send event to iLert`, followed by the network error. The Nagios server cannot reach `api.ilert.com`. The event waits in `/tmp/ilert_nagios`, and the retry job sends it once the connection is back. If events stay in that directory while the connection is up, check that the job exists with `sudo crontab -u nagios -l`.

### The log shows `could not write event`

The system log shows `could not write event to /tmp/ilert_nagios` and `Permission denied`. The directory belongs to root, usually because someone ran the plugin as root first. Give it back to the `nagios` user:

```bash
sudo chown -R nagios:nagios /tmp/ilert_nagios
```

### No alert appears and the logs show no error

Look for the notification in the Nagios log:

```bash
grep 'NOTIFICATION: ilert' /var/log/nagios4/nagios.log
```

**If it is not there,** Nagios did not notify the contact. Check that the contact is in a contact group of that host or service. Check the notification period too: the default `linux-server` host template uses `workhours`, so host notifications wait until working hours.

**If it is there,** open the alert source in ilert and look at its [**Alert source logs**](/alerting/working-with-alerts/alert-source-logs.md). A listed event that opened no alert was either a [type ilert does not act on](#what-each-notification-does-in-ilert) or went to an alert that is still open.

### Running the plugin shows `No module named request`

The error reads `import urllib.request ImportError: No module named request`. Python 2 is running the Python 3 script. Use `python3`, or [install the Python 2 script](#use-python-2).

## FAQ <a href="#faq" id="faq"></a>

**What happens if the connection to ilert is interrupted?**

The plugin keeps the event in `/tmp/ilert_nagios` after a network error, an HTTP 429 or a server error, and the retry job sends it within a minute of the connection coming back. Events in that directory are lost if `/tmp` is cleared, for example at a reboot. To keep them elsewhere, add `-d DIRECTORY` to both the `notify-ilert` command and the cron job.

**Can I send notifications to more than one alert source?**

Yes. Copy the contact, give the copy a new `contact_name` and the other alert source's key in `pager`, and add it to the contact groups of the hosts and services that belong to that alert source.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ilert.com/integrations/inbound-integrations/nagios.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
