iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
To enable email alerts in Icinga 2, configure all four links in the notification chain: a recipient User or UserGroup, a host or service Notification apply rule, a mail NotificationCommand or script, and an enabled notification feature. Give each recipient a valid email address and enable_notifications = true, validate the configuration with icinga2 daemon -C, then test the external mail delivery mechanism as the Icinga service account.
How Icinga email notifications work
Icinga separates deciding who should be notified from deciding how a message is delivered. A check changes state, a notification rule decides whether that event qualifies, and a notification command hands the message to an external script or mail transport. Icinga 2 itself does not deliver SMTP mail. The notification command must invoke a working local script, relay, or other mail mechanism.
An alert is therefore delivered only when each of these conditions is true:
- A
User(or a member of aUserGroup) is selected. - The user has an
emailattribute andenable_notifications = true. - A
Notificationapply rule matches the host or service that changed state. - The rule imports a mail template or specifies a mail
NotificationCommand. - The notification feature is enabled and the command is executable by the Icinga service account.
- The event’s state and notification type pass the configured filters, and the interval does not suppress it.
Missing any one of these links can produce a valid-looking configuration with no email.
1. Define a recipient User
Create a user object for every person or mailbox that can receive alerts. This example follows the documented Icinga pattern:
object User "icingaadmin" {
display_name = "Icinga 2 Admin"
enable_notifications = true
states = [ OK, Warning, Critical ]
types = [ Problem, Recovery ]
email = "icinga@localhost"
}Replace the example address with a real mailbox in production. The address belongs in the User object or in whatever managed configuration source generates that object. A syntactically valid address does not prove that mail can be delivered; the external command and mail transport still have to work.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsWhat each User setting controls
display_nameis the human-readable name shown by Icinga interfaces and notification data.enable_notificationsmust betrue; a disabled user will not receive notifications even if a rule selects that user.emailsupplies the destination used by the mail command. If it is missing or empty, the command has no recipient address.stateslimits the host or service states that can generate notifications for this user.typeslimits event types such as problems and recoveries.
If states or types is omitted, Icinga treats all states or all notification types as eligible. Explicit filters are safer when a mailbox should receive only a defined subset of events.
2. Decide where recipients are managed
You can attach recipients directly in a notification rule, or store routing data with the host or service in vars.notification["mail"]. Both approaches ultimately resolve to users or groups.
Direct user or group assignment
Direct assignment is easy to audit when a small, stable set of recipients handles a rule. The notification rule sets users or user_groups explicitly, as shown in the service example below.
Routing through notification.mail
When ownership varies by host or service, place the recipients in the object’s custom variables. The documented structure is:
vars.notification["mail"] = {
groups = [ "icingaadmins" ]
users = [ "icingaadmin" ]
}An apply rule can read those groups and users values. This keeps recipient routing beside the monitored object and is useful when another configuration system generates hosts or services. Ensure every referenced name resolves to an existing User or UserGroup; a variable containing a misspelled name does not create a recipient automatically.
3. Apply a mail notification to services and hosts
A notification apply rule determines which objects can generate mail. The target after to is significant: host and service notifications are separate object types and use different mail templates.
Service alerts
apply Notification "mail-noc" to Service {
import "mail-service-notification"
user_groups = [ "noc" ]
assign where host.vars.notification.mail
}This rule imports the mail-service template, sends to the noc group, and applies only when the host has a truthy notification.mail variable. If your design stores explicit users instead of a group, set users to the intended user names. If you use the nested routing object, the template or rule must map its groups and users members to the notification recipients.
Host alerts
apply Notification "mail-host-noc" to Host {
import "mail-host-notification"
user_groups = [ "noc" ]
assign where host.vars.notification.mail
}Use to Host and import mail-host-notification for host state changes. A service rule does not automatically cover host notifications, and a host rule does not automatically cover every service. If you need both, define both apply rules and make their assignment expressions match the intended objects.
Free tools Windows power users keep installed
One-click scans. No signup required.
Check the assignment expression
The assign where clause is a gate. If it evaluates to false for an object, no notification object is generated for that object. Verify the variable path and value exactly, including capitalization and nesting. A host-level variable may be present while a service-level expression checks a different path, leaving the service without a rule.
4. Provide a mail NotificationCommand
Icinga 2 does not know how to send notifications on its own. A NotificationCommand invokes an external mechanism, commonly a shell script. A fresh installation includes example host and service email scripts; treat them as starting points rather than a guaranteed production mail system.
Rank #4
- Used Book in Good Condition
Adapt the delivery mechanism
Review the example command and adapt it to your environment’s mail transport, sender address, authentication requirements, and message formatting. The correct implementation depends on whether your server hands mail to a local transfer agent, an authenticated relay, or another service. The Icinga notification layer supplies event data; the external command is responsible for handing that data to the transport.
- Confirm that the command passes the recipient address from the User’s
emailattribute. - Set a sender identity accepted by your relay and policy.
- Preserve useful host, service, state, output, and time information in the message body.
- Use the host and service example scripts as a baseline, then remove assumptions that do not match your transport.
Check execution rights
The script must be executable by the operating-system account running Icinga. A script that works in your interactive shell can still fail when the Icinga account lacks execute permission, cannot read a referenced file, or has a different environment. Test the command using the Icinga service account and the same paths used by the configured NotificationCommand. Do not rely on a user’s shell aliases, home-directory configuration, or interactive credentials.
Recommended Free Tools
Enable the notification feature
The notification feature must be enabled for notification commands to execute. A correct User, rule, and script will still produce no mail if that feature is disabled. Check feature enablement before changing recipient filters or rewriting the message script.
5. Choose states, notification types, and repeat intervals
Notification filters determine which events reach a recipient. The filters can be defined in the User, notification template, or notification object according to your configuration design. When no filter is specified, Icinga assumes all states or all notification types are eligible.
Best Value
| Setting | Examples | Effect |
|---|---|---|
states |
Warning, Critical, Unknown, OK |
Limits notifications to selected host or service states. Include every state you expect to test. |
types |
Problem, Acknowledgement, Recovery, downtime events |
Controls which event categories produce mail. |
interval |
The documented example uses 30 minutes | Controls how often a continuing problem is re-notified. The value is an example/default in the configuration, not a performance statistic. |
One-time versus repeating alerts
Set interval = 0 when the workflow calls for one notification without repeat reminders. Choose a nonzero interval when an unresolved incident should remind recipients periodically. A repeat interval does not create the first notification; the event must still pass the state and type filters.
Recovery behavior
Recovery notifications are normally sent only to recipients who previously received the related problem notification. Therefore, adding Recovery to a User’s types does not mean every recipient receives every recovery. The recipient must have been eligible for the problem notification as well.
6. Validate the configuration before testing mail
Run the built-in configuration check after every change:
icinga2 daemon -CResolve every error reported by this command before investigating delivery. A successful validation means the configuration can be parsed and assembled; it does not prove that a script can execute or that a relay accepts mail.
Inspect the generated object model
When a rule appears correct but no notification is generated, inspect the generated objects with the documented icinga2 object list workflow. Confirm that:
- The expected User exists, has the intended email address, and has notifications enabled.
- The host or service has a Notification object generated from the apply rule.
- The imported template or explicit command is present on that object.
- The resolved users and groups are the names you intended.
- The resulting states, types, and interval are not narrower than your test event.
This separates object-generation problems from command-execution and mail-transport problems.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Why Icinga may not send an email
| Symptom | Likely cause | What to check |
|---|---|---|
| No notification object for a host or service | The apply rule does not match. | Check the to Host or to Service target, the assign where expression, and the exact custom-variable path. |
| Notification exists but no recipient | User or group resolution failed. | Verify every name in users, user_groups, and vars.notification["mail"] maps to a defined object. |
| Recipient is listed but receives nothing | User is disabled or has no valid address. | Set enable_notifications = true and verify the email attribute. |
| Problem event is ignored | State or type filters exclude it. | Include the event’s state, such as Critical or Unknown, and the Problem type. |
| Recovery email is missing | The recipient did not receive the original problem, or Recovery is filtered. |
Check both the problem and recovery type filters and the original recipient eligibility. |
| Only the first alert arrives | Repeat interval is zero or the configured interval has not elapsed. | Review interval; zero intentionally disables re-notifications. |
| Notification command never runs | Notification feature is disabled. | Enable the feature, then reload the validated configuration. |
| Command runs but mail is not delivered | Script permissions or external mail transport failure. | Execute the command as the Icinga service account, check file permissions and paths, and inspect the relay or local mail system. |
| Configuration check fails | Syntax, missing object, or invalid attribute. | Run icinga2 daemon -C and fix the first reported error before testing again. |
A practical end-to-end setup sequence
- Create or update a
Userwith a realemailaddress andenable_notifications = true. Start with explicitstatesandtypesso the test is predictable. - Create the relevant
UserGroupif you route alerts to a team, and verify that its members are defined Users. - Choose recipient ownership: put users or groups directly in the rule for a simple fixed route, or add
vars.notification["mail"]to each host or service when routing is data-driven. - Add a service notification apply rule importing
mail-service-notification. Add a separate host rule importingmail-host-notificationif host alerts are required. - Confirm that the imported template or notification object references a working mail
NotificationCommand. - Enable the notification feature and make sure the external script is executable by the Icinga account.
- Run
icinga2 daemon -C. Do not proceed while validation errors remain. - Use
icinga2 object listto verify the generated User and Notification objects and their resolved recipients. - Test the command independently as the Icinga service account, then test an event whose state and type are allowed by your filters.
- If the event is generated but no message arrives, troubleshoot the external transport rather than changing the apply rule.
Direct configuration versus data-driven routing
| Decision point | Direct rule assignment | notification.mail routing |
|---|---|---|
| Recipient location | Users or groups are written in the Notification rule. | Users and groups are stored with each host or service. |
| Best fit | Small environments with a stable operations team. | Many objects with different owners or generated configuration. |
| Rule scope | Separate host and service rules still apply. | Separate host and service rules still apply; the variable only supplies routing data. |
| Filter precision | Set states and types in the User, template, or notification object. | Use the same state and type controls; recipient storage does not change event filtering. |
| Repeat behavior | Set interval on the notification design. |
Set interval on the notification design; routing variables do not alter it. |
| Delivery mechanism | Both approaches rely on an external NotificationCommand, commonly a script, and an enabled notification feature. | |
Production checklist
- Use a real monitored mailbox rather than leaving the example address unchanged.
- Keep recipient definitions in one managed source so address changes do not leave stale Users behind.
- Document which hosts and services set
vars.notification["mail"]and which apply rule consumes it. - Define whether the team wants only problems and recoveries or also acknowledgements and downtime events.
- Choose an interval that matches the incident process; use zero only when repeat reminders are intentionally unwanted.
- Verify that the sender, relay authentication, and message format used by the external script match local mail policy.
- Restrict script and configuration permissions while ensuring the Icinga service account can execute and read what it needs.
- Keep host and service rules distinct so a test validates the same object type used in production.
- After changes, run
icinga2 daemon -C, inspect generated objects when necessary, and test the command under the service account.
What a successful test proves
A complete test should demonstrate each boundary separately: the host or service matches an apply rule; the rule resolves a User or UserGroup; the User allows the event and has an address; the notification feature invokes the command; the script is executable under the Icinga account; and the external transport accepts the message. Checking these boundaries in order is faster than repeatedly changing the email address or notification rule without confirming whether an object was generated.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
