How to Enable Email Alerts in Icinga 2

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 rule, a NotificationCommand that calls an external mail mechanism, and an enabled notification feature. The recipient must have a valid email attribute and enable_notifications = true. State and notification-type filters decide which events qualify, while interval controls reminder frequency.

Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.

The configuration below uses Icinga’s documented object syntax. Validate it with icinga2 daemon -C before reloading Icinga, then troubleshoot in the order shown if mail does not arrive.

#	Preview	Product	Price
1		A Beginner’s Guide to Security, Monitoring, Camera Systems, and Surveillance Technology: A...	$11.76	Buy on Amazon
2		Practical Monitoring: Effective Strategies for the Real World	$13.95	Buy on Amazon
3		Electrician''s Guide to Control and Monitoring Systems: Installation, Troubleshooting, and...	$40.00	Buy on Amazon
4		The Practice of Network Security Monitoring: Understanding Incident Detection and Response	$48.65	Buy on Amazon
5		Designing Machine Learning Systems: An Iterative Process for Production-Ready Applications	$40.00	Buy on Amazon

As an Amazon Associate I earn from qualifying purchases.

What an Icinga email alert needs

Icinga notifications are a chain rather than a single mail setting. A check result first has to qualify for notification, then Icinga must resolve a recipient, select a notification object, and execute a command that hands the message to a mail system.

Icinga 2 does not send email on its own. It invokes an external mechanism, commonly a shell script. The scripts shipped as examples are starting points: adapt their sender, authentication, transport, and message formatting to your environment rather than assuming that an installation is already connected to a mail relay.

#1 Best Overall

A Beginner’s Guide to Security, Monitoring, Camera Systems, and Surveillance Technology: A Complete Beginner’s Guide to Security, Surveillance, Camera Systems, and Video Monitoring

$11.76

Buy on Amazon

Step 1: Define a recipient User

Create a User object for each person or service address that should receive notifications. The documented example is:

object User "icingaadmin" {
  display_name = "Icinga 2 Admin"
  enable_notifications = true
  states = [ OK, Warning, Critical ]
  types = [ Problem, Recovery ]
  email = "icinga@localhost"
}

Required attributes

• enable_notifications = true must be present for this recipient to receive notifications.
• email must contain a valid mailbox. Replace the example local address with a real production mailbox.
• states determines which host or service states are eligible. The example includes OK, Warning, and Critical.
• types determines which notification events are eligible. The example sends Problem and Recovery events.

If you omit states or types, Icinga treats the missing filter as all states or all notification types. That is convenient for a first configuration, but explicit lists make an alert policy easier to audit.

Use groups when several people share a policy

A UserGroup lets a notification rule address several users without listing each address repeatedly. Put the users in the group, then assign that group in a host or service notification rule. Keep the individual email address on the User object or in another managed configuration source so recipient data has one clear owner.

Step 2: Attach a notification rule to monitored objects

A notification apply rule is separate from the check itself. It decides which users or groups are notified when an object changes state. The target in the rule is significant: host and service notifications are different object types.

Rank #2

Sale

Practical Monitoring: Effective Strategies for the Real World

$13.95

Buy on Amazon

Service notifications

This documented pattern applies a mail template to services and sends it to the noc group when the host’s custom variable indicates that mail routing is enabled:

apply Notification "mail-noc" to Service {
  import "mail-service-notification"
  user_groups = [ "noc" ]
  assign where host.vars.notification.mail
}

import "mail-service-notification" supplies the template’s command and default behavior. The assign where expression is evaluated for each service. If a service’s host does not have vars.notification.mail, this rule does not apply to it.

Host notifications

For host-state alerts, create a corresponding rule targeted at hosts and import the host template:

apply Notification "mail-host-noc" to Host {
  import "mail-host-notification"
  user_groups = [ "noc" ]
  assign where host.vars.notification.mail
}

Using to Host with mail-host-notification keeps host events and service events on their appropriate templates. A service rule will not automatically cover host notifications, and a host rule will not automatically cover services.

Rank #3

Electrician''s Guide to Control and Monitoring Systems: Installation, Troubleshooting, and Maintenance

$40.00

Buy on Amazon

Assign users directly when the scope is small

You can set users = [ "icingaadmin" ] in a notification object when one or a few named recipients should always receive that rule. Groups are usually easier to maintain when many objects share the same on-call audience. Whichever form you choose, verify that every referenced name resolves to an actual User or UserGroup.

Step 3: Route recipients with vars.notification["mail"]

Recipient routing can live with host or service data instead of inside a global notification rule. The documented nested variable format is:

vars.notification["mail"] = {
  groups = [ "icingaadmins" ]
  users = [ "icingaadmin" ]
}

This structure is useful when ownership belongs to the object itself or when another configuration system generates host and service variables. The notification apply rule can read the groups and users values and pass them to the notification object. A rule using that model can be written as:

apply Notification "mail-from-object" to Service {
  import "mail-service-notification"
  user_groups = host.vars.notification.mail.groups
  users = host.vars.notification.mail.users
  assign where host.vars.notification.mail
}

Choose either a centrally assigned audience or object-level routing deliberately. Central rules make a global change quick; object variables make exceptions visible next to the monitored object. Mixing both without a naming convention can make it unclear why a particular person receives an alert.

Rank #4

Sale

The Practice of Network Security Monitoring: Understanding Incident Detection and Response

• Used Book in Good Condition

$48.65

Buy on Amazon

Step 4: Ensure a delivery command and mail transport exist

