Skip to main content
Icinga 2 monitors your hosts and services and decides when something is worth telling a human about. Connect it to incident.io to page the right people when a check goes critical, and to resolve the alert automatically when that check recovers. Icinga 2 sends alerts to incident.io through the icinga2-plugin integration, pointed at an HTTP alert source you create in incident.io. The integration is a notification command: Icinga runs it when a notification fires, and it posts an alert carrying the host, service, state, and any custom variables you choose to send. Once connected, Icinga alerts flow into your alert routes for escalation and incident creation, just like any other source. Two things follow from Icinga owning the decision to notify:
  • Icinga’s suppression applies first. Downtimes, acknowledgements, notification periods, and times windows are all evaluated before incident.io sees anything. An object in a scheduled downtime does not page anyone.
  • Nothing changes until you opt in. Installing the integration sends no alerts. You choose which hosts and services participate with vars.incident_io = true.

​
Before you start

Notifications only ever fire from the master zone, so satellites and agents need nothing installed and need no egress. Icinga’s config sync distributes .conf files but not executables, so each master needs the package.

​
Instructions

1

Create the alert source

  1. Head over to the Alerts section in your incident.io dashboard.
  2. Select the sources tab at the top of the page.
  3. Press the New alert source button.
  4. Search for HTTP, then click continue to create the alert source. Name it something you will recognize, such as Icinga 2.
  5. Leave the source type as Default. The integration already sends incident.io’s standard alert schema, so you do not need a transform expression.
  6. Copy the URL and bearer token shown on the setup page. You will paste both into Icinga in step 3.
2

Install the integration on each master

Download the .deb or .rpm from the releases page and install it on every master in your master zone:
This installs the notification handler to /usr/bin/incident-io-icinga and its Icinga configuration to /etc/icinga2/conf.d/. Use whatever configuration management already installs packages on your masters, so a new master does not come up missing it.
3

Add your credentials

On each master, create the credentials file from the example the package ships:
Fill in the URL and token from step 1, and the base URL of your Icinga Web 2 install:
IncidentIoIcingaWebUrl puts a link back to the object on every alert, so a responder can go from the page to the check in one click. IncidentIoIcingaWebStyle decides which Icinga Web 2 front end that link points at: use icingadb for Icinga DB Web, or monitoring for the older monitoring module. If you are unsure, open a host in Icinga Web 2 and look at the path in your browser.
Keep this file out of zones.d. Config sync would stage a copy of your token under /var/lib/icinga2/api/zones/ on every node in the zone.
4

Choose which objects alert

Mark the hosts and services you want paged on. A host set to true covers its services too:
Set vars.incident_io = false on an individual service to carve it out again. To route your whole estate, change the assign where clauses in /etc/icinga2/conf.d/incident-io-notifications.conf to assign where true.
5

Validate and reload

If validation complains that IncidentIoUrl is undefined, the credentials file from step 3 has not been created yet.

​
Confirm it works

Build a payload without sending anything, to check the handler runs:
Then send a real one. In Icinga Web 2, open any object you opted in and use Send custom notification. The alert appears in incident.io within a few seconds. Handler output goes to syslog under the tag incident-io-icinga, so journalctl -t incident-io-icinga tells you what happened to a notification that did not arrive.
We recommend opting in a handful of objects, or a non-production zone, and watching those alerts arrive before you enable Icinga alerting across your estate.

​
Route alerts with Icinga metadata

Every alert carries a metadata object, which you can use to build alert attributes and route alerts to the right team. You get these without configuring anything: You can add anything else Icinga knows. Name existing custom variables to promote them, or set an explicit dictionary:
Promoting variables by name is deliberate rather than exporting everything, because custom variables often hold check credentials. Nothing leaves your estate unless you name it. See metadata for nested objects, service-level metadata, and estate-wide defaults. check_source is worth calling out for distributed setups. It names the satellite that executed the check, so where your satellites map to datacenters, you can route EU checks to EU on-call. Once alerts are arriving, create an alert route to filter, group, and escalate them, or to automatically create incidents.

​
FAQs

Yes. Icinga sends a RECOVERY notification when a check comes good, and the integration resolves the alert it opened. This works because the deduplication key is built only from the host and service names, never from the state, timestamp, or the node that sent it.
No. Icinga’s notification component runs with enable_ha = true by default, so exactly one master owns notifications at a time and failover is automatic. Even if that assumption broke, both masters would produce the same deduplication key, so incident.io would collapse them into a single alert.
Icinga suppresses notifications for objects in downtime, so nothing is sent. If a downtime starts while an alert is already open, incident.io resolves it, so planned maintenance does not leave an alert hanging. The alert fires again if the problem is still there when the downtime ends.
No. Notifications only fire from the master zone. Satellites and agents keep running checks and need no egress to incident.io.
The repository ships a Director configuration basket under contrib/, which creates the Icinga objects through the Director UI. Director cannot install the handler itself, so you still need the package on every master.
Use this one for Icinga 2, and the Nagios integration for Nagios Core. Icinga 2 has its own configuration language and notification model, so it gets a notification command that understands host and service objects, custom variables, and satellites, rather than a Nagios plugin.