OpenNMS® Installation Guide

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.

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.

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.

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:

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

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:

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.

# 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

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 startup script uses curl to connect to the OpenNMS daemon to check that the various components are up and running ("opennms status").

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.

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

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

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

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.

OpenNMS is now supported on SuSE.

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.

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.

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.

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

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.

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/opennms login

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

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

This part is easy. Execute this command:

./build.sh compile

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

XXX this needs to be written. :-)

Execute the startup script:

$OPENNMS_HOME/bin/opennms start

The following section contains advice for overcoming common installation issues.

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

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