How to configure notifications using Nagios

h6. Overview

This page reviews how to configure alert notifications using Nagios. Notification configuration includes defining host and service groups, contacts, contact groups, and escalations.

{section}{column:width=38%}CONTENTS
{toc:minLevel=1|maxLevel=1|printable=false}
{column}{column:width=33%}RELATED RESOURCES
* [About Notifications (Nagios)|About Notifications and Downtime]
{column}
{column}WAS THIS PAGE HELPFUL?

* {html}<a href="mailto:training@gwos.com?subject=How to configure notifications using Nagios">Leave Feedback</a>{html}{column}{section}

{anchor:ConfiguringHostGroupsandServiceGroups}

h1. 1.0 Configuring Host Groups and Service Groups

h6. Defining a Host Group

A *Host Group* definition is used to group one or more hosts together for the purposes of simplifying notifications. When a host goes down, becomes unreachable, or recovers, _Nagios_ will find which host group(s) the host is a member of, get the contact group for each of those host groups, and notify all Contacts associated with those contact groups. Host groups allow for flexibility in determining who gets paged for what kind of problems. Each host that you define must be a member of at least one host group - even if it is the only host in that group. Hosts can be in more than one host group.

# Select Configuration > *Hosts*, expand the *Host Groups* drop-down menu and select *New*.
# In the *Host Group Properties* screen, enter a host group *Name* which should be unique and not the same as a contact group. Enter an *Alias*.
# Next, optionally enter *Notes*. This field is intended to describe common features of the host group (e.g., the business unit, the geographical location,or the team responsible for maintenance). This information is shown on the host group detail page within the _Status_ application.
# Select the *Members* (hosts) from the right side list to be included in this host group, and choose the *Contact Groups* that should be notified whenever there are problems (or recoveries) with any of the hosts in this host group. We will skip the optional host and service escalation ID directives for now.
# Select *Add* to save the new host group.
\\
\\
Figure: Defining a host group
!bookshelf_notifications_how_to_01.jpg|alt="Defining a host group",title="Defining a host group"!

h6. Defining a service group

*Service Groups* allow for flexibility in determining who gets paged for what kind of problems. Service groups allow you to group services together for display purposes in the CGIs and can be referenced in service dependency and service escalation definitions to make configuration a bit easier. This section will take you through the steps to create a new service group. The prerequisites for service groups are defined hosts with services and services assigned to hosts.

# Select Configuration > *Services*, *Service Groups*, and *New*.
# In the *Service Group* screen, enter the properties;
#* *Name* \- \[Required\] Name of the service group. Example: dbservices
#* *Alias* \- \[Required\] This directive is is used to define a longer name or description used to identify the service group. It is provided in order to allow you to more easily identify a particular service group. Example: Database Services
#* *Notes* \- \[Optional\] This filed is intended to describe common features of the service group (e.g., the usage, functions, or specific application software being monitored). This information is shown on the service group detail page within the Status application.
#* *Host/Service* \- \[Required\] This is a list of the descriptions of services (and the names of their corresponding hosts) that should be included in this group.
#* *Service Escalation* \- This is a list of defined service escalations that can be assigned to this service group.
# Click *Add* to go to the *Service Group* screen.
# Select the *Host* drop-down box to select a host. Available services will be listed.
# Choose a service to add and click *Add Service(s)*. The host and service columns above will displayed your selections. To remove a selected service click the *X* corresponding to the line to be deleted.
# Select the *Service* drop-down box to select a service, available hosts will be listed.
# Choose a host to add and click *Add Host(s)*. The host and service columns above will display your selections. To remove a selected host click the X corresponding to the line to be deleted.
# Select *Save* to save the service group. *Delete* removes the current service group, and *Rename* is used to change the name of the current service group. You will be notified on the next screen that the service groups has been updated. After setting up host and/or service groups you're ready to setup notifications and escalations.
\\
\\
Figure: Defining a service group
!bookshelf_notifications_how_to_02.jpg|alt="Defining a service group",title="Defining a service group"!

h1. 2.0 Configuring Contacts and Contact Groups

