OpenNMS User Guide

A Guide for New Users

Steve Giles

Tarus Balog

Table of Contents

1. Chapter 1
1.1. This guide
1.2. Terms used in this document
2. Chapter 2
2.1. Outage table
2.2. Availability
2.3. Performance and Notification
3. Chapter 3
3.1. Viewing Events
3.2. Managing Events
4. Chapter 4
5. Chapter 5
5.1. Searching for Nodes
5.2. Searching Asset Information
6. Chapter 6
6.1. Performance Reports
6.2. Custom Performance Reports
6.3. Availability Reports
7. Chapter 7
7.1. Turning Notifications on
7.2. Check and Acknowledge Notifications
7.3. Managing Notifications
8. Chapter 8
8.1. Adding Asset information
8.2. Search Nodes based on Asset Information
8.3. Exporting Asset Information
8.4. Importing Asset Information
9. Chapter 9
9.1. Documentation
9.2. Web Site
9.3. Email
9.4. Usenet News


OpenNMS is the creation of numerous people and organizations, operating under the umbrella of the OpenNMS project. The original code base was developed and published under the GPL by the Oculan Corporation until 2002, when the project administration was passed on to Tarus Balog.

The current corporate sponsor of OpenNMS is The OpenNMS Group, which also owns the OpenNMS trademark.

OpenNMS is a derivative work, containing both original code, included code and modified code that was published under the GNU General Public License. Please see the source for detailed copyright notices, but some notable copyright owners are listed below:

Please send any omissions or corrections to this document to Tarus Balog.

Chapter 1. Chapter 1

OpenNMS Basics

Warning: This document is deprecated and refers to old code. A new document is being developed, but for now the best source of information can be found on The OpenNMS Wiki. This document may be wrong on a number of important issues, and it will definitely waste your time.

OpenNMS is a service and network management platform for automatic node discovery, network services monitoring, operator notification of problems, events consolidation, automatic action launching and service level performance monitoring.

This guide

This guide covers the use of the web UI on an already configured management station. It covers, finding information, recognizing and acknowledging events and notices, as well as reporting features, and asset management. This guide is intended for end users to be able to understand the current state of the managed network, as well as research historical data, and make the most of all the information available through the web interface.

Terms used in this document

The following is a list of terms relevant to this document. Some of these terms are used rather loosely within the industry, but are defined here as they specifically apply to OpenNMS.

Interface. Any logical IP address bound to a device that responds to network requests, OR, anything reported via SNMP as being an interface.

Service. Any single, predefined network service that is bound to an interface.

Node. Any physical device with one or more interfaces. A node may have multiple interfaces, and may also have multiple services per interface. (Whether or not a specific interface "belongs" to a node can be determined using several different methods i.e. SNMP or NetBIOS Names. However, if no parenting information is available for a given interface, it will be represented as a separate node.)

Event. Any occurrence or happening.

Alarm. Any significant occurrence or happening. Alarms are based on one or more occurrences of events.

Outage. A temporary suspension of operation, signified by an inability to communicate with a managed service. (A failed poll.)

Notice. A notice is generated when specific events occur. The notification process usually consists of making users, or groups of users aware of these events via email, pagers or other means, or in some cases initiating corrective actions.

Chapter 2. Chapter 2

Main page

The web interface is accessed, using a web browser on port 8980 in the opennms sub-directory.

From this centralized view, a quick overview of the current health of the network can be found. Notice in the upper right hand corner is information about the time and date on the management station, as well as the currently logged in user, and whether or not notices are currently turned on.

Outage table

To the left of the screen is the outage table, labeled "Nodes with Outages." This is a list of nodes that currently have service outages. Clicking on a node in this list will present more specific information about the node, it's services, and current, as well as historic, outages. From this page, information can be found regarding times that any outages occurred as well as when service was restored.


In the center of the display are categories of services. For each category, there is listed the number of current outages as well as availability for the last 24 hours.

The outage, and availability sections of this table are colored green, yellow, or red based on threshold values set by the administrator when the system was installed.

Performance and Notification

On the right side of the display there are links to notifications and a portal to performance graphs. This section is used to create graphs from data collected via SNMP.

Chapter 3. Chapter 3


When an event occurs on the management station, it is stored in the database. These entries can be viewed on the events page which is accessed by clicking "Events" on the menu bar near the top of the main page.

Viewing Events

From this page, start by choosing the type of events to view. Options are "outstanding events" (events that have not yet been acknowledged) and "acknowledged events." After selecting the type of events, an unfiltered list of events is presented in a table format. Each event has been assigned a severity and is colored appropriately. The legend can be viewed by pressing the button labeled "Severity Legend".

More information about any event can be reached by clicking on the link in the ID column.

Managing Events

From the main Events page there is a link to acknowledge or unacknowledge all events. In addition, filters can be applied to the event list by clicking on the "+" or "-" next to the item.

Clicking the "-" will exclude any item where the specific field that matches that value.

Clicking the "+" will exclude any item that does not match that value for the specific field.

Chapter 4. Chapter 4


Access the outage page by clicking on the "Outages" link in the main menu. On this page there is a table that contains information about all current outages for all managed devices. On this page, there is information regarding the type of outages, affected nodes and interfaces as well as the times of the outages. Clicking links in this table will provide additional information such as availability, events, and historical outages.

