granicus.if.org Git - icinga2/blob - doc/3.04-notifications.md

   1 ## <a id="notifications"></a> Notifications
   2
   3 Notifications for service and host problems are an integral part of your
   4 monitoring setup.
   5
   6 There are many ways of sending notifications, e.g. by e-mail, XMPP,
   7 IRC, Twitter, etc. On its own Icinga 2 does not know how to send notifications.
   8 Instead it relies on external mechanisms such as shell scripts to notify users.
   9
  10 A notification specification requires one or more users (and/or user groups)
  11 who will be notified in case of problems. These users must have all custom
  12 attributes defined which will be used in the `NotificationCommand` on execution.
  13
  14 TODO
  15
  16 The user `icingaadmin` in the example below will get notified only on `WARNING` and
  17 `CRITICAL` states and `problem` and `recovery` notification types.
  18
  19     object User "icingaadmin" {
  20       display_name = "Icinga 2 Admin"
  21       enable_notifications = 1
  22       notification_state_filter = [ OK, Warning, Critical ]
  23       notification_type_filter = [ Problem, Recovery ]
  24       vars.email = "icinga@localhost"
  25       vars.pager = "+49123456789"
  26       }
  27     }
  28
  29 If you don't set the `notification_state_filter` and `notification_type_filter`
  30 configuration attributes for the `User` object, all states and types will be
  31 notified.
  32
  33 You should choose which information you (and your notified users) are interested in
  34 case of emergency, and also which information does not provide any value to you and
  35 your environment.
  36
  37 There are various custom attributes available at runtime execution of the
  38 `NotificationCommand`. The example below may or may not fit your needs.
  39
  40     object NotificationCommand "mail-service-notification" {
  41       import "plugin-notification-command"
  42
  43       command = [ SysconfDir + "/icinga2/scripts/mail-notification.sh" ]
  44
  45       env = {
  46         "NOTIFICATIONTYPE" = "$notification.type$"
  47         "SERVICEDESC" = "$service.description$"
  48         "HOSTALIAS" = "$host.displayname$",
  49         "HOSTADDRESS" = "$host.vars.address$",
  50         "SERVICESTATE" = "$service.state$",
  51         "LONGDATETIME" = "$icinga.longdatetime$",
  52         "SERVICEOUTPUT" = "$service.output$",
  53         "NOTIFICATIONAUTHORNAME" = "$notification.author$",
  54         "NOTIFICATIONCOMMENT" = "$notification.comment$",
  55         "HOSTDISPLAYNAME" = "$host.displayname$",
  56         "SERVICEDISPLAYNAME" = "$service.displayname$",
  57         "USEREMAIL" = "$user.vars.email$"
  58       }
  59     }
  60
  61 The command attribute in the `mail-service-notification` command refers to the
  62 shell script installed into `/etc/icinga2/scripts/mail-notification.sh`.
  63 The macros specified in the `env` dictionary are exported as environment
  64 variables and can be used in the notification script.
  65
  66 You can add all shared attributes to a `Notification` template which is inherited
  67 to the defined notifications. That way you'll save duplicated attributes in each
  68 `Notification` object. Attributes can be overridden locally.
  69
  70 TODO
  71
  72     template Notification "generic-notification" {
  73       notification_interval = 15m
  74
  75       notification_command = "mail-service-notification"
  76
  77       notification_state_filter = [ Warning, Critical, Unknown ]
  78       notification_type_filter = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
  79                                    FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ]
  80
  81       notification_period = "24x7"
  82     }
  83
  84 The time period `24x7` is shipped as example configuration with Icinga 2.
  85
  86 Use the `apply` keyword to create `Notification` objects for your services:
  87
  88     apply Notification "mail" to Service {
  89       import "generic-notification"
  90
  91       notification_command = "mail-notification"
  92       users = [ "icingaadmin" ]
  93
  94       assign where service.name == "mysql"
  95     }
  96
  97 Instead of assigning users to notifications, you can also add the `user_groups`
  98 attribute with a list of user groups to the `Notification` object. Icinga 2 will
  99 resolve all group members and send notifications to all of them.
 100
 101 ### <a id="notification-escalations"></a> Notification Escalations
 102
 103 When a problem notification is sent and a problem still exists after re-notification
 104 you may want to escalate the problem to the next support level. A different approach
 105 is to configure the default notification by email, and escalate the problem via sms
 106 if not already solved.
 107
 108 You can define notification start and end times as additional configuration
 109 attributes making the `Notification` object a so-called `notification escalation`.
 110 Using templates you can share the basic notification attributes such as users or the
 111 `notification_interval` (and override them for the escalation then).
 112
 113 Using the example from above, you can define additional users being escalated for sms
 114 notifications between start and end time.
 115
 116     object User "icinga-oncall-2nd-level" {
 117       display_name = "Icinga 2nd Level"
 118       enable_notifications = true
 119
 120       vars.mobile = "+1 555 424642"
 121     }
 122
 123     object User "icinga-oncall-1st-level" {
 124       display_name = "Icinga 1st Level"
 125       enable_notifications = true
 126
 127       vars.mobile = "+1 555 424642"
 128       }
 129     }
 130
 131 Define an additional `NotificationCommand` for SMS notifications.
 132
 133 > **Note**
 134 >
 135 > The example is not complete as there are many different SMS providers.
 136 > Please note that sending SMS notifications will require an SMS provider
 137 > or local hardware with a sim card active.
 138
 139     object NotificationCommand "sms-notification" {
 140        command = PluginDir + "/send_sms_notification $mobile$ ..."
 141     }
 142
 143 The two new notification escalations are added onto the host `localhost`
 144 and its service `ping4` using the `generic-notification` template.
 145 The user `icinga-oncall-2nd-level` will get notified by SMS (`sms-notification`
 146 command) after `30m` until `1h`.
 147
 148 > **Note**
 149 >
 150 > The `notification_interval` was set to 15m in the `generic-notification`
 151 > template example. Lower that value in your escalations by using a secondary
 152 > template or overriding the attribute directly in the `notifications` array
 153 > position for `escalation-sms-2nd-level`.
 154
 155 If the problem does not get resolved or acknowledged preventing further notifications
 156 the `escalation-sms-1st-level` user will be escalated `1h` after the initial problem was
 157 notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
 158
 159     apply Notification "mail" to Service {
 160       import "generic-notification"
 161       notification_command = "mail-notification"
 162       users = [ "icingaadmin" ]
 163
 164       assign where service.name == "ping4"
 165     }
 166
 167     apply Notification "escalation-sms-2nd-level" to Service {
 168       import "generic-notification"
 169       notification_command = "sms-notification"
 170       users = [ "icinga-oncall-2nd-level" ]
 171
 172       times = {
 173         begin = 30m
 174         end = 1h
 175       }
 176
 177       assign where service.name == "ping4"
 178     }
 179
 180     apply Notification "escalation-sms-1st-level" to Service {
 181       import "generic-notification"
 182       notification_command = "sms-notification"
 183       users = [ "icinga-oncall-1st-level" ]
 184
 185       times = {
 186         begin = 1h
 187         end = 2h
 188       }
 189
 190       assign where service.name == "ping4"
 191     }
 192
 193 Instead of assigning users to notifications, you can also add the `user_groups`
 194 attribute with a list of user groups to the `Notification` object. Icinga 2 will
 195 resolve all group members and send notifications and notification escalations to
 196 all of them.
 197
 198 ### <a id="first-notification-delay"></a> First Notification Delay
 199
 200 Sometimes the problem in question should not be notified when the first notification
 201 happens, but a defined time duration afterwards. In Icinga 2 you can use the `times`
 202 dictionary and set `begin = 15m` as key and value if you want to suppress notifications
 203 in the first 15 minutes. Leave out the `end` key - if not set, Icinga 2 will not check against any
 204 end time for this notification.
 205
 206     apply Notification "mail" to Service {
 207       import "generic-notification"
 208       notification_command = "mail-notification"
 209       users = [ "icingaadmin" ]
 210
 211       times.begin = 15m // delay first notification
 212
 213       assign where service.name == "ping4"
 214     }
 215
 216 ### <a id="notification-filters-state-type"></a> Notification Filters by State and Type
 217
 218 If there are no notification state and type filter attributes defined at the `Notification`
 219 or `User` object Icinga 2 assumes that all states and types are being notified.
 220
 221 Available state and type filters for notifications are:
 222
 223     template Notification "generic-notification" {
 224
 225       notification_state_filter = [ Warning, Critical, Unknown ]
 226       notification_type_filter = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
 227                                    FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
 228     }
 229
 230 If you are familiar with Icinga 1.x `notification_options` please note that they have been split
 231 into type and state, and allow more fine granular filtering for example on downtimes and flapping.
 232 You can filter for acknowledgements and custom notifications too.