Next, in our setup of notifications and escalations, we'll work with the *Contact Template* definition directives. A contact template consists of host and service notification time periods, specific host and service notification options (states for which notifications can be sent out), and host and service notification commands used to notify of a host or service problem or recovery. These templates aid in creating contacts by conveniently applying commonly used directives.

After you have completed defining contact templates, continue with *Creating Contacts*. Contact directives consist of contact properties: name, alias, email, pager, and a required contact template. Individual template directives can be selected for the contact definition, or the applied contact template's properties can be inherited.

Next, a *Contact Group* is a grouping of contacts. A contact group's directives consist of name, alias, and the selected contacts. After creating contact groups, you will be ready to associate these groups with host and service templates, hosts, services, and host groups definitions.

# In the *Contact Template Properties* screen, enter a required contact template *Name{*}*.*
# Next, enter the various host and service contact template properties which will be used for all contacts that use this contact template:
*Host notification period* \- \[required\] This directive is used to specify the name of the time period during which the contact can be notified about host problems or recoveries.
*Host notification options* \- \[required\] This directive is used to define the host states for which notifications can be sent out to this contact.
*Host notification commands* \- \[optional\] This directive is used to define a list of names of the commands used to notify the contact of a host problem or recovery. All notification commands are executed when the contact needs to be notified.
*Service notification period* \- \[required\] This directive is used to specify the name of the time period during which the contact can be notified about service problems or recoveries.
*Service notification options* \- \[required\] This directive is used to define the service states for which notifications can be sent out to this contact.
*Service notification commands* \- \[optional\] This directive is used to define a list of names of the commands used to notify the contact of a service problem or recovery. All notification commands are executed when the contact needs to be notified.
# Contact templates also enable you to define and manage optional [custom object variables|http://www.nagios.sourceforge.net/docs/3_0/customobjectvars.html]. This section is used to define macros which are ultimately associated with contacts. These macros may be referenced when you invoke notification commands. Select [http://nagios.sourceforge.net/docs/3_0/customobjectvars.html] for a description of this facility.
# Select *Add* to save the template. You can now use this template when creating new contacts.
\\
\\
Figure: Contact templates

# In the *Contact Properties* screen, if a new contact, enter a contact *Name*, and an *Alias* as a description used to identify the contact. Optionally enter an email address or pager number.
*Name* \- \[required\] This directive is the name used to identify the contact.
*Alias* \- \[required\] This directive is used to define the name or description for the contact. Under the right circumstances, the $CONTACTALIAS$ macro will contain this value.
*Email* \- \[optional\] This directive is used to define an email address for the contact. Depending on how you configure your notification commands, it can be used to send out an alert email to the contact. Under the right circumstances, the $CONTACTEMAIL$ macro will contain this value.
*Pager* \- \[optional\] This directive is used to define a pager number for the contact. It can also be an email address to a pager gateway (e.g., pagejoe@pagenet.com). Depending on how you configure your notification commands, it can be used to send out an alert page to the contact. Under the right circumstances, the $CONTACTPAGER$ macro will contain this value.
# Next, enter a required *Contact Template* most suitable for this contact. By default, many of the selected template directives are checked to be used in the new contact definition. You can uncheck any of the *Inherit* boxes on the left to overide the selected template values. Clicking the *Set Full Inheritance* button will recheck all values and enable the contact definition to inherit all values from the template.
# You can adjust any *custom object variable* values that appear in the controlling contact template, and add new custom object variables that are specific to this one contact. Under the right circumstances, these will appear as special macros that you can refer to in notification command definitions. See the _Nagios_ documentation for details.
# Finally, you may optionally select *Contact Groups* which are used to identify the _name(s)_ of the contact groups that the contact belongs to. This directive may be used _as an alternative to (or in addition to) using the contacts_ directive in the contact groups definition.
# When finished, select *Save*.
\\
\\
Figure: Contacts
!bookshelf_notifications_how_to_04.jpg|alt="Contacts",title="Contacts"!

h6. Creating Contact Groups

