How to Enable Email Alerts in Icinga 2

To enable email alerts in Icinga 2, configure all three parts of the notification chain: a recipient User (or UserGroup) with a valid email address, a host or service Notification apply rule, and a NotificationCommand or external script that can deliver mail. Then validate the configuration with icinga2 daemon -C and test each layer separately.

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

How Icinga 2 email notifications fit together

Icinga 2 does not deliver email on its own. A check changes state, the notification rules decide whether that event should produce an alert, and a notification command hands the message to an external delivery mechanism such as a local mail transfer agent or an SMTP relay. If any link is missing, the check can still appear correctly in Icinga while no email is sent.

#	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.

The complete path is:

1. A host or service enters an eligible state, such as Critical or Warning.
2. A Notification object applies to that host or service.
3. The notification resolves one or more users or user groups.
4. The selected user accepts that state and notification type.
5. The notification invokes a NotificationCommand.
6. The command or script passes the message to your mail transport.

Icinga’s documentation describes notifications as an integral part of the monitoring stack, but also notes that Icinga 2 “on its own” does not know how to send notifications. Treat mail delivery as an integration you must configure and operate separately from monitoring.

Prerequisites before you edit notification rules

• A working Icinga 2 installation that can evaluate host and service checks.
• Permission to edit the configuration objects and deploy a reload through your normal Icinga process.
• A real mailbox for production testing. The example address icinga@localhost is suitable only for a local test environment.
• An available mail transport: for example, a local MTA or an authenticated SMTP relay that your notification script can use.
• A notification feature that is enabled. Notification commands are not executed when that feature is disabled.
• A delivery command or script readable and executable by the operating-system account running Icinga.

Decide first whether recipients belong centrally in User objects or should be selected by host and service data. Central user objects are easier to audit when the same people receive many alerts. Variables on a host or service are useful when routing is generated by another configuration system or differs for every monitored object.

#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 with notifications enabled and an email address. This is the smallest complete example from the official configuration pattern:

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

Replace the address with a mailbox that you can actually receive. Keep the address in the user object or in another controlled configuration source; an address that exists only in a comment or an unrelated variable is not a notification destination.

What each User property controls

If states and types are omitted, Icinga assumes all states and notification types are eligible. Explicit lists are safer for a busy installation because they make the intended alert policy visible, but they can also explain why a test event produces no message.

Step 2: Organize recipients with a UserGroup

A UserGroup lets one notification address a team rather than listing individual users repeatedly. A service notification can assign a group such as noc:

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

Every user in the group still needs its own enabled notification setting and valid email address. A group name that does not resolve to a defined group will not produce a recipient merely because the spelling looks correct.

Step 3: Apply a mail notification to services and hosts

Host and service notifications are different object types. The target in the apply rule determines which checks the rule can match, and the imported mail template must correspond to that target.

Rank #2

Sale

Practical Monitoring: Effective Strategies for the Real World

$13.95

Buy on Amazon

Service alerts

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

This rule applies to services whose host has the custom variable notification.mail. Your policy can use a more specific assign where expression, but it must evaluate true for the service being tested.

Host alerts

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

Use the host template for a host rule and the service template for a service rule. A service rule does not automatically create host notifications, and a host rule does not replace service notifications.

Step 4: Route recipients with notification.mail variables

Instead of hard-coding recipients in every notification rule, attach them to the monitored object. The documented nested variable format is:

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

The notification apply rule can read the groups and users members and pass them to the notification template. This approach is useful when an inventory or provisioning system generates host and service configuration, because the routing decision travels with the object.

Direct recipients versus variable-driven recipients

Do not mix the two patterns accidentally. If a template expects users from notification.mail but the rule supplies only a fixed group, the generated notification may not reach the intended team. Keep one clearly documented source of truth for each rule.

Step 5: Provide a NotificationCommand and mail transport

Icinga 2 invokes a NotificationCommand; it does not become an SMTP client merely because a user has an email address. A fresh installation includes example host and service email scripts. Use those scripts as starting points, then adapt the sender address, transport, authentication, headers, and message formatting to your environment.

Rank #3

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

$40.00

Buy on Amazon

What the command must accomplish

• Accept the notification arguments supplied by the imported host or service template.
• Construct a message with a recipient, sender, subject, and body.
• Hand that message to a reachable local mail service or SMTP relay.
• Return a useful exit status so command failures appear in Icinga logs.

Do not assume that a script executable from your shell is executable by Icinga. The command runs as the Icinga service account, which needs execute permission on the script and read or execute permission on any interpreter, helper, certificate, or configuration file the script uses. If the script invokes a local mail binary, that binary must also be available in the service account’s execution environment.

Transport choices and their trade-offs

The official examples establish the command-and-script model but do not prescribe a particular SMTP provider. Select a transport that meets your organization’s authentication, retention, and delivery requirements.

Step 6: Choose states, event types, and reminder intervals

Notification filters decide which state changes are eligible. Common states include Warning, Critical, and Unknown. Common types include Problem, Acknowledgement, Recovery, and downtime-related events. A template or user without filters is treated as eligible for all states and types.

object User "oncall" {
  display_name = "On-call team"
  enable_notifications = true
  states = [ Warning, Critical, Unknown ]
  types = [ Problem, Acknowledgement, Recovery ]
  email = "[email protected]"
}

The address above is an example format; use a real, controlled mailbox in your configuration. The important policy choices are the state and type lists, not the example domain.

How interval affects repeated alerts

The interval controls how often Icinga repeats a notification while the underlying problem remains active. The example configuration uses a 30-minute interval. Set interval = 0 when you want one notification without re-notifications, or choose a duration that matches your incident process.

