> 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/checkmk/native.md).
# Checkmk Integration (v 2.0+ )
Send Checkmk 2.x notifications to ilert with the built-in iLert notification method, and optionally acknowledge Checkmk problems from ilert.
Checkmk 2.0 and later include an **iLert** notification method. Add a notification rule that uses it, and Checkmk posts each notification to a checkmk alert source in ilert. A problem opens an alert, an acknowledgment accepts it, and a recovery resolves it.
These steps were last run against Checkmk 2.5 and 2.3. On Checkmk 1.x, use the [guide for the ilert plugin](/integrations/inbound-integrations/checkmk/check-mk.md) instead.
## In ilert: Create a Checkmk alert source
1. Go to **Alerting** → **Alert sources** and click **Create new alert source**.
2. Search for **checkmk**, click its 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**.
Pick an existing escalation policy, or generate a basic one without leaving the wizard.
5. Select **Default grouping** and click **Next**. The wizard then asks **Enable two-way alert status sync?** Select **Turn off bi-directional mode**, or see [Optional: Acknowledge Checkmk problems from ilert](#optional-acknowledge-checkmk-problems-from-ilert), then click **Continue setup**.
6. The next page shows more settings, such as notification priority and alert templates. Click **Finish setup** for now, or **Continue setup** if you turned two-way sync on.
7. On the final page, ilert shows the integration key for this alert source. Copy it; you will paste it into the notification rule in the next section.
## In Checkmk: Add a notification rule
{% tabs %}
{% tab title="Checkmk 2.4 and later" %}
Go to **Setup** → **Events** → **Notifications** and click **Add notification rule**. The rule opens as a guided form with six steps. These labels are from Checkmk 2.5; Checkmk 2.4 spells two of them differently, **Acknowledgement of problem** and **iLert alert source API key**.
1. **Triggering events**: Keep **Specific events**. The preset covers hosts going DOWN or UP and services going to CRIT, WARN or OK. Click **Add event** under both **Host events** and **Service events**, and add **Acknowledgment of problem** to each; without it, acknowledging a problem in Checkmk does not reach ilert. Remove the WARN event if warnings should not open alerts. Avoid **All events**, because it also [opens alerts for downtimes](#what-each-notification-does-in-ilert). Click **Next step: Specify host/services**.
2. **Filter for hosts/services**: Leave this empty to cover everything, or narrow it to the hosts and services this alert source is for. Click **Next step: Notification method (plug-in)**.
3. **Notification method (plug-in)**: Select **iLert**. Choose **Select parameters** and click **Create**. Enter a **Description**, paste the integration key under **ilert alert source API key** with **Explicit** selected, and click **Save**. Click **Next step: Recipient**.
4. **Recipient**: Under **Select recipient**, choose **Specific users** and add one user. Do not keep the default, **All contacts of the affected object**: on a host without contacts it creates no notification. One user is enough, because Checkmk sends one notification per recipient. Click **Next step: Sending conditions**.
5. **Sending conditions**: Nothing is needed here. Click **Next step: General properties**.
6. **General properties**: Enter a **Description**, click **Next step: Review all settings**, and click **Apply & test notification rule**. The rule takes effect without **Activate changes**.
{% endtab %}
{% tab title="Checkmk 2.3 and earlier" %}
Go to **Setup** → **Events** → **Notifications** and click **Add rule**. These labels are from Checkmk 2.3.
1. Under **Rule properties**, replace the **Description**.
2. Under **Notification method**, set **Notification Method** to **iLert**. Under **iLert alert source API key**, keep **API key** selected and paste the integration key.
3. Under **Contact selection**, clear **All contacts of the notified object**, select **The following users**, and add one user. On a host without contacts, the default creates no notification. One user is enough, because Checkmk sends one notification per recipient.
4. Under **Conditions**, select **Match host event type** and **Match service event type**, and choose the state changes you want plus the acknowledgment. Without these two conditions, the rule sends every event, which also [opens alerts for downtimes](#what-each-notification-does-in-ilert).
5. Click **Save**, and activate the pending change if Checkmk shows one.
{% endtab %}
{% endtabs %}
## Check that it works
{% stepper %}
{% step %}
### Fake a problem
{% hint style="warning" %}
This opens a real alert in ilert, and the alert source's escalation policy notifies whoever it names.
{% endhint %}
Open a service in Checkmk, click **Commands**, click the three dots at the top of the menu to show more entries, and click **Fake check results**. Select **Critical** under **Result**, enter a test message under **Plug-in output**, and click **Fake check result**.
The alert appears under **Alerts** with a summary such as `PROBLEM Service Alert: acme-web-1/Memory is CRITICAL - Test from Checkmk`.
{% endstep %}
{% step %}
### Acknowledge the problem
Click **Commands** → **Acknowledge problems**, enter a comment, select **Notify affected users if notification rules are in place (send notifications)**, and submit. The alert in ilert changes to **Accepted**, and its escalation stops.
{% endstep %}
{% step %}
### Let the problem recover
The next real check of the service sets it back to OK, or you can fake an **OK** result. The alert in ilert changes to **Resolved**.
If nothing arrives in ilert, see [Troubleshooting](#troubleshooting).
{% endstep %}
{% endstepper %}
## What each notification does in ilert
Each row is a type of notification Checkmk can send. Your rule's events and conditions decide which of them it sends.
| Notification type | Sent for | What ilert does |
| --------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `PROBLEM` | A state change to DOWN, CRIT or WARN | Opens an alert and starts its escalation policy. If an alert with the same key is still open, the event goes to that alert |
| `RECOVERY` | A state change to UP or OK | Resolves the alert |
| `ACKNOWLEDGEMENT` | **Acknowledgment of problem** | Accepts the alert, which stops its escalation |
| `DOWNTIMESTART` | **Start or end of downtime** | Opens an alert, although the host or service may be fine |
| `DOWNTIMEEND`, `DOWNTIMECANCELLED` | **Start or end of downtime** | Resolves the alert |
| `FLAPPINGSTART` | **Start or end of flapping state** | Opens an alert |
| `FLAPPINGSTOP` | **Start or end of flapping state** | Resolves the alert |
| `CUSTOM` and any other type, such as `ALERTHANDLER` | The **Send custom notification** command, or another event the rule includes | Opens an alert |
The **alert key** is `HOSTADDRESS` for a host and `HOSTADDRESS-SERVICEDESC` for a service, for example `192.0.2.10-Memory`. With **Default grouping**, events with the same key belong to one alert, so two hosts with the same address share their host alert. [Two-way sync](#optional-acknowledge-checkmk-problems-from-ilert) changes this key.
## Notification rule settings
These settings sit next to the key in the notification parameters. They are optional. The labels are from Checkmk 2.5, and Checkmk 2.3 words some of them slightly differently.
| Setting | What it does |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Notification priority (this will override the priority configured in the alert source)** | Sets the priority of alerts from this rule, but only while the alert source has its default high priority. On an alert source set to anything else, its own setting wins, despite this label |
| **Custom incident summary for host alerts** | The alert summary for hosts. Default: `$NOTIFICATIONTYPE$ Host Alert: $HOSTNAME$ is $HOSTSTATE$ - $HOSTOUTPUT$` |
| **Custom incident summary for service alerts** | The alert summary for services. Default: `$NOTIFICATIONTYPE$ Service Alert: $HOSTALIAS$/$SERVICEDESC$ is $SERVICESTATE$ - $SERVICEOUTPUT$` |
| **Proxy** | Sends the notification through a proxy |
| **Disable SSL certificate verification** | Skips the check of the server certificate on the connection to ilert |
| **URL prefix for links to Checkmk** | Leave this as it is. In a test on Checkmk 2.5, it did not produce a working link on the alert in ilert |
## Optional: Acknowledge Checkmk problems from ilert
{% hint style="info" %}
Two-way sync requires an [ilert Scale plan](https://www.ilert.com/pricing) or higher.
{% endhint %}
With two-way sync, accepting an alert in ilert acknowledges the problem in Checkmk, and a comment on the alert becomes a comment on the problem. Resolving an alert in ilert changes nothing in Checkmk, because the state of a host or service comes from its checks.
ilert calls the Checkmk REST API from its own servers, so Checkmk must be reachable from the internet. Turn the sync on while you create the alert source: its settings offer no way to turn it on later, and you cannot set it up through the API.
Two-way sync changes how events become alerts. The alert key also includes Checkmk's problem ID, so each new problem gets its own alert, and a repeat notification for a problem that already has an open alert is dropped.
{% stepper %}
{% step %}
### Check your Checkmk API address and user
Use a Checkmk user that may acknowledge problems on the hosts this alert source covers. An automation user with the `admin` role works, with its automation secret as the password. Test the address and the user:
```bash
curl -u YOUR_USERNAME:YOUR_PASSWORD https://YOUR_CHECKMK_HOST/YOUR_SITE/check_mk/api/1.0/version
```
A working address and user return a JSON document with the site name and Checkmk version. HTTP 401 means the user or password is wrong, and HTTP 404 means the address is wrong.
{% endstep %}
{% step %}
### Turn on the sync
In the alert source wizard, at **Enable two-way alert status sync?**, select **Enable two-way synchronization of alert status** and click **Continue setup**. Keep clicking **Continue setup** until ilert asks for the connection details.
{% endstep %}
{% step %}
### Enter the connection details
Enter the values you just tested:
| Field | Value |
| ------------ | ------------------------------------------------------ |
| **Url** | `https://YOUR_CHECKMK_HOST/YOUR_SITE/check_mk/api/1.0` |
| **Username** | The Checkmk user |
| **Password** | The password or automation secret |
The **Url** must include the full path to the API. The address of your Checkmk instance alone does not work: every call fails with HTTP 404.
Click **Continue setup** and finish the wizard. ilert creates a connector and an alert action that carry the sync. Change the connection details on the alert source, not on those two, and do not delete them, because the sync stops without them.
{% endstep %}
{% step %}
### Check the sync
Accept an alert from this alert source in ilert. In Checkmk, the problem shows as acknowledged. Add a comment to the alert, and it appears as a comment on the problem.
{% endstep %}
{% endstepper %}
## Troubleshooting
Start with **Analyze recent notifications** on the **Notifications** page (**Show analysis** in Checkmk 2.3), or with `~/var/log/notify.log` as the site user. If the entries below do not explain what you see, contact .
### `notify.log` shows `no notification has been created`
The log shows, for example, `2 rules matched, but no notification has been created.` The rule matched, but it has no recipient. This is what the default recipient does on a host without contacts. Set the rule's recipient to one specific user.
### The alert stays pending after an acknowledgment
`notify.log` shows `does not match: Event type 'x' not handled by this rule`. The rule does not include acknowledgments. Add **Acknowledgment of problem** to its events, and keep the notification option on when you acknowledge.
### `notify.log` shows `Event type 'f' not handled`
The service is flapping, often after several faked results in a row, and Checkmk has stopped sending normal notifications for it. Wait until the service settles, or add **Start or end of flapping state** to the rule if you want an alert for flapping.
### The log shows `invalid API key`
The notification result reads `400: Bad Request;Event not accepted by iLert` with `HTTP 400 invalid API key`. The key in the notification parameter is wrong, or the alert source's key has been rotated. Correct it in **Parameters for notification methods**, or in the rule itself on Checkmk 2.3.
### No alert appears and Checkmk reports success
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 went to an alert that is still open, or the alert source is disabled or in a maintenance window.
## FAQ
**Will alerts in ilert be resolved automatically?**
Yes, as soon as the host or service is UP or OK again, provided the rule sends those state changes. The preset events do.
**Can I send notifications to more than one alert source?**
Yes. Add one notification rule per alert source, each with that alert source's integration key and a **Filter for hosts/services** that selects its hosts.
---
# 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/checkmk/native.md?ask=&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.
