OpenNMS® Installation Guide

Installing the OpenNMS Network Management Application

OpenNMS Development Team

Tarus Balog

DJ Gregor

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts. A copy of the license is available at

Table of Contents

1. Overview
1.1. About OpenNMS
1.2. How to Use This Document
1.3. Minimum Requirements
2. Preparing for install
2.1. Prerequisite Package: Java
2.1.1. Installing Java on Debian
2.1.2. Installing Java on Everything Else
2.2. Prerequisite Package: Tomcat4
2.2.1. Modifying Tomcat4 on Debian Sid
2.2.2. Installing Appropriate Tomcat4 on Fedora Core 2 and 3
2.2.3. Installing Tomcat4 on SuSE Linux Pro 9
2.2.4. Customizing Tomcat4
2.3. Prerequisite Package: RRDtool
2.4. Prerequisite Package: PostgreSQL
2.4.1. Customizing the postgresql.conf file
2.4.2. Customizing the pg_hba.conf file
2.4.3. Installing the PostgreSQL on Red Hat Linux 7
2.4.4. Creating the PostgreSQL Database on Solaris
2.5. Prerequisite Package: curl
2.6. Optional Prerequisite Package: metamail
3. Installing OpenNMS
3.1. Performing a Fresh Install
3.1.1. Installing on Debian Linux
3.1.2. Installing on RPM-based Linux Distributions
3.1.3. Installing on Solaris
3.1.4. Installing on Mac OS X
3.1.5. Installing from Source
3.2. Upgrading an Existing Installation
3.2.1. Basic Locations for OpenNMS Data
3.2.2. Before Upgrading - Make a Backup!
3.3. Run the Installer
3.3.1. Configure Java for OpenNMS
3.3.2. Run the Installer to Setup the PostgreSQL Database
3.3.3. Run the Installer to Setup the Web Application
4. Getting Started with OpenNMS
4.1. Configuring Discovery
4.2. Start PostgreSQL, Tomcat4, and OpenNMS
4.3. Login to the web application
4.4. Configure OpenNMS to Start Automatically at Boot Time
4.4.1. Configuring Automatic Startup on Debian Linux
4.4.2. Configuring Automatic Startup on RPM-based Linux Distributions
4.4.3. Configuring Automatic Startup on Solaris
5. Building From Source
5.1. Are you sure you want to do this?
5.2. Install prerequisite applications
5.3. Download source
5.3.1. Retrieve released source
5.3.2. Retrieve source from CVS
5.4. Configuring
5.5. Compiling OpenNMS
5.6. Installing OpenNMS
6. Troubleshooting an OpenNMS Installation
6.1. Common Installation Issues
6.1.1. Dependency Problems
6.1.2. Error: "Started OpenNMS, but it has not finished starting up"
6.1.3. DHCP Poller Won't Start
6.1.4. The OpenNMS Web Application Will Not Start, or You Can't Log In
6.1.5. Error: "runjava: Could not find an appropriate JRE"
6.1.6. Error: "The database server's error messages are not in English ..."
6.1.7. Error: "Column X in new table has NOT NULL constraint ..."
6.1.8. Error: "One or more backup tables from a previous install still exists"
6.1.9. Error: "Table X contains N rows (out of M) that violate new constraint Y"
6.2. Where to Get Help
6.2.1. The Release Notes
6.2.2. The OpenNMS Web Site
6.2.3. The OpenNMS Mailing Lists
6.2.4. Commercial Support


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. Overview

1.1. About OpenNMS

OpenNMS is the world's first enterprise-grade network management system developed under the open source model. As with any complex and powerful system, getting it installed and configured can take a little effort. It is the purpose of this document to explain what is required to get OpenNMS installed.

1.2. How to Use This Document

So, how should you use this document? It is arranged in the following sections:

  • This overview

  • The programs on which OpenNMS depends, and how they need to be modified

  • Installation and upgrade instructions, including details for spectific operating systems and distributions

  • Getting started with OpenNMS, including initial configuration and logging into the web interface

  • Building OpenNMS from source

  • Troubleshooting and Where to Get Help

This installation guide relies strongly on the idea of "packages." Most modern operating systems and distributions have a system where software can be installed and managed through the use of packages that group the files belonging to a given application together (as well as managing changes to those files, removal, upgrades, etc.).

Please see the latest release notes to see if your operating system is supported. Currently OpenNMS runs on many Linux distributions, Solaris and Mac OS X.

This guide assumes that if you use packages, you do so consistently. This is because OpenNMS will attempt to determine if the software it requires is installed by using the operating system's built in package management system. If you've installed, say, Java, but not via packages, OpenNMS will be unable to determine that Java is installed and it will fail.

To get back to the original question of "how should you use this document," first go through the second section to insure that you have all of the prerequisite applications properly installed and configured. Use the third section to help get those packages installed for your particular operating system, as well as the OpenNMS software. Finally, use the last section to help correct any errors your might encounter.

1.3. Minimum Requirements

While it is impossible to exactly size OpenNMS for a particular environment, the following represents the minimum requirements for installation, assuming a network of about 200 devices. Note that OpenNMS can monitor more than 100 times that given the proper hardware.