An interval does not create the first alert; it governs repeats after an eligible notification has already been sent. A long interval can make a working configuration appear silent during a test if a previous notification is still within its suppression window. Recovery notifications are normally sent only to recipients who previously received the related problem notification.

Rank #4

Sale

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

• Used Book in Good Condition

$48.65

Buy on Amazon

Use filters deliberately

• Include Problem when testing that a failure generates an initial message.
• Include Recovery if operators must be told when the check returns to normal.
• Include Acknowledgement or downtime types only when those workflow events belong in email.
• Check that the state under test is listed for both the user and the notification template.
• Temporarily use a narrow, obvious test policy rather than changing production-wide filters while diagnosing delivery.

Step 7: Validate the configuration before testing delivery

Run the configuration checker after every meaningful edit:

icinga2 daemon -C

Fix every syntax, object-name, import, and apply-rule error before investigating SMTP. A successful check means the configuration can be parsed and compiled; it does not prove that a script can connect to a relay or that a mailbox accepted a message.

After validation, deploy the configuration through your normal Icinga reload procedure. Confirm that the notification feature is enabled, because a valid command is still not executed when that feature is disabled. If you need to confirm what Icinga generated, inspect the compiled object model with the documented icinga2 object list workflow and verify that the expected host or service notification exists.

A safe test sequence

1. Validate with icinga2 daemon -C.
2. Confirm the target object has the expected notification.mail data, if you use variable-driven routing.
3. Confirm the notification object is generated for the correct host or service type.
4. Check that the recipient user is enabled and has a real email address.
5. Check the selected state, event type, and interval.
6. Run the delivery command using the Icinga service account in a controlled test, using the actual script and transport configuration rather than your personal shell environment.
7. Trigger or observe a test event and follow the Icinga and mail-transport logs from notification creation through delivery.

Why Icinga is not sending email: a diagnostic path

1. Configuration validation fails

Start with icinga2 daemon -C. An undefined user, group, template, import, variable, or malformed apply rule prevents the intended object model from being deployed. Correct the first reported error, run the check again, and continue until validation succeeds.

2. No Notification object was generated

Inspect the generated objects and compare the rule with the target. For a service rule, verify that the rule uses to Service and that its assign where expression matches the service’s host variables. For a host rule, verify to Host and the host-level variable expression. A rule that parses successfully but evaluates false simply does not create a notification for that object.

3. The recipient is filtered out

Check enable_notifications, email, states, and types on every intended user. A user who is enabled but excludes the tested state or event type will not receive the message. If you use a group, verify that it resolves to users who individually pass these checks.

Best Value

Sale

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

$40.00

Buy on Amazon

4. The notification command is absent or disabled

Verify that the imported mail template exists and ultimately references a NotificationCommand. Confirm that the notification feature is enabled. Icinga’s documentation specifically calls out feature enablement as a prerequisite for executing notification commands.

5. The command cannot execute as the Icinga account

Inspect the script’s execute bit, its interpreter, referenced files, and environment. A command that works when run as root or as your login user can fail under Icinga because of permissions, a different PATH, a missing certificate, or a protected credential file. Make the smallest permission change necessary; do not give the monitoring account broad administrative access simply to make mail work.

6. The command runs but transport rejects the message

At this stage, troubleshoot the external mail mechanism: relay hostname resolution, network egress, port access, TLS negotiation, authentication, sender policy, recipient rejection, and queue status. Icinga cannot correct a relay refusal. Use the transport’s logs and delivery status to distinguish a hand-off failure from a downstream mailbox problem.

7. A repeat notification is being suppressed

Check interval and the notification history. A nonzero interval intentionally suppresses repeats until the configured period elapses. A recovery is also tied to the original problem notification, so a person who did not receive the problem may not receive its recovery.

Operational practices for reliable alert mail

Keep notification policy separate from delivery credentials

User objects and apply rules describe who should be alerted and for which events. SMTP credentials, relay certificates, and transport-specific settings belong in the delivery mechanism with permissions that prevent ordinary configuration readers from obtaining them.

Make sender identity and routing explicit

Choose a sender address accepted by your relay and recognizable to operators. If different environments use different relays, keep those differences in the command or deployment layer rather than duplicating notification policy for every host.

Prevent alert storms without hiding incidents

Use state and type filters to remove events that do not belong in email, and use interval for controlled reminders. Do not set the interval to zero as a blanket fix for missing alerts; zero disables repeats but does not repair a recipient, rule, command, or transport problem.

Test both failure and recovery

An initial problem proves that the problem path works. A separate recovery test confirms that recovery is included in the type filters and that Icinga associates the recovery with recipients who received the problem. If acknowledgements or downtime notices matter operationally, test those event types as well.

Complete configuration checklist

• The recipient is a defined User or member of a defined UserGroup.
• enable_notifications = true is set for the recipient.
• The recipient has a valid production email address.
• The notification apply rule targets the correct object type: Host or Service.
• The assign where expression matches the intended object.
• Any notification.mail variable contains the intended users and groups.
• The imported mail template or explicit NotificationCommand exists.
• The notification feature is enabled.
• The delivery script is executable by the Icinga service account.
• The state and type filters include the event being tested.
• The interval is not suppressing a repeat you expect immediately.
• icinga2 daemon -C completes successfully.
• The external mail transport accepts the message and provides delivery or rejection logs.

The practical answer

Email alerts work when Icinga can resolve an enabled recipient, generate a matching host or service notification, and execute an external mail command successfully. Configure those layers in that order, validate the object model, then troubleshoot execution and transport separately. This approach distinguishes an Icinga rule problem from a script-permission problem and from an SMTP delivery problem, so each failure has a specific place to fix.

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.