OpenNMS® Installation Guide

Instructions on Installing the OpenNMS Network Management Application

OpenNMS Development Team

Tarus Balog

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 http://www.gnu.org/copyleft/fdl.html


Table of Contents

Preface
1. Installing OpenNMS - An Overview
Minimum Requirements
Download
2. Prerequisite Applications for OpenNMS
Java
Tomcat4
RRDtool
PostgreSQL
The postgresql.conf file
The pg_hba.conf file
The metamail Application
The curl Application
3. Platform-Specific OpenNMS Installation Notes
Debian
Woody
Sid
Fedora
Fedora Core 1
Fedora Core 2
Mandrake
Mandrake 8
Mandrake 9
Mandrake 10
Red Hat
Red Hat Linux 7
Red Hat Linux 8
Red Hat Linux 9
Red Hat Enterprise Linux 3
Solaris
Environment Variables
Creating the Database
Startup
SuSE
SuSE Linux Pro 9
4. Upgrading OpenNMS from Previous Versions
Basic Locations for OpenNMS Data
Before Upgrading - Make a Backup
5. Building hand Installing From Source
Are you sure you want to do this?
Install prerequisite applications
Download source
Retrieve released source
Retrieve source from CVS
Configuring build.properties
Compiling OpenNMS
Installing OpenNMS
Setup the webapp in Tomcat
Starting OpenNMS
6. Troubleshooting an OpenNMS Installation
Common Installation Issues
Dependency Problems
The OpenNMS Application Won't Start
The OpenNMS Web Application Will Not Start, or You Can't Log In
Where to Get Help
The OpenNMS Web Site
The OpenNMS Mailing Lists
Commercial Support

Preface

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. Installing OpenNMS - An Overview

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.

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

  • Distribution Specific Installation Instructions

  • 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 Linux (many distributions), Solaris and Mac OSX.

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.

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.

  • Processor: 1 GHz Pentium III class or better. OpenNMS will benefit from more processors.

  • Memory: 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 log4j.properties 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.

Download

OpenNMS is available for download from Sourceforge on the OpenNMS download page. Install the dependent packages per this document, and read the release notes to insure that your installation goes smoothly.

Chapter 2. Prerequisite Applications for OpenNMS

This section will discuss the applications needed to support OpenNMS. They include:

  • Java (most of OpenNMS is written in Java)

  • Tomcat4 (this is used as the servlet container for our web-based user interface)

  • RRDtool (used for storing time series data and for generating performance graphs)

  • PostgreSQL (our back end database for storing events and device information

  • Metamail (to assist with mailing PDF attachments for availability reports)

The actual packages needed will differ depending on your operating system and version, but the required configuration will be the same.

If you are having trouble finding particular packages, check out the OpenNMS FTP site at ftp.opennms.org.

Java

OpenNMS is written mainly in Java (there are a few JNI calls to some C code in order to implement things such as ICMP, as well as some small Perl scripts to assist with the install), and so it follows that Java would need to be installed.

As the current code has a small dependency on a Sun-only library ("com.sun.net.ssl.internal.www.protocol" 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.

Note that I said "SDK". 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).

Note: It looks like the installer for 1.1.3 only looks for java in /bin/java. Be sure to symbolically link it for now:

ln -s /usr/java/j2sdk1.4.2_04/bin/java /bin/java

replacing the first path with your path, if different.

If you are attempting to install version 1.1.3 or later, 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.

Note: If you are using Linux, unless it is Debian you'll want to download the RPM (see my comments about package management earlier). For Debian you'll need the ".bin" file, and you'll need to follow the instructions for Debian in the next chapter.

If you are attempting to install version 1.1.2 or earlier, you cannot use 1.4.2 (it will cause memory leaks). You will need to use something earlier, and from experience the proper version is 1.4.0, release 2.

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.

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

You'll need to find the tomcat4.conf file (it's in /etc/tomcat4/ on the Red Hat/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 

The two changes we need to make involve JAVA_HOME and TOMCAT_USER.

Add a line for JAVA_HOME that points to your installation of JAVA. For example:

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

Now the second thing you need to do involves the Tomcat user. You have two choices:

  1. The Easier Way: Just set the Tomcat user to "root":

    TOMCAT_USER="root"

    Note that this does open a potential security risk, although a minor one.

  2. The Harder Way: You add the "tomcat" and "root" users to the "tomcat4" group, and then change 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.

    • The "tomcat" user should have been created on installation - verify this by looking in /etc/passwd

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

      tomcat4:x:91:tomcat,root

    • 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_etc_dir]

      chmod -R g+w [opennms_etc_dir]

      where [opennms_etc_dir] is the OpenNMS "etc" directory.

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

      chgrp -R [opennms_logs_dir]

      chmod -R g+w [opennms_logs_dir]

      where [opennms_logs_dir] 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.

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.