A 1 GHz Pentium III (or equivalent processor) or better. OpenNMS can also take advantage of multiple processors.


A minimum of 256 MB of RAM, although 512 MB is strongly recommended. The OpenNMS Java Virtual Machine benefits from large amounts of memory, up to 2 GB.

Disk Space

OpenNMS requires about 25 MB of disk space for the program files. In addition, each data variable collected requires, by default, 283 KB of disk space. It is safe to assume that each interface being managed will require around 2 MB of disk space, so for 200 interfaces you are looking at 400 MB (conservatively). Depending on the number of events stored, you can assume 100 MB to 200 MB are required for the database. Finally, the OpenNMS logs can grow quite large, especially in debug mode. Edit the file in the OpenNMS configuration directory (usually /opt/OpenNMS/etc or /etc/opennms) to change those settings. For a minimum system, 800 MB to 1 GB should be sufficient.

Chapter 2. Preparing for install

2.1. Prerequisite Package: Java

OpenNMS is written mainly in Java, although there are a few JNI calls to some C code in order to implement things such as ICMP. and so it follows that Java would need to be installed.

As the current code has a small dependency on a Sun-only library ("" in the HTTPS Monitor), it is recommended that Sun's SDK is used. It should be possible to use IBM's SDK, but you'll get an error in the logs when the poller starts.

The instructions below are on using Sun's Java distribution, however a number of users have had success with the Blackdown builds of Sun's Java.

XXX Add something about 32-bit vs 64-bit for libjicmp and librrd.

2.1.1. Installing Java on Debian

Add the following to /etc/apt/sources.list and update, (i.e. "apt-get update").

For Woody, add:

deb debian/opennms stable

For Sid, add:

deb debian/opennms unstable

Next, obtain and install a suitable version of Java. Because of licensing issues, a suitable Java SDK cannot be distributed with OpenNMS so you will have to obtain and install one yourself prior to installing OpenNMS. You have two options here:

  1. Use the sun-jdk1.4-installer package and build script to download the j2sdk from Sun and build your own j2sdk1.4 package (recommended).

    Building and installing a j2sdk1.4 package:

    • The java-common package is a dependency for the j2sdk1.4 package you will be creating, and since it will be installed by dpkg, apt will not be there to pull it in so install it first:

      # apt-get install java-common

    • Next, install the sun-jdk1.4-installer package:

      # apt-get install sun-jdk1.4-installer

    • Download the Java 1.4.2 SDK from Sun. Make sure that you get the non-RPM binary package (the ".bin" package).

    • Then run the following command to build the package:

      # build-sun-jdk14 ./j2sdk-1_4_2_05-linux-i586.bin

      where j2sdk-1_4_2_05-linux-i586.bin is the binary file you downloaded from Sun.

    • And finally install the package:

      # dpkg -i j2sdk-1_4_2_05-linux-i586.deb

      where j2sdk-1_4_2_05-linux-i586.deb is the Debian package that was just created by build-sun-jdk14.

  2. Obtain and install and your own version and meet the OpenNMS packages dependencies by installing the java-virtual-machine meta-package.

    # apt-get install java-virtual-machine

2.1.2. Installing Java on Everything Else


It is important to install the SDK instead of the JRE, as Tomcat will need to compile Java code (which requires "javac" in the SDK).

You will need to use Sun's Java 2 Platform, Standard Edition, version 1.4.2 or later. You can download it from Sun's Java website. Step through the licensing process and then download the proper version of Java for your operating system. If you will be using an RPM-based Linux package of OpenNMS, you will need to download the RPM package of Java, otherwise, you will want the ".bin" file. Install Java according to the instructions from Sun.

2.2. Prerequisite Package: Tomcat4

Tomcat is part of the Jakarta project in Apache, and it is a Java servlet engine. What that means is that Tomcat is a web server that serves up HTML that is built from small Java programs called "servlets". Note that this is much different than Java "applets"--servlets are run on the server, not downloaded to the browser. Once a servlet is compiled, Tomcat will cache it, which means that the first visit to a particular page may be slow, but subsequent visits should be rather fast.

The latest version of Tomcat is Tomcat5, however OpenNMS does not work with Tomcat5 due to using Tomcat4-specific authentication features. This will be changed in a future version, but for now, you need to use Tomcat4.

2.2.1. Modifying Tomcat4 on Debian Sid

Recent versions of the Tomcat package in Sid, (unstable), use jikes as the compiler instead of the javac from your toolkit. Open up /etc/tomcat4/web.xml in your favorite editor and comment out the "compiler init param" section.

2.2.2. Installing Appropriate Tomcat4 on Fedora Core 2 and 3

The Tomcat4 package that ships with Fedora Core 2 does not appear to reliably run, even when the OpenNMS web app is not installed. For now, we suggest using the tomcat4 packages on the OpenNMS FTP site. You'll want to install both packages, tomcat4-4.1.18-full.1jpp.noarch.rpm and tomcat4-webapps-4.1.18-full.1jpp.noarch.rpm.

There is a bug in some kernels that can cause Java processes, and even the entire kernel to hang. It is documented in Red Hat bug #121902. You should make sure you are running at least a 2.6.6-422 kernel.

