OpenNMS® Installation Guide

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

For Woody, add:

deb http://debian.opennms.org/ debian/opennms stable

For Sid, add:

deb http://debian.opennms.org/ 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:

You will need to use Sun's Java 2 Platform, Standard Edition, version 1.4 or later. We suggest using 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.

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.

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.

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.

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:

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:

# 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
set_jvm
fi

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

# 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
CATALINA_HOME="/var/tomcat4"
JASPER_HOME="/var/tomcat4"
CATALINA_TMPDIR="/var/tomcat4/temp"

# What user should run tomcat
TOMCAT_USER="tomcat"

# You can change your tomcat locale here
#LANG=en_US

# 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:

JAVA_HOME="/usr/java/j2sdk1.4.2_04/"

To change the Tomcat user, you would set:

TOMCAT_USER="root"

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.

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.

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

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):

# TYPE DATABASE USER IP-ADDRESS IP-MASK METHOD
local all all trust
host all all 127.0.0.1 255.255.255.255 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.

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

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.

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.

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

# rpm -i opennms-1.2.1-1_<distribution>.<platform>.rpm
# rpm -i opennms-webapp-1.2.1-1_<distribution>.<platform>.rpm
# rpm -i opennms-docs-1.2.1-1_<distribution>.<platform>.rpm

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

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

XXX write me

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

Execute this command to install:

# sh build.sh install

OpenNMS stores data in a number of locations:

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:

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

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.

# $OPENNMS_HOME/bin/runjava -s

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

# $OPENNMS_HOME/bin/install -disU

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

This is enabled automatically when you install the Debian packages.

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

# 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

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.2.1-1.tar.gz. After you unarchive the source distribution, change directory into opennms-1.2.1-1/source and continue to the next section.

The source code for OpenNMS is stored in CVS at SourceForge.net. 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 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/opennms login

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

$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/opennms co opennms

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

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.

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:

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
        <service>
                <name>OpenNMS:Name=Dhcpd</name>
                <class-name>org.opennms.netmgt.dhcpd.jmx.Dhcpd</class-name>
                <invoke pass="1" method="start"/>
                <invoke at="status" pass="0" method="status"/>
                <invoke at="stop" pass="0" method="stop"/>
        </service>
        -->

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.

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:

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.

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.

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.

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.

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.

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:

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

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.

OpenNMS maintains a number of active mailing lists on SourceForge:

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.