PostgreSQL

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

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.

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:

    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

The pg_hba.conf file

Starting with Postgres 7.2 the "host-based authentication" file was added. This 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.

The metamail Application

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.

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

The curl Application

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

Chapter 3. Platform-Specific OpenNMS Installation Notes

Debian

OpenNMS is supported on Debian, and can be installed using apt. However, due to licensing issues, we cannot distribute a version of Sun's Java SDK, so some extra steps are required.

Woody

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

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

Then 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 several 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.

      [root@host /root]# apt-get install java-common

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

      [root@host /root]# apt-get install sun-jdk1.4-installer

    • Download the 1.4.2 SDK from Sun, get the non-RPM binary package

    • Then run the following command to build the package:

      [root@host /root]# 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:

      [root@host /root]# 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.

    [root@host /root]# apt-get install java-virtual-machine

Then, install OpenNMS:

[root@host /root]# apt-get install opennms

Optionally install the documentation and/or contrib packages

[root@host /root]# apt-get install opennms-doc opennms-contrib

Sid

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

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

Then 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 several 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.

      [root@host /root]# apt-get install java-common

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

      [root@host /root]# apt-get install sun-jdk1.4-installer

    • Download the 1.4.2 SDK from Sun, get the non-RPM binary package

    • Then run the following command to build the package:

      [root@host /root]# 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:

      [root@host /root]# 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.

    [root@host /root]# apt-get install java-virtual-machine

Then, install OpenNMS:

[root@host /root]# apt-get install opennms Optionally install the documentation and/or contrib packages

[root@host /root]# apt-get install opennms-doc opennms-contrib

Note: 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.

Fedora

OpenNMS is supported on Fedora. Note that yum and apt for RPM repositories will be available soon.

Fedora Core 1

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Fedora Core 2

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Mandrake

OpenNMS is supported on Mandrake. Note that urpmi repositories will be available soon.

Mandrake 8

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Mandrake 9

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Mandrake 10

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Red Hat

The following section refer to the supported versions of Red Hat Linux. Note that yum and apt for RPM repositories will be available soon.

Red Hat Linux 7

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section. To use version 1.1. or later, you will need to install version 7.2 of Postgres (which was available in Red Hat Linux 7.3).

Red Hat Linux 8

OpenNMS is currently supported on Red Hat Linux 8, but version 1.2.0 will be the last version to support this operating system.

Red Hat Linux 9

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section. Note that there was an issue with the RPM database "hanging" that might affect OpenNMS installation on a new system.

Red Hat Enterprise Linux 3

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Solaris

OpenNMS is supported on Solaris, both on SPARC and x86.

However, there are some extra steps required for a trouble free install on Solaris.

As with all OpenNMS installations, you need a Java SDK. In addtion, the PostgreSQL, Tomcat4 and RRDtool packages can be harder to find.

A good source for open-source packages is SunFreeware. Most of the packages there install in /usr/local, so we've adopted that convention for the packages we create. We have also included some packages on our FTP site in the /pub/dependencies directory.

Environment Variables

You will want to set up the following environment variables:

JAVA_HOME=/usr/java/j2sdk1.4.2_02 (or whatever your Java home dir is)