2.2.3. Installing Tomcat4 on SuSE Linux Pro 9

SuSE 9 ships with Tomcat 5, which will not work with OpenNMS. You will need to de-install the Tomcat 5 packages if they are installed and install Tomcat 4 from an older release of SuSE. The Tomcat 4 packages for SuSE 8.1 seem to work just fine. They are available on SuSE's FTP site.

2.2.4. Customizing Tomcat4

We need to make a few changes to Tomcat. Most of these should be done via the installer, but you will need to make a few changes by hand. These two changes will need to be made manually to Tomcat:

  1. Tomcat must be configured to use the same installation of Java that OpenNMS uses.

  2. Tomcat needs to be able to read and write the configuration files of OpenNMS. This can be done one of two ways. The first option is making Tomcat run as root and the second is making the OpenNMS configuration files readable and writable by the user Tomcat runs as.

Many Linux distributions have a tomcat4.conf configuration file where you can set configuration parameters. It is in /etc/tomcat4/ on the Red Hat and Fedora series of Linux distributions. It looks like this:

j# tomcat /etc/rc.d script example configuration file
# Use with version 1.07 of the scripts or later

# Use Jpackage utils if present
if [ -x /usr/bin/java-functions ]; then
. /usr/bin/java-functions

# Source Java system configuration if exist
if [ -r /etc/java/java.conf ]; then
. /etc/java/java.conf

# you could also override JAVA_HOME here
# Where your java installation lives
# JAVA_HOME="/usr/java/jdk"
# JAVA_HOME="/opt/IBMJava2-131"

# You can pass some parameters to java
# here if you wish to
#JAVACMD="$JAVA_HOME/bin/java -Xminf0.1 -Xmaxf0.3"

# Where your tomcat installation lives
# That change from previous RPM where TOMCAT_HOME 
# used to be /var/tomcat.
# Now /var/tomcat will be the base for webapps only

# What user should run tomcat

# You can change your tomcat locale here

# If you wish to further customize your tomcat environment,
# put your own definitions here
# (i.e. LD_LIBRARY_PATH for some jdbc drivers)
# Just do not forget to export them 

In this file, you can change the location of the Java environment and the user that Tomcat runs as by changing JAVA_HOME and TOMCAT_USER variables, respectively. You can add a line for JAVA_HOME that points to your installation of Java, for example:


To change the Tomcat user, you would set:


If you are using a Linux distribution or another operating system (e.g.: Solaris, Mac OS X) that does not have a tomcat4.conf file, you will need to figure out how effect the same changes. Please feel free to post your details as an enhancement bug to the OpenNMS bug database or send an email to the opennms-install mailing list and we will add it to this documentation.

If you choose not to set the user that runs Tomcat to root, you will need to make the following changes so that the Tomcat user can read and write the OpenNMS configuration files. This process adds the "tomcat" and "root" users to the "tomcat4" group, and then changes permissions so that the "tomcat4" group can write to the OpenNMS "etc" and "logs" directory. You have to do this after the OpenNMS software is installed.

  1. The "tomcat" user should have been created on installation of Tomcat--verify this by looking in /etc/passwd.

  2. Edit /etc/group and add "tomcat" and "root" as members of the "tomcat4" group. It should look something like:


  3. Locate the OpenNMS "etc" directory. It is usually in /opt/OpenNMS/etc or /etc/opennms. It will have a number of files with an ".xml" extension, such as capsd-configuration.xml. Run the commands:

    # chgrp -R $OPENNMS_HOME/etc
    # chmod -R g+w $OPENNMS_HOME/etc

    where $OPENNMS_HOME/etc is the OpenNMS "etc" directory.

  4. Locate the OpenNMS "logs" directory. This is usually /var/log/opennms, and can be found by looking in the file in the OpenNMS "etc" directory (find an instance of "File"). Run the commands:

    # chgrp -R $OPENNMS_HOME/logs
    # chmod -R g+w $OPENNMS_HOME/logs

    where $OPENNMS_HOME/logs is the OpenNMS "logs" directory.

Tomcat will start with just the first change, but without the second change you'll start seeing errors in the OpenNMS logs, and administration commands run in the web UI will fail because Tomcat cannot change the configuration files.

2.3. Prerequisite Package: RRDtool

RRDtool is the genesis of probably the first widely used open-source network management tool, MRTG.

RRDtool provides a "round robin" database that stores time-series data quickly and in a small amount of space. OpenNMS stores its performance-related data in RRD files created using RRDtool.

We require no special configuration for using RRDtool. As long as it was installed as a package, the OpenNMS package should be able to find it and configure itself to use the proper commands. We are known to work with any "1.0" version of RRDtool since 1.0.33.

2.4. Prerequisite Package: PostgreSQL

XXX add a comment about 32-bit vs. 64-bit stuff for the module

PostgreSQL (or "Postgres") is a relational database that OpenNMS uses to store information about devices on the network, as well as information about events, notifications and outages.

When installing OpenNMS, two things must happen. First, OpenNMS has to be able to contact the database over TCP/IP (even on localhost) and second, the installation process must be able to create the database.

