Tutorial Notifications

From OpenNMS
Jump to: navigation, search

Introduction

OpenNMS has a very powerful notification system, capable of posting interesting events as email, SMS, SNMP traps, or just about anything else you can think of.

Create a User

While it is of course possible to send notifications to the default ("admin") user, the first thing you should do is create a user for yourself.

You can do so by clicking the "Admin" link in the menu bar, going to "Configure Users, Groups and On-Call Roles", and then clicking "Configure Users".

Then, click the "Add New User" link, and enter a username and password in the form, then click "OK". Next, fill out the relevant user information.

Finally, click "Finish" down at the bottom of the form.

Note.png Try It! Create a New User

Create a user for yourself. In this example, we will use the username "tutorial," but feel free to use a name that is more appropriate for yourself.

Click through to the Configure Users page, click "Add New User", enter your chosen username and password in the form, and click "OK".

After you click OK, fill out any user information you might feel relevant. Make sure you add at least an e-mail address, because that's what this tutorial will use.

When you're finished, click "Finish" at the bottom of the form. You should see your new user in the list:

User Added

Destination Paths

To receive a notification, your user or a group that your user is in needs to be a part of a destination path. A destination path helps OpenNMS determine who is eligible to receive a particular notification, depending on user name, groups, duty schedules, and other rules.

When an event is received that should be notified on, OpenNMS "walks" the destination path for that notification (or notifications). We say that the destination path is "walked" because it is often a series of actions performed over time and not necessarily just a single action (although it can be). The destination path continues to be walked until all notifications and escalations have been sent or the notification is acknowledged (automatically or by manual intervention).

A destination has an initial delay (how long to wait before sending notifications), 1 or more targets (users, groups, on-call roles, or email addresses), and then 0 or more escalations.

Note.png Try It! Create a Destination Path

Let's try creating a destination path for your new user. Go to the Admin page, click "Configure Notifications" in the "Operations" section, then "Configure Destination Paths," then click the "New Path" button.

Give it a name, like "Tutorial", then click "Edit". Add your new user by selecting it, then click "Next >>>":

Initial Target

On the next page, leave the defaults ("javaEmail" and "on") and click "Next >>>" again.

Finally, click "Finish" and you should see your new tutorial path in the "Existing Paths" section.

Event Notifications

Right now, your destination path doesn't have any events associated with it, so it won't do anything yet. The next thing we'll do is create an event notification, which ties any OpenNMS event together with a destination path.

Go to the Admin page, click "Configure Notifications" in the "Operations" section, then "Configure Event Notifications." In here you 'll see a list of events which are configured for notifications, some of which are turned off. You can create a new event notification by clicking the "Add New Event Notification" button near the top.

It will ask you for the event to notify on, followed by asking you to optionally "build" a rule. The "Build Rule" UI lets you match a subset of IP addresses or services. Finally, it will ask you to fill out information that should go into the notification, including the destination path, a subject if it's an email message, the text, a "short" message (used in SMS or XMPP notifications, for example), and some other parameters.

Note.png Try It! Creating an Event Notification

Click the "Add New Event Notification" button at the top of the Event Notifications page. Next you'll see a gigantic list of possible events. Scroll about 3/4 of the way down in that box, and look for "OpenNMS-defined internal event: an authentication failure has occurred in WebUI":

Add Event Notification

Then click "Next >>>".

On the next page, you can build a rule for matching a set of IP addresses and/or services. In this case, we're just matching an internal OpenNMS event, so we'll continue on and click "Skip results validation >>>".

Finally, you can configure the information used to send the notification. Fill in the following values:

  • Name: authenticationFailed
  • Choose A Path: Tutorial
  • Text Message: The OpenNMS Web UI had a failed login attempt, by user '%parm[user]%', from IP address %parm[ip]% (Exception message: %parm[exceptionMessage]%)
  • Short Message: Authentication failed by user %parm[user]% (Notice #%noticeid%)
  • Email Subject: Authentication Failed (Notice #%noticeid%)

...and then click "Finish".

You should now see your notification event in the list, but it will be disabled. Set the radio button to "On" to enable it, and you should be ready to send a notification:

Enable Event Notification

Hint: UEI Filter

You can use Regex UEI filter in notifications to use one notification for several events.

Unfortunately you can't use the WebUI for this configuration. You need to edit your notification in /etc/opennms/notifications.xml.

Examples:

<uei>~uei.opennms.org/custom/event.*</uei>
<uei>~uei.opennms.org/.*/event</uei>
<uei>~uei.opennms.org/custom/event[0-9]+</uei>
<uei>~uei.opennms.org/custom/event\d+</uei>

Configure Mail

Unless you have an SMTP server running on your OpenNMS host, you will need to configure mail before notifications will work. Mail configuration for notifications is in the "$OPENNMS_HOME/etc/javamail-configuration.properties" file. In most cases, you should only have to change a few lines to point it at your mail server:

 # This is the e-mail address that OpenNMS puts in the "From" field:
 org.opennms.core.utils.fromAddress=FROM-EMAIL-ADDRESS
 org.opennms.core.utils.mailHost=MAIL-SERVER-IP

Also, if your mail server requires authentication for sending, see the section under "These properties define the Mail authentication." and edit them as appropriate for your environment.

Enable Notifications

By default, OpenNMS ships with notifications disabled, so you don't get them accidentally as you're just setting things up. The last thing you need to do once you have things configured as you like is to enable notifications.

In the main OpenNMS Admin page, there is a radio selector labeled, "Notification Status." Change it to "On" and click update.

Enable Notifications

Note.png Try It! Trigger a Notification

Now let's trigger your notification. Log out of the OpenNMS Web UI (by clicking "Log out" in the upper-right corner), and then try logging in again, but give the wrong password.

You should receive an email telling you about the authentication failure. If you don't, take a look at "$OPENNMS_HOME/logs/daemon/notifd.log" and see if you get any error messages.

Moving On to Automating Discovery

That's it!



Next-arrow.png Next Step: Discovering Devices Automatically

Now that we've configured some basic notifications, let's automate discovering new devices.