LD_LIBRARY_PATH=/usr/local/lib:/usr/local/ssl/lib/:/usr/local/pgsql/lib:/usr/local/opennms/lib:/usr/local/pgsql/include/server/lib:/usr/local/pgsql/include/internal/lib

POSTGRES_LIB=/usr/local/pgsql/lib

PERL5LIB=/usr/local/lib/perl5

Creating the Database

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.

As root, initialize the OpenNMS database:

/usr/local/opennms/bin/install -disU

Startup

Now you are ready to start OpenNMS. After modifying the files in /usr/local/opennms/etc (particularly the discovery configuration file), run:

/usr/local/opennms/bin/opennms.sh start

and then start Tomcat4 (restart it if it is already running):

/usr/local/tomcat/bin/startup.sh

Note: The shell you start this in will behave like a console, and you may get some JMX messages like:

DEBUG: pq_recvbuf: unexpected EOF on client connection

Just ignore them.

SuSE

OpenNMS is now supported on SuSE.

SuSE Linux Pro 9

There are no special requirements for OpenNMS on this distribution of Linux, except for those configuration issues mentioned in the previous section.

Chapter 4. Upgrading OpenNMS from Previous Versions

Basic Locations for OpenNMS Data

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.

OpenNMS stores data in three locations: the $OPENNMS_HOME/etc directory, the PostgreSQL database, and in RRD files (which live in $OPENNMS_HOME/share).

If the default structure of a file in "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.

In addition, the OpenNMS installer may attempt to make changes to the database. These should be automatic, but as with the best laid plans things may go wrong.

Finally, the installer should not touch the RRD files. Unless you are moving from RRDTool to jRobin, you should not have to worry about them.

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

  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

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

Chapter 5. Building hand Installing From Source

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.

Install prerequisite applications

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

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.

Retrieve released source

XXX someone needs to write this. :-)

Retrieve source from CVS

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

Configuring build.properties

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 build.properties 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 build.properties:

install.dir=/opt/OpenNMS

Compiling OpenNMS

This part is easy. Execute this command:

./build.sh compile

Installing OpenNMS

This part is pretty easy, too. Note: this will install into dist in the same directory as the build.xml, unless you changed install.dir as mentioned above. Execute this command to install:

./build.sh install

Once the files are installed, you need execute runjava to find and configure a suitable Java Runtime Environment for OpenNMS and then run the OpenNMS installer to setup the database and other items. First, execute runjava -s:

$OPENNMS_HOME/bin/runjava -s

Then, execute the installer:

$OPENNMS_HOME/bin/install -disU

Setup the webapp in Tomcat

XXX this needs to be written. :-)

Starting OpenNMS

Execute the startup script:

$OPENNMS_HOME/bin/opennms start

Chapter 6. Troubleshooting an OpenNMS Installation

Common Installation Issues

The following section contains advice for overcoming common installation issues.

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.

The OpenNMS Application Won't Start

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.

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.

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 of 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 subdirectory called webapps. The OpenNMS webapp directory, opennms, will need to be either a sub-directory in webapps or linked from thre. The OpenNMS installer should do this.

Also in CATALINA_HOME there is a sub-directory called conf and in that directory is a file called server.xml. We need to add a "context" to that file in order for Tomcat to know where OpenNMS lives. The install should also do this update, but for reference it 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 >

Finally, 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-0.9.3.9.jar -> /opt/OpenNMS/lib/castor-0.9.3.9.jar

  • 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

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

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 FAQ and the bug database. You might also find useful information in the old FAQ, but please realize that this information may be out of date.

The OpenNMS Mailing Lists

OpenNMS maintains a number of active mailing lists on Sourceforge:

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

  • opennms-cvs: 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).

  • opennms-devel: This list is for code development discussion.

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

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

  • opennms-maps: 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.

  • opennms-ug-tokyo: We have a small users group in Tokyo, Japan. This list is for meeting announcements or help in Japanese.

Commercial Support

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