Chapter 5. Chapter 5


Clicking on the "Search" link in the main menu takes us to the search page. From here we can search for nodes using various criteria. Once a search is initiated we recieve a list of nodes and their interfaces that match the search criteria. Each of these will be a link to the main node, or interface pages. These pages contain a very complete set of information about each device. Below is more detail on some of the different types of searches that can be done.

Searching for Nodes

Generate lists of nodes that match any of a number of criteria including ip addresses, services, and machine names. Ranges of addresses can be entered for example, to provide a list of nodes that have ip addresses in that range. There are examples on this page, as well as some syntax rules to help refine searches. If all else fails there is also a link to "list all nodes"

Searching Asset Information

If asset information has been entered for devices on the network, a search can can be created based on that information. Searches can be initiated based on category, information in any given field, or again there is a link to all nodes containing asset information.

If no asset information has been entered for the devices, these searches will not return any matches.

Chapter 6. Chapter 6


Access the main reporting page by clicking "reporting" in the main menu. From this point there are 3 options, performance reports, custom performance reports and availability reports. In this section we will look at each type of report, and how to generate and interpret the graphs and information provided.

Performance Reports

Clicking on "Performance Reports" will display a list of options for generating the standard performance reports.

In the leftmost select box, choose an interface to generate a report on. Select any one SNMP capable interface. Next, choose what information to report on. Select any number of options in the second column. Select at least one option in each of the first 2 columns. Lastly, choose the timeframe to report on.

After selecting the options, press the "Submit" button to be taken to a bookmarkable page containing the resulting reports.

Custom Performance Reports

After selecting "Reports" from the main menu select "Custom Performance Report". At this point, you will be guided through a series of questions about the report you would like to create. First choose the interface on which you would like to report. Next you need to select between 1 and 4 data sources to report on. For each data source you can choose a title, color, line style and the type of value. Finally choose a title for you graph as well as a time period to report on. From this point, selecting next should display a bookmarkable graph. The complete address of this graph can be sent to another user via email, or instant message.

Availability Reports

After selecting "Reports" from the main menu select "Availability Report". From this point simply select the type of report you would like to create, and the category you would like to report on. Pressing the "Get Report" button will open the requested report in a new browser window.

Chapter 7. Chapter 7


Notifications Notify you of events.

Turning Notifications on

From the admin page, select Notification Status ON, then simply click "Update Status". This will turn notifications on/off for the entire system en masse.

Check and Acknowledge Notifications

From the notifications page select the catagory that best describes the type of notifications in which you are interested. From here you will get a list of notifications that you can browse through and acknowledge, if needed. Unacknowledged notifications will continue to escalate as perscribed, until acknowledged.

Managing Notifications

From the admin page and click "Turn On/Off Notices by Service". Follow instructions on this page to control notifications on a per service basis.

Chapter 8. Chapter 8


!!!Important!!!: Please read this entire section, before you enter any asset information.

Asset information helps you keep track of information about your managed devices. It can be used as search criteria, and is very handy in troubleshooting when you need a phone number for a vendor, or wish to document peculiar behavior for the next person that may access this information.

Adding Asset information

Use the search page to find the node you would like to add asset information to, and click it. Then click "Asset Info". Fill out whatever fields you think you need. Click submit. When entering asset information, be very careful not to use any commas in any fields if you plan to export or import your data. THERE IS CURRENTLY NO WAY TO ESCAPE COMMAS IN THE CURRENT VERSION.

Search Nodes based on Asset Information

Go to the search page or asset page and enter the criterium, and search.

Exporting Asset Information

Exporting your asset information will give you a list of comma separated values. The first line of which will be the field names, and each subsequent line a device.

Importing Asset Information

This feature, by itself, is basically useless in it's current state. The node id must match for each device, and because of that, this information can not be passed from one management station to another, nor could it even be used across installations, unless you remapped the node ids. Information could be exported from a management station, imported into a spread sheet, then modified, exported back to a comma separated list, and then re-imported back into the same management station from which it was initially exported. Or alternately the exported list could be modified by an external script and then re-imported if for instance you would need to duplicate information such as addresses for a large number of devices.

Note that when re-importing information, the field names (the first line) should be left out. That is, if you export and save the resultant .csv file, pasting this file in the import field would cause an error in the first line. The field names are only there for the sake of another spreadsheet/database program that could read them as field names.

Chapter 9. Chapter 9


This project is always under development. Features and functionality are constantly being added or improved. Some items in this documentation may from time to time be out dated, or even refer to features that are not in the current release of the software, and may only exist in the unstable branch of the CVS reporitory. There are a number of places to get help and information about OpenNMS. You may also wish to contribute code to the project. In the following section I will point out some resources that may be of use.


In addition to this document there are also guides that cover installation, and administration of OpenNMS. The latest versions of these guides are usually available from CVS. While it is nearly impossible to document every aspect of the project this way it is a very good place to start.

Web Site

The OpenNMS web site is available at

From here you can gain access to the software, documentation, bug information, mailing list archives, and CVS, as well as a number of other resources.


OpenNMS currently supports a number of mailing lists. For more information on specific lists and how to join, please visit


Usenet News

While as of the writing of this document OpenNMS does not host a specific news group, you can often find information scattered around various other news groups.