OpenNMS requires version 7.2 or later of PostgreSQL. If you are using a version of PostgreSQL prior to 7.4, the server error messages are required to be in English (the 'C' locale). In particular, the parameter lc_messages must be set to 'C'. This is set in postgresql.conf in he PostgreSQL data directory and it requires the database be restarted if you change the setting. See the section below on pg_hba.conf for details on the location of the data directory.

The minimum packages you will need to install should be:

  • postgresql-server

Note that Red Hat Enterprise Linux and CentOS call their PostgreSQL packages "rhdb" for the "Red Hat DataBase" and older releases of SuSE call their packages "postgres".

If you are using later releases Mandrake, around 9 or later, you also need:

  • postgresql-pl

Once you have installed Postgres, you will need to make two changes to Postgres configuration files: postgresql.conf and pg_hba.conf. These files are only created once Postgres has been started, so if your installation method for Postgres did not start the database, do so before continuing. Usually, startup scripts will be placed in /etc/init.d.

Locate the Postgres "data" directory. Often this is /var/lib/pgsql/data. You should then find the two files we need to modify in that directory.

2.4.1. Customizing the postgresql.conf file

This file controls some basic parameters of Postgres. We need to change three of these parameters.

  1. Find the line in the file that contains tcpip_socket. It needs to read (this can be ignored on PostgreSQL 8.0 and later as this is the default):

    tcpip_socket = true

    Make sure that there is no comment character ("#") in front of that line (or the other two that you change). This will enable OpenNMS to talk to the database.

  2. Find the line in the file that contains max_connections. It needs to read:

    max_connections = 256

  3. Find the line that contains shared_buffers. It needs to read:

    shared_buffers = 1024

2.4.2. Customizing the pg_hba.conf file

The pg_hba.conf file controls which machines and users can access the database on a given machine via TCP/IP.

Since that is how OpenNMS accesses the database (via localhost) it is necessary to modify this file to allow OpenNMS to work. The easiest thing to do is to just allow anyone from the localhost to access the database (do not add the last line if your system does not support IPv6):

local all all
trust host all all
trust host all all ::1 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff trust

Make sure that no other lines are uncommented in this file.

You will need to stop and restart Postgres after making these changes.

2.4.3. Installing the PostgreSQL on Red Hat Linux 7

You will need to install version 7.2 of Postgres (which was available in Red Hat Linux 7.3).

2.4.4. Creating the PostgreSQL Database on Solaris

You will need to create an opennms database.

As the postgres user, go to the /usr/local/pgsql/bin directory, and run the following command:

# ./initdb -D /usr/local/pgsql/data -E ""

This will create the database. Following the instructions in the section above, modify the pg_hba.conf and postgresql.conf files.

Then you'll need to start the database:

# ./pg_ctl -D /usr/local/pgsql/data start

Now you are finished as the postgres user.

2.5. Prerequisite Package: curl

The startup script uses curl to connect to the OpenNMS daemon to check that the various components are up and running ("opennms status").

2.6. Optional Prerequisite Package: metamail


This is no longer needed starting with OpenNMS 1.1.4, as the Perl mailing has been replaced with a Java mailer.

Since OpenNMS uses Perl to mail availability reports, with some mailers it is necessary to add the metamail application in order for the PDF files created by OpenNMS to be mailed properly.

Like the Perl modules in the above section, metamail can be found on the OpenNMS FTP site (which includes and SRPM) if metamail is not directly available for your distribution.

Chapter 3. Installing OpenNMS


You need to be root when you execute the commands in this chapter.

Follow the instructions in either the fresh install section or the upgrade section, and then continue to the section on running the installer. If you have any errors during the installation process, please see the troubleshooting section of this guide.

3.1. Performing a Fresh Install

Follow the instructions in this section appropriate for your operating system if you are performing a fresh install. If you are upgrading an existing installation of OpenNMS, see the next section.

3.1.1. Installing on Debian Linux

Assuming that you have setup the apt repository in the prerequisities section, do this:

# apt-get install opennms

Optionally install the documentation and/or contrib packages

# apt-get install opennms-doc opennms-contrib

You can also download the appropriate packages for your version of Debian from the OpenNMS Files section on SourceForge.

3.1.2. Installing on RPM-based Linux Distributions

Download the appropriate packages for your Linux distribution from the OpenNMS Files section on SourceForge.

# rpm -i opennms-1.1.5-0_<distribution>.<platform>.rpm
# rpm -i opennms-webapp-1.1.5-0_<distribution>.<platform>.rpm
# rpm -i opennms-docs-1.1.5-0_<distribution>.<platform>.rpm

3.1.3. Installing on Solaris

Download the appropriate package for your Linux distribution from the OpenNMS Files section on SourceForge.

# cd /usr/local
# gzip -d opennms-1.1.5-0-sol<version>-sparc-local.gz
# pkgadd -d `pwd`/opennms-1.1.5-0-sol<version>-sparc-local

3.1.4. Installing on Mac OS X

XXX write me

3.1.5. Installing from Source

Before you try to install from source, visit the chapter on "Building from Source," to first download and compile from source.


this will install into dist in the same directory as the build.xml file unless you changed install.dir as mentioned in the "Building from Source" chapter.

