Creating a new e-mail contact

In this recipe, we'll create a new contact with which hosts and services can interact, chiefly to inform them of hosts or services changing states. We'll use the simplest example of setting up an e-mail contact, and configuring an existing host so that this person receives an e-mail message when Nagios Core's host checks fail and the host is apparently unreachable. In this instance, I'll make it e-mail me at [e-mail] whenever my host, sparta.naginet, goes from DOWN to UP state, or vice-versa.

Getting ready

You should have a working Nagios Core 3.0 or greater server running, with a web interface and at least one host to check. If you need to do this first, see the Creating a new network host recipe in this chapter.

For this particular kind of contact, you'll also need to have a working SMTP daemon running on the monitoring server, such as Exim or Postfix. You should verify that you're able to send messages to the target address, and that they're successfully delivered to the mailserver you expect.

How to do it...

We can add a simple new contact to the Nagios Core configuration as follows:

1. Change to Nagios Core's object configuration directory; ideally it should contain a file that's devoted to contacts, such as contacts.cfg here, and edit that file:

   # cd /usr/local/nagios/etc/objects
   # vi contacts.cfg
   

2. Add the following contact definition to the end of the file, substituting your own values for the properties in bold as you need them:

   define contact {
       contact_name                   spartaadmin
       alias                          Administrator of sparta.naginet
       email                          [e-mail]
       host_notification_commands     notify-host-by-email
       host_notification_options      d,u,r
       host_notification_period       24x7
       service_notification_commands  notify-service-by-email
       service_notification_options   w,u,c,r
       service_notification_period    24x7
   }

3. Edit the definition for the sparta.naginet host, and add or replace the definition for contacts for the appropriate host to our new spartaadmin contact:

   define host {
       host_name              sparta.naginet
       alias                  sparta
       address                10.128.0.21
       max_check_attempts     3
       check_period           24x7
       check_command          check-host-alive
       contacts               spartaadmin
       notification_interval  60
       notification_period    24x7
   }

4. Restart the Nagios Core server:

   # /etc/init.d/nagios restart
   

With this done, the next time our host changes its state, we should receive messages similar to the following:

When the host becomes available again, we should receive a recovery message similar to the following:

If possible, it's worth testing this setup with a test host that we can safely bring down and then up again, to check that we receive the appropriate notifications.

How it works...

This configuration adds a new contact to the Nagios Core configuration, and references it in one of the hosts as the appropriate contact to use when the host has problems.

We've defined the required directives for the contact, and a couple of others as follows:

• contact_name : This defines a unique name for the contact, so that we can refer to it in host and service definitions, or anywhere else in the Nagios Core configuration.

• alias : This defines a human-friendly name for the contact, perhaps a brief explanation of who the person or group is and/or for what they're responsible.

• email : This defines the e-mail address of the contact, since we're going to be sending messages by e-mail.

• host_notification_commands : This defines the command or commands to be run when a state change on a host prompts a notification for the contact. In this case, we're going to e-mail the contact the results with a predefined command called notify-host-by-email.

• host_notification_options : This specifies the different kinds of host events for which this contact should be notified. Here, we're using d,u,r, which means that this contact will receive notifications for a host going DOWN, becoming UNREACHABLE, or coming back UP.

• host_notification_period : This defines the time period during which this contact can be notified of any host events. If a host notification is generated and defined to be sent to this contact, but it falls outside this time period, then the notification will not be sent.

• service_notification_commands : This defines the command or commands to be run when a state change on a service prompts a notification for this contact. In this case, we're going to e-mail the contact the results with a predefined command called notify-service-by-email.

• service_notification_options : This specifies the different kinds of service events for which this contact should be notified. Here, we're using w,u,c,r, which means we want to receive notifications about the services entering the WARNING, UNKNOWN, or CRITICAL states, and also when they recover and go back to being in the OK state.

• service_notification_period : This is the same as host_notification_period, except that this directive refers to notifications about services, and not hosts.

Note that we placed the definition for the contact in contacts.cfg, which is a reasonably sensible place. However, we can place the contact definition in any file that Nagios Core will read as part of its configuration; we can organize our hosts, services, and contacts any way we like. It helps to choose some sort of system, so we can easily identify where definitions are likely to be when we need to add, change, or remove them.

There's more...

If we define a lot of contacts with similar options, it may be appropriate to have individual contacts extend contact templates, so that they can inherit those common settings. The QuickStart Nagios Core configuration includes such a template, called generic-contact. We can define our new contact as an extension of this template, as follows:

define contact {
    use    generic-contact
    alias  Administrator of sparta.naginet
    email  [e-mail]
}

To see the directives defined for generic-contact, you can inspect its definition in the /usr/local/nagios/etc/objects/templates.cfg file.

See also

• The Creating a new contact group recipe in this chapter

• The Automating contact rotation and Defining an escalation for repeated notifications recipes in Chapter 5, Monitoring Methods