# Select Configuration > *Contacts*, *Contact Groups*, and *New* to create a new contact group, or you can copy or modify an existing definition.
# In the *Contact Group Properties* screen, enter a contact group *Name*, and an *Alias* as a description used to identify the contact group.
# Next, using the *Add* and *Remove* buttons, select which contacts are to be part of the contact group.
# When finished with your choices, click *Save*. You can now associate these contact groups with contacts, host and service templates, hosts, services, and host groups definitions. Contact groups can be applied to escalation trees to be used in setting up notifications for hosts and services.
\\
\\
Figure: Contact groups
!bookshelf_notifications_how_to_05.jpg|alt="Contact groups",title="Contact groups"!

{anchor:DefiningEscalationTrees}

h1. 3.0 Defining Escalation Trees

# In the *Escalation Properties* screen, enter an escalation *name*.
# Next, setup the notification options:
*First Notification* \- \[required\] This directive is a number that identifies the first notification for which this escalation is effective. For instance, if you set this value to 3, this escalation will only be used if the host is down or unreachable long enough for a third notification to go out or if the service is in a non-OK state long enough for a third notification to go out.
*Last Notification*. \[required\] This directive is a number that identifies the last notification for which this escalation is effective. For instance, if you set this value to 5, this escalation will not be used if more than five notifications are sent out for the host (or service). Setting this value to 0 means to keep using this escalation entry forever (no matter how many notifications go out).
*Notification Interval* \[required\] Indicates when a notification should be sent. This directive is used to determine the time interval, (unless you've changed the interval_length directive from the default value of 60, this number will mean minutes), at which notifications should be made while this escalation is valid. If you specify a value of 0 for the interval, Nagios will send the first notification only, and will then prevent any more problem notification s from being sent out for the host. Specifying any other value will send continuous notifications at the time interval specified.
{Note}If multiple escalation entries for a host overlap for one or more notification ranges, the smallest notification interval from all escalation entries is used.{Note}
# Continue with the escalation options, you can optionally enter an *Escalation period* which is used to specify the name (e.g., _Work Hours_, _24x7_) of the time period during which this escalation is valid. If this directive is not specified, the escalation is considered to be valid during all times.
# The *Escalation options* directive lets you optionally select the criteria that determines when an escalation is used (e.g., For a host: _Recovery_, _Down_, _Unreachable_; and for a service: _Recovery_, _Warning_, _Unknown_, _Critical_). The escalation is used only if the host (or service) is in one of the states specified in this directive. If this directive is not specified the escalation is considered to be valid during all host (or service) states. Example (host escalation): If you specify _Down_ in this field, the escalation will only be used if the host is in a _DOWN_ state; (service escalation): If you specify warning in this field, the escalation will only be used if the service is in a WARNING state.
# Select *Add* to add the new escalation.
\\
\\
Figure: Escalations
!bookshelf_notifications_how_to_06.jpg|alt="Escalations",title="Escalations"!

h6. Configuring Escalation Trees

Defining a Host or Service Escalation Tree

# Select Configuration > *Escalations*, expand the *Escalation Trees* drop-down menu, expand the *Host (or Service)* drop-down menu, and select *New*.
# Enter a name for the host (or service) escalation tree, and select *Add*, the _Managing Escalations_ screen will be displayed.
\\
\\
Figure: Escalation trees
!bookshelf_notifications_how_to_07.jpg|alt="Escalation trees",title="Escalation trees"!

h6. Add Escalations to an Escalation Tree

Next, in the _Managing Escalations_ screen you can add/remove defined escalations. After selecting each escalation the _Assign Contact Groups_ screen will be displayed where you can assign contact groups to be associated with the escalation. These are groups of contacts that will be notified when the host or service notification is escalated.

You can build up a number of escalations to accomplish elaborate notification schemes. For example, a _Technical_ contact group could be assigned an escalation that sends out the first through the last notifications. Whereas a different escalation might start with the 5th notification and end with the 6th notification and go to a _Senior Manager_ that might want to be notified only when a alarm hasn't been acknowledged within the 4 previous notifications.
# Select a defined escalation from the right side to add to the _Escalation Tree_ then click *Add Escalation*.
# Next, add all contact groups to be associated with the escalation and select *Assign Contact Groups*.
# You will still be in the _Detail_ tab, here you can add additional escalations or modify contact groups. Next we'll assign host groups to set the default host escalation.
\\
\\
Figure: Escalation trees
!bookshelf_notifications_how_to_08.jpg|alt="Escalation trees",title="Escalation trees"!

h6. Assigning Host Groups

Now you can optionally assign host groups which will set the default host escalation for all hosts in a host group. You also have the option to set a host escalation for an individual host.

# Select the *Assign Host Groups* tab, and the host groups to assign to the escalation tree.
# Select *Save* and *Close*.
\\
\\
Figure: Assigning host groups to an escalation tree
!bookshelf_notifications_how_to_09.jpg|alt="Assigning host groups to an escalation tree",title="Assigning host groups to an escalation tree"!

h6. Applying Escalation Trees

When creating or modifying an *Escalation Tree* you have the option to assign host groups which sets the default host escalation for all hosts in the host group. And you can assign hosts which sets the host escalation for the host. Additionally, you can add an escalation tree to defined host groups and hosts.

Apply an escalation tree to a host

# Go to *Configuration* > *Hosts*, *Hosts*, and choose a *Host Group* for the host you want to edit and then select the host.
# Select *Detail*. The _Manage Host_ screen will be displayed.
# Select the *Escalation Trees* tab, and an *Escalation Tree* from the drop-down box appropriate for this host.
{Note}To avoid amplified notifications (i.e. multiple notifications for the same event), a host escalation assigned to this host should not also be assigned to a host group in which the host is a member.{Note}
# Choose an *Escalation Tree* from the drop-down box appropriate for all services on this host.
{Note}When a service escalation is assigned here, all services on this host will use the same escalation. To use different escalations for different services, each service must have its own escalation. In that case do not assign a service escalation at this point. {Note}
# Select *Save*.
\\
\\
Figure: Applying an escalation tree to a host
!bookshelf_notifications_how_to_10.jpg|alt="Applying an escalation tree to a host",title="Applying an escalation tree to a host"!

h6. Apply an Escalation Tree to a Host Group

# Go to Configuration >Select *Hosts* and *Host Groups*.
# Click *Modify* to get a listing of defined host groups, and select a *Host Group*. The _Host Properties_ screen will be displayed.
# Next, select a *Host Escalation Tree* from the drop-down box applicable to the host group.
{Note}All hosts in the host group will receive the same host escalation.{Note}
# Select a *Service Escalation Tree* from the drop-down box applicable to this host group
{Note}All services on each host in the host group receive the same host escalation.{Note}
# Click *Save*.
\\
\\
Figure: Apply an escalation tree to a host group
!bookshelf_notifications_how_to_11.jpg|alt="Apply an escalation tree to a host group",title="Apply an escalation tree to a host group"!

h1. 4.0 Enabling and Receiving Notifications

Notifications in _GroundWork Monitor_ are set to *{_}OFF{_}* system-wide by default. This means that host and service notifications will not be sent out. After enabling notifications, host and service notifications will be sent to any valid system contacts. In addition to the system-wide default setting for notifications, the _Enable Notifications_ option can be set for all hosts and services assigned to a specific template by setting this option in a host or service template. Also, the _Enable Notifications_ option can be set for individual host or service definitions by changing the definitions template inheritance. Below, we outline how to enable notifications. For additional information on notifications select [http://nagios.sourceforge.net/docs/3_0/notifications.html]. After enabling notifications, continue setting up system notifications and escalations by clicking the home icon at the top of this page and referring to links under _Setting up Host and Service Notifications_.

h6. Enable system wide notifications

# Select *Configuration* > *Control*, and the *Nagios Main Configuration* option.
# About half way down the page, select the box next to *Enable Notifications* to enter a check which indicates notifications are on. At the bottom of the page, click *Save and Next* to save this change. You'll need to commit this change to your _Nagios_ configuration, select *Control* again.
# Select *Backup* if necessary, and then *Commit* to overwrite the active _Nagios_ configuration and restart _Nagios_.
\\
\\
Figure: Enable notifications
!bookshelf_notifications_how_to_12.jpg|alt="Enable notifications",title="Enable notifications"!