Execute this command to install:

# sh install

3.2. Upgrading an Existing Installation

XXX this section could use some more love, too.

Upgrades from a previous version of OpenNMS to a current one usually just involve installing a new package for your particular distribution.

For RPM-based distributions, this is pretty simple using the "rpm -Uvh [package name]" command.

In addition, the OpenNMS installer may attempt to make changes to the database. Follow the instructions later in this chapter for executing the installer. The changes should go smoothly, but as with the best laid plans things may go wrong. Make a backup of your PostgreSQL database per the details below before upgrading in case there are problems.

3.2.1. Basic Locations for OpenNMS Data

OpenNMS stores data in a number of locations:


OpenNMS configuration files. If the default structure of a file in $OPENNMS_HOME/etc has changed between versions, RPM will create a ".rpmnew" version of that file. You will need to look at the changes between your file and the new one and merge them manually, at the moment. The command "diff -u <old file> <new file> | less" can assist you in seeing what has changed.


RRD data files that store response time data and performance data collected from SNMP. The installer should not touch the RRD files in $OPENNMS_HOME/share/rrd. Unless you are moving from RRDTool to jRobin, you should not have to worry about them.


The OpenNMS web application. While data is not stored here, some users may customize the web interface and these customizations should be saved before upgrading OpenNMS.


Data about nodes, services, events, notifications, etc., are stored in the opennms table in PostgreSQL.

3.2.2. Before Upgrading - Make a Backup!

Things can go wrong on upgrades, so it is always a good idea to make a backup of important information before attempting the upgrade.

For OpenNMS, you should do two things:

  1. Copy the contents of the $OPENNMS_HOME/etc directory to a safe location. Should an issue arise with any new files, you will want to be able to recover your original

  2. Make a backup of the postgres database. Using the pg_dumpall command you can dump the entire contents of the database to a file:

    # pg_dumpall > old_data

    will copy all of the data to a file called old_data. You will want to run this as the "postgres" user:

    # sudo -u postgres pg_dumpall > old_data

    To restore, run the command:

    # sudo -u postgres psql -U postgres -f old_data template1

  3. If you have made changes to the web application, you will want to save a copy of your changes, as well.

As mentioned earlier, there should be no need to backup the RRD files during an upgrade.

3.3. Run the Installer

No matter which installation method above you choose, and whether you are performing a fresh install or an upgrade, you still need to run the installer. This tool will setup the opennms database within PostgreSQL and also install the OpenNMS web application ("webapp" or the "webUI") into Tomcat.

3.3.1. Configure Java for OpenNMS

Before you execute the installer, OpenNMS needs to be configured to use an appropriate Java Runtime Environment (JRE). The OpenNMS tool runjava is used to set this up, and it can either search for a suitable JRE or you can tell it exactly which JRE to use. Search for a JRE (suggested)

Execute runjava with the "-s" option to search for a JRE:

# $OPENNMS_HOME/bin/runjava -s Configure a specific JRE

Execute runjava with the "-S <path to JRE>" option to specify the exact JRE you want OpenNMS to use:

# $OPENNMS_HOME/bin/runjava -S <path to JRE>

3.3.2. Run the Installer to Setup the PostgreSQL Database

# $OPENNMS_HOME/bin/install -disU

3.3.3. Run the Installer to Setup the Web Application

# $OPENNMS_HOME/bin/install -y -w $CATALINA_HOME/webapps -W $CATALINA_HOME/server/lib

Chapter 4. Getting Started with OpenNMS

4.1. Configuring Discovery

OpenNMS has a default host discovery configuration that probably does not fit your organization. Edit $OPENNMS_HOME/etc/discovery-configuration.xml. You'll see something like this:

<discovery-configuration threads="1" packets-per-second="1"
        initial-sleep-time="300000" restart-sleep-time="86400000"
        retries="3" timeout="800">

        <include-range retries="2" timeout="3000">



You will most likely want to change the beginning and end ranges (within the <begin> and <end> tags, respectively). And you can add multiple <include-range> entries to fit your needs. If you would rather list the individual hosts that you want to have discovered, you can insert <specific> tags above the <include-range> tag or place them in the file referrred to by <include-url>, one IP address per line. Lastly, if you prefer to use the web interface to add hosts for OpenNMS to monitor, you can comment out the contents of this file completely (put "<!--" before the first line and "-->" after the last line).

4.2. Start PostgreSQL, Tomcat4, and OpenNMS

This is an example and may vary based on your operating system:

# /etc/init.d/postgres start
# /etc/init.d/tomcat4 start
# $OPENNMS_HOME/bin/opennms start

If your operating system does not have a startup script for PostgreSQL or Tomcat4, you would execute something like this:

# sudo -u postgres /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start
# /usr/local/tomcat/bin/

4.3. Login to the web application

Point your browser at http://<host>:8080/opennms/ (port 8180 on Debian Linux). The initial user name is "admin" and the password is "admin".

4.4. Configure OpenNMS to Start Automatically at Boot Time

If everything looks good, you can configure OpenNMS to start automatically at boot time. By default on most platforms OpenNMS does not start automatically until you configure it to do so.