The notification object only schedules an invocation. Icinga 2 relies on a NotificationCommand to call an external mechanism, commonly a shell script. A fresh installation includes example host and service email scripts. Treat those files as templates, then adapt them for your mail transport, sender identity, authentication requirements, and message format.

Check the command path

• Confirm that the imported mail template names a command that exists in the generated configuration.
• Confirm that the command’s executable path points to the intended script or mail client.
• Make the script executable by the operating-system account that runs Icinga. A script that works when launched as an administrator can still fail when Icinga runs it with its service-account permissions.
• Check that every argument expected by the script is supplied by the notification template, including recipient, subject, and body values where applicable.

Enable the notification feature

The notification feature must be enabled for notification commands to execute. If the feature is disabled, the recipient and apply rule can be perfectly valid while no delivery command runs. Verify feature enablement before changing mail-script arguments.

Separate Icinga from mail delivery

Icinga does not provide the mail transfer itself. Your external mechanism may be a local mail command, a relay managed by your operations team, or another SMTP-capable service. The documentation establishes the hand-off point but does not prescribe a particular provider. Configure that mechanism’s sender, authentication, transport, and formatting according to its own requirements, then test it under the Icinga service account.

Step 5: Select states, event types, and reminder interval

Filters determine whether a state change produces a notification at all. Notification templates and users can specify states such as Warning, Critical, and Unknown. Event types can include Problem, Acknowledgement, Recovery, and downtime-related events.

Best Value

Sale

Designing Machine Learning Systems: An Iterative Process for Production-Ready Applications

$40.00

Buy on Amazon

Build a policy that matches the event

• Include Problem if the first failure should generate mail.
• Include Recovery if the same incident should generate a clear message when it returns to normal.
• Include Acknowledgement or downtime events only when those workflow changes belong in email.
• Include the state being tested. A service in Unknown will not match a filter containing only Warning and Critical.

When no state or type filter is specified, Icinga assumes all states and notification types. This can help prove the wiring during initial setup, after which you can narrow the policy.

Understand interval

The notification interval controls reminders while an incident remains in a notifying state. The example configuration uses a 30-minute interval; that value is a configuration example, not a performance or adoption statistic. Set interval = 0 for one notification without repeat reminders, or choose a duration that fits the incident workflow. A nonzero interval can make a working configuration appear silent if you are waiting for a repeat sooner than the configured period.

Recovery notifications are normally sent only to recipients who previously received the related problem notification. Therefore, adding a recipient after a problem was already delivered does not necessarily produce a recovery message for that earlier event.

Step 6: Validate the configuration before reloading

1. Run icinga2 daemon -C on the Icinga server. Fix every syntax, object-reference, and apply-rule error it reports before attempting a reload.
2. Confirm that the recipient object exists, has a valid email, and has enable_notifications = true.
3. Confirm that the host or service actually matches the rule’s assign where expression.
4. Confirm that every user, group, imported template, and notification command name resolves.
5. Confirm that the notification feature is enabled.
6. Inspect the generated object model with the documented icinga2 object list workflow when inheritance or apply-rule matching is unclear. This lets you verify the resulting notification object rather than only the source file.
7. After validation succeeds, reload Icinga using your normal service-management procedure and observe the notification logs while performing a controlled test event.

Why Icinga may not send email

Direct recipient rules versus object-driven routing

Both approaches use the same notification engine. The practical difference is where recipient data and scope are maintained.

Use central rules when the same operations group owns a broad set of checks. Use object variables when ownership differs by host or service, or when a configuration generator already emits those variables. In either model, validate the generated notification object and command path instead of assuming that an imported template applied as expected.

A practical first-alert checklist

• Create one test User with a real mailbox, enable_notifications = true, and broad temporary state and type filters.
• Choose either a host or service test object and write the matching apply rule with the correct to target.
• Assign the test user directly or through a group whose membership you have verified.
• Import the corresponding mail template and confirm that its NotificationCommand exists.
• Verify the notification feature is enabled and that the command is executable by the Icinga service account.
• Run icinga2 daemon -C and resolve all validation errors.
• Inspect the resulting notification object if the rule’s inheritance or assignment is uncertain.
• Perform a controlled problem-and-recovery test, allowing for the configured interval and remembering that recovery normally goes only to recipients who received the problem.
• After delivery is proven, narrow states and types, set the reminder interval, and remove any temporary broad testing policy.

Key boundaries to keep in mind

An email address alone does not create an alert. A user without a matching notification object is never selected; a notification object without a command cannot deliver; and a command without an enabled notification feature is not executed. Likewise, a correctly delivered problem message does not guarantee that every recipient will receive a later recovery message, because recovery follows the original notification relationship.

The most reliable troubleshooting order follows that same chain: validate configuration, prove object matching, prove recipient resolution, prove feature and command execution, and only then investigate the external mail transport. This isolates Icinga configuration errors from delivery-system errors without changing several layers at once.

Quick Recap

Bestseller No. 1

A Beginner’s Guide to Security, Monitoring, Camera Systems, and Surveillance Technology: A Complete Beginner’s Guide to Security, Surveillance, Camera Systems, and Video Monitoring

$11.76

SaleBestseller No. 2

Practical Monitoring: Effective Strategies for the Real World

$13.95

Bestseller No. 3

Electrician''s Guide to Control and Monitoring Systems: Installation, Troubleshooting, and Maintenance

$40.00

SaleBestseller No. 4

The Practice of Network Security Monitoring: Understanding Incident Detection and Response

Used Book in Good Condition

$48.65

SaleBestseller No. 5

Designing Machine Learning Systems: An Iterative Process for Production-Ready Applications

$40.00

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.