OpenNMS?? Installation Guide


Published in

Copyright (c) Copyright ?? 2004 Blast Internet Services, Inc.,
www.opennms.org

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 Blast Internet Services, which also owns the OpenNMS trademark.

The OpenNMS Project strives to remain independent, and includes contributions from people outside of Blast. Please visit the OpenNMS website for more information.

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

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

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.

Prerequisite Applications for OpenNMS

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

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

If you are attempting to install version 1.1.3 or later, you will need to use Java version 1.4.2 or later. You can get it from Sun's 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, but we have not been tested against that yet. For version 1.1.0 of OpenNMS and later, we require at least Tomcat 4.1.18. For version 1.0, you must use Tomcat 4.0 in order to get the navigation links to work properly. This is due to a change that the Tomcat team made between 4.0 and 4.1.

If you have 4.0 installed and want to install 4.1, you may need to remove 4.0 first.

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.

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.

Once OpenNMS is installed, it will need to make some changes. These should happen automatically, but I'll list them here for completeness.

First, in the CATALINA_HOME directory (usually /var/tomcat4), you should see a subdirectory called "webapps". The OpenNMS webapp directory will need to either be a sub-directory in webapps or linked from there. The OpenNMS installer should do this.

Second, also in the CATALINA_HOME directory should be a sub-directory called conf. 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 installer 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 >
  ...
</Service >

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

Note that the OpenNMS installer should make all of these changes, but if you are having problems accessing the web UI or logging on, these are things to check.

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 of Postgres. Version 1.1 of OpenNMS requires a version of at least 7.2.

The minimum packages you will need to install should be:

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:

# TYPE  DATABASE    USER        IP-ADDRESS        IP-MASK           METHOD

local   all         all                                             trust
host    all         all         127.0.0.1         255.255.255.255   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 Perl modules perl-DBI and perl-DBD-Pg

While OpenNMS is moving toward being as completely Java as possible, we still use a bit of Perl in the installation as well as in mailing availability reports.

Prior to 1.1.3, the install.pl script was used to create the initial OpenNMS database. If you are using a version of OpenNMS prior to 1.1.3, you'll need to have these two Perl modules installed.

As I have mentioned earlier, the easiest way for OpenNMS to know that these modules are installed is if they are installed via packages. The OpenNMS FTP site, ftp.opennms.org has compiled these packages on a number of platforms (in the /pub/dependencies directory). Also, the application cpan2rpm can create these packages for you.

If you are installing a version prior to 1.1.3, please insure that these packages are installed.

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.

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:

  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:

  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.

SuSE

OpenNMS is now supported on SuSE.

SuSE Linux Enterprise Server 8

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

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.

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

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.

The OpenNMS Mailing Lists

OpenNMS maintains a number of active mailing lists on Sourceforge:

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.