4.4.1. Configuring Automatic Startup on Debian Linux

This is enabled automatically when you install the Debian packages.

4.4.2. Configuring Automatic Startup on RPM-based Linux Distributions

The OpenNMS packages add an init script in /etc (usually /etc/init.d), however you need to execute chkconfig to enable the service to start automatically:

# chkconfig --add opennms

4.4.3. Configuring Automatic Startup on Solaris

# ln -s $OPENNMS_HOME/bin/opennms /etc/init.d/opennms
# ln -s ../init.d/opennms /etc/rc3.d/S99opennms
# ln -s ../init.d/opennms /etc/rc3.d/K01opennms

Chapter 5. Building From Source

5.1. Are you sure you want to do this?

OpenNMS is a complex software product, and it does not (yet) have a simple "./configure && make && make install" build process like many other tools. If there is a packaged release for your operating system, we highly suggest you use that instead. If you have problems with a packaged release, please see the troubleshooting section for assistance.

5.2. Install prerequisite applications

See the chaper on installing prerequisites for OpenNMS and install all prerequisites.

5.3. Download source

You can download source for a specific release, or you can download source directly from the source code respository (CVS). You probably want to download released source unless you wish to do development or are looking for specific features or bug fixes that are not yet in a release.


The commands listed below can be executed as any user, but they will all need to be executed as the same user.

5.3.1. Retrieve released source

Download the latest source release from the opennms-source file package in the OpenNMS files section at SourceForge. The file name of the source release will look something like opennms-source-1.1.5-0.tar.gz. After you unarchive the source distribution, change directory into opennms-1.1.5-0/source and continue to the next section.

5.3.2. Retrieve source from CVS

The source code for OpenNMS is stored in CVS at See the OpenNMS CVS page for details, or follow the instructions below to get started quickly.

Login to the CVS server with an empty password:

$ cvs login

Check out the OpenNMS sources (this will fetch HEAD, the most bleeding-edge version):

$ cvs -z3 co opennms

You will now have a directory called opennms. Change into this directory and continue to the next section.

5.4. Configuring

There are a few details about where RRDtool and PostgreSQL are installed that the build process cannot (or does not yet) reliably determine automatically. If you don't have RRDtool installed into /usr or if the PostgreSQL server include directory is not /usr/include/pgsql/server, you will need to create a file.

You can be lazy and let the build process tell you if it cannot find any of these components.

By default, the install process will install OpenNMS into the dist directory under the same directory that contains build.xml. This is fine for testing (and probably desireable), but if you want to install into somewhere for production use, you need to set install.dir. You probably want to add a line like this to


5.5. Compiling OpenNMS

This part is easy. Execute this command:

$ sh compile

5.6. Installing OpenNMS

Please see the chapter on installing OpenNMS for details.

Chapter 6. Troubleshooting an OpenNMS Installation

6.1. Common Installation Issues

The following section contains advice for overcoming common installation issues. If your issue is not addressed below, please see the section on where to get help.

6.1.1. Dependency Problems

To assist with code management, the easiest way to install OpenNMS is via packages. Every effort has been made to insure that the packages OpenNMS depends on are required before the OpenNMS package can be installed. You should be able to find those packages on the distribution CDs that came with your system. For some of the more obscure packages, like metamail, you can visit the OpenNMS FTP site and check in the /pub/dependencies directory. In addition, sites like Ibiblio and FreshRPMs are also good sources.

6.1.2. Error: "Started OpenNMS, but it has not finished starting up"

This can happen for a a number of reasons. You can run "opennms -v status" a few times after getting this error to see if OpenNMS eventually starts itself completely and if not, to see which daemons never start up completely. Hare are some of the likely causes of this problem:

  1. OpenNMS takes a while to startup. This can happen on larger installations and when this happens "opennms -v status" will eventually show that all services have started up. By default, the startup script will try 10 times to see if OpenNMS has started and will wait 5 seconds between each try. You can increase the number of times by creating $OPENNMS_HOME/etc/opennms.conf and adding a line like "START_TIMEOUT=20" to double the number of times it tests. You can set the value to 0 to have the startup script not wait for OpenNMS to start.

  2. Database is not running. If only about half or less of the daemons are shown as running. You can check for this condition by looking for FATAL errors in the log files. You'll see something like "Error accessing database" in the logs.

  3. Dhcpd doesn't start. See the item in the next section.

  4. JNI library problem. OpenNMS uses a few native C libraries that are accessed using JNI (Java Native Interface). Normally they just work, except users have started seeing problems when running Linux in native AMD64 mode where they end up using a 32-bit (x86) version of Java and a 64-bit (AMD64) version of the JNI libraries, or vice-versa. If you have this problem, you might want to try switching your version of Java from 32-bit to 64-bit or in the other direction.

  5. Other. If the OpenNMS is installed, and the packages were not forced in using options like "--nodeps", the application should run just fine. If not, OpenNMS has a robust logging facility. Change to the logs directory (usually /var/log/opennms) and search the logs, using grep or your tool of choice, for words like FATAL and ERROR (the two highest log severities). Those events should give you clues as to why OpenNMS is not working.

6.1.3. DHCP Poller Won't Start

The OpenNMS DHCP poller will fail to start most operating systems (Linux, in particular) if you are running a DHCP client on the OpenNMS server. You'll see this by running "opennms -v status" and seeing everything in the running state, except for Dhcpd. The solution is to edit $OPENNMS_HOME/etc/service-configuration.xml and comment-out the "<service>...</service>" stanza for Dhcpd. For example, this is what the section would look like after modification to disable Dhcpd:

        <!-- Commented out since we have a DHCP client on this server
                <invoke pass="1" method="start"/>
                <invoke at="status" pass="0" method="status"/>
                <invoke at="stop" pass="0" method="stop"/>

We discourage the running of OpenNMS on a server that is a DHCP client, both because OpenNMS may not be able to monitor DHCP servers on the network, and it is important that the monitoring server have a static IP address for receiving traps and to be reliant on as few network services as possible.

6.1.4. The OpenNMS Web Application Will Not Start, or You Can't Log In

There are actually two main applications in the OpenNMS product: the application itself and the web-based User Interface (webUI). The webUI is implemented via Tomcat, and it is possible for Tomcat to be running and the OpenNMS application to be stopped and vice versa.

Before you do anything else, check the platform-specific installation notes in this guide. There are a number of common problems with Tomcat which are covered there.

If you can't get to the OpenNMS interface (http://[opennms server]:8080/opennms or http://[opennms server]:8180/opennms on Debian - where [opennms server] is the name of the OpenNMS machine) make sure that Tomcat is running, and if necessary restart it. You should also be able to access the main Tomcat page by leaving off the "/opennms".

Check to make sure that the OpenNMS web application is installed correctly. In Tomcat's CATALINA_HOME (usually /var/tomcat4), you should see a sub-directory called webapps. Starting in OpenNMS 1.1.4, we no longer place the OpenNMS webapp directly into this webapps directory. Inside of webapps, you should only see a file (or symbolic link) called opennms.xml. If you see a directory (or symbolic link) called opennms, delete it (this is not done automatically by the installer when upgrading).

Also in CATALINA_HOME there is a sub-directory called conf and in that directory is a file called server.xml. Before OpenNMS 1.1.4, we needed to add a "context" to that file, however this is no longer needed in OpenNMS 1.1.4. In fact, if you are upgrading from 1.1.3 or earlier, you must manually remove this "context" from server.xml (it is not done automatically when upgrading). Here is what it looks like looks like:

<!-- Example Server Configuration File -->
<Server ...
    <Host ... >
      <Context path="/opennms" docBase="opennms" debug="0" reloadable="true">
        <Logger classname="org.opennms.web.log.Log4JLogger" homeDir="/opt/OpenNMS"/>
        <Realm className="org.opennms.web.authenticate.OpenNMSTomcatRealm" homeDir="/opt/OpenNMS"/>
      </Context >
    </Host >
</Server >

Tomcat will also need to be aware of various OpenNMS JARs and libraries which provide the Java classes which make these directives work. To give tomcat access to these resources, links are created in $CATALINA_HOME/server/lib pointing to the locations of the following OpenNMS JARs:

  • castor- -> /opt/OpenNMS/lib/castor-

  • log4j.jar -> /opt/OpenNMS/lib/log4j.jar

  • opennms_common.jar -> /opt/OpenNMS/lib/opennms_common.jar

  • opennms_core.jar -> /opt/OpenNMS/lib/opennms_core.jar

  • opennms_services.jar -> /opt/OpenNMS/lib/opennms_services.jar

  • opennms_web.jar -> /opt/OpenNMS/lib/opennms_web.jar

Tomcat has a "working" directory (usually $CATALINA_HOME/work) where it stores the Java source for JSP pages as well as the compiled classes for JSPs. Sometimes users see problems with the webapp until the working directory is cleared and Tomcat is restarted. We suggest running "rm -rf $CATALINA_HOME/work" if the above items fail to get the webapp working.

6.1.5. Error: "runjava: Could not find an appropriate JRE"

The runjava program is used to locate a suitable JRE for OpenNMS at install time that will be used for the installer and also for running OpenNMS after installation. See the section earlier in this manual on installing Java for OpenNMS. If you installed Java in a location that runjava cannot find, you can use its "-f" option to specify the JRE you want OpenNMS to use.

6.1.6. Error: "The database server's error messages are not in English ..."

You either need to set "lc_messages = 'C'" in your postgresql.conf file and restart PostgreSQL or upgrade to PostgreSQL 7.4 or later.

The installer does not always verify that an operation will succeed before executing the operation (e.g.: dropping database functions). In this case, it catches the exceptions returned from the database and checks the exception to see if it is an "okay" exception that should be ignored (e.g.: if the database function does not exist when attempting to drop a function).

In PostgreSQL 7.4 and later, a new client/server protocol is used (version 3, to be specific) that provides specific error codes intended for programmatic evaluation and we use these error codes if the server provides them. However for PostgreSQL versions before 7.4, we require that the database server error language be in English (the 'C' locale) so that we can parse the text error messages. If you are not running PostgreSQL 7.4 or newer, the installer executes a bogus query against the database and checks for an expected result in English.

6.1.7. Error: "Column X in new table has NOT NULL constraint ..."

This is a warning that the installer might not update tables successfully. Make sure that your database is backed up, and run the installer again with the "-N" option to ignore this check.

As an attempt to ensure that the install will complete successfully, a check is done to see if there might be any rows with NULL columns that might be inserted into a column in an upgrade table with a NOT NULL constraint. This usually happens when a previous run of the installer failed, or might be due to modifications to the database schema or a really old version of the schema.

6.1.8. Error: "One or more backup tables from a previous install still exists"

When the installer runs to upgrade the OpenNMS database from a previous install, it often updates table schemas. When it does this, it copies the data in a table to a temporary table (e.g.: the contents of node are copied into node_old_11033991291234). The original table is deleted, the new version of the table is created, the data in the temporary table is translated into the new table, and finally the temporary table is deleted.

Unfortunately, the installer cannot check for all problems that might break translation, so sometimes the translation step fails. In this case, the installer "reverts" the table it was processing by dropping the new table and moving the temporary table into its place.

Reverting the table in case of a problem is all good and well, but sometimes even it does not work properly, especially with older versions of the Java installer. If this happens, the temporary table (the one with "_old_" in it) is left with all of the old data. Until OpenNMS 1.1.5, this problem would not be caught the next time you ran the installer. The installer would see that you did not have the node table, for example, and happily continue to create a new one for you. This is bad, especially since you probably still have data that you care about that is now in the "old" table.

If you get this error, you will want to get rid of the table(s) containing "_old_", however you want to first check if they contain data. For example, if you have a single table, node_old_11033991291234, no other node_old_* tables, and no node table, you can simply rename the table:

# psql -h localhost -U opennms opennms
Welcome to psql 7.4.6, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit

opennms=# ALTER TABLE node_old_11033991291234 RENAME TO node;

You can use the "\d" command within psql to see what other tables exist in your database. You can use "SELECT count(*) from table;" (fill in the table name for "table") to get a count of rows in any table. If you have empty tables, you can just drop them. If you have multiple tables with data, you will have to decide which table of data you want to keep or merge them. This is left as a (not so simple) exercise for the reader.

6.1.9. Error: "Table X contains N rows (out of M) that violate new constraint Y"

Over time OpenNMS extends its database schema to improve functionality. This error can happen because of the way certain administrative functions in older versions of OpenNMS functioned or if the database was modified outside of OpenNMS (the latter is common for larger sites). Over time OpenNMS has introduced additional foreign key constraints on its database. These are used to ensure internal database consistency when data in two tables are tied together by a shared key. For example, each event can have a pointer to the node that it is related to; there is a foreign key constraint that requires that an event must not point at a node that does not exist.

Starting with 1.1.5, when we upgrade the database schema, we first check for rows that violate any new foreign key constraints that might be added. There are three options to to fix these errors:

  1. Remove the offending rows. This is suggested if the number of rows that violate the constraint is small in comparison to the total number of rows in the affected table and if you don't need the data. Use "$OPENNMS_HOME/bin/install -C <constraint> -X" to delete the offending rows.

  2. Mark the key in the offending rows to NULL. This is suggested if you need to keep the data around or are not yet sure about what to do with it. Use "$OPENNMS_HOME/bin/install -C <constraint>" to mark the key column to NULL in the offending rows.

  3. Fix the key in the offending rows. This is for advanced users and requires a good amount of effort. This is left as an exercise for the reader.

6.2. Where to Get Help

OpenNMS is a community supported project. Please keep that in mind when seeking help on the program, as no one gets paid to work on the project (unless it is through a commercial support contract).

6.2.1. The Release Notes

Check the release notes for this release. They are in the Documentation section of the OpenNMS project page at SourceForge.

6.2.2. The OpenNMS Web Site

The main OpenNMS site is a Wiki. As a community project, there is a lot of good advice and information available there. In particular, we suggest checking the above-mentioned release notes, the FAQ, the bug database and Google before posting to a mailing list. You might also find useful information in the old FAQ, but please realize that this information may be out of date.

6.2.3. The OpenNMS Mailing Lists

OpenNMS maintains a number of active mailing lists on SourceForge:


A low traffic, moderated mailing list for OpenNMS announcements. All posts to this list are duplicated on the opennms-discuss list.


This is a fairly high traffic list of all updates to the CVS repositories on SourceForge. Moderated. Only CVS updates are posted here (no discussion).


This list is for code development discussion.


This is the main OpenNMS discuss list. It's pretty friendly. Pretty much anything goes here, however it is suggested that installation-related issues to go opennms-install.


This is a great list for new users to OpenNMS. The main focus is installation issues (cleared up by this great documentation, right?) but most "newbie" questions are welcome here.


Whether or not to use maps in network management is as divisive an issue as abortion or gun control (grin). OpenNMS does have a small contributed map system, which still needs a lot of work. We can talk about it here.


We have a small users group in Tokyo, Japan. This list is for meeting announcements or help in Japanese.

6.2.4. Commercial Support

If you are using OpenNMS in a production environment, or are considering it, you might be interested in commercial support. The OpenNMS Group maintains the OpenNMS project, and we also offer support, training, consulting services and custom development.