OpenNMS® Installation Guide

Before you begin installing, you will want to set up Yum to install from the OpenNMS repositories. This covers most RPM-based distributions, including Red Hat Enterprise Linux, Fedora, and CentOS.

[user@localhost]$ sudo yum install yum-fastestmirror
 Setting up Install Process
 ...
 Running Transaction
   Installing: yum-fastestmirror            ######################### [1/1] 
 
 Installed: yum-fastestmirror.noarch 0:1.1.9-2.fc8
 Complete!

rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-snapshot-fc7.noarch.rpm

rpm -Uvh http://yum.opennms.org/repofiles/opennms-repo-unstable-rhel5.noarch.rpm

 [user@localhost]$ sudo yum list opennms
 ...
 Available Packages
 opennms.noarch                           1.5.96-1               opennms-unstable

[root@localhost]# cat /etc/yum.repos.d/* >> /etc/yum.conf

The Sun JDK is available in our Yum repository. If you have configured Yum as specified above, you just need to run:

yum install jdk

Because of a bug in the 64-bit RPM signing, if you are on x86_64, you will need to disable GPG checking. You can do so with the --nogpgcheck option to yum:

yum --nogpgcheck install jdk

The Sun JDK is available in our URPMI repository. If you have configured URPMI as specified above, you just need to run:

urpmi --auto jdk

Sun's Java can now be installed using "apt" on Debian Etch or higher.

apt-get install sun-java5-jdk

This should also work on Ubuntu 6.10 (Edgy Eft) or higher. Alternatively, you could install sun-java6-jdk, which has performance improvements over the java5 version.

You will need to use Sun's Java SE, version 5 (1.5) 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.

On modern versions of Red Hat Enterprise Linux, CentOS, and Fedora, you should just need to install the postgresql-server RPM:

[user@localhost]$ sudo yum -y install postgresql-server
Setting up Install Process
...
Running Transaction
  Installing: postgresql-server            ######################### [1/1] 

Installed: postgresql-server.x86_64 0:8.2.5-1.fc8
Complete!

sudo yum -y install rhdb-server

On Mandriva, you use URPMI to install the PostgreSQL server:

sudo urpmi --auto postgresql-server

On Debian or Ubuntu, use apt to install the PostgreSQL server:

sudo apt-get update
sudo apt-get install postgresql-8.1

On Windows, all you should need to do is get the latest Windows installer from PostgreSQL.org.

First, unpack the installer. The installer does not run properly from inside a zipped folder, so you will need to extract the ZIP file. You should be able to just copy the postgresql-X.X.msi and postgresql-X.X-int.msi files to your desktop and run them from there.

Then, run the postgresql-X.X.msi and follow the instructions. For the most part, the defaults should be just fine, although if you're allowing the installer to initialize your database, make sure the encoding is set to "UTF-8".

Once you have installed PostgreSQL, you will need to make two changes to Postgres configuration files: postgresql.conf and pg_hba.conf.

These files are only created once PostgreSQL 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

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

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

On most RPM-Based Distributions, all you should need to run is:

yum install jicmp

On Mandriva, you can install JICMP with the command:

urpmi --auto jicmp

If JICMP has not already been compiled on your RPM-based platform, you can build a native RPM from the source tarball like so:

rpmbuild -tb jicmp-X.X.X.tar.gz

If you are on a 64-bit platform, you can build a 64-bit RPM instead like so:

rpmbuild --target=x86_64 jicmp-X.X.X.tar.gz

On Debian or Ubuntu, you can install JICMP through apt:

sudo apt-get install libicmp-jni

To build from source, download the latest source tarball from SourceForge, unpack it, and run the usual:

./configure
make
make install

Download the appropriate package for your Solaris version from the SourceForge download page for OpenNMS.

Then, install the package using pkgadd:

# cd /usr/local
# gzip -d opennms-*-local.gz
# pkgadd -d `pwd`/opennms-*-local

OpenNMS is supported on Mac OS X via the Fink project.

Once you've installed Fink, you should be able to install OpenNMS by running:

fink install opennms

OpenNMS is supported on Windows as well, although the lack of true package management makes it a bit more work to maintain.

To install on Windows, download the latest standalone-opennms-installer-X.X.X.jar file from the OpenNMS SourceForge download page.

You should be able to then just double-click the jar file in Explorer, and follow the instructions in the install wizard.

Once you're done, you may want to make a pristine copy of the $OPENNMS_HOME/etc directory so it's easy to tell what's changed in later releases later.

There are a number of things you can do that can help ease the transition when doing upgrades.

--# this deletes any events that are not associated with outages
DELETE FROM events WHERE NOT EXISTS 
  (SELECT svclosteventid FROM outages WHERE svclosteventid = events.eventid  
UNION 
  SELECT svcregainedeventid FROM outages WHERE svcregainedeventid = events.eventid 
UNION 
  SELECT eventid FROM notifications WHERE eventid = events.eventid) 
AND eventtime < now() - interval '6 weeks';

pg_dump -U postgres -Fc -C -f opennms-database-backup.pg opennms

tar -C $OPENNMS_HOME -cvzf /tmp/opennms-etc-backup.tar.gz etc

install -Xms1024m -Xmx2048m -dis

If you have the OpenNMS Yum repositories configured, all you should need to do to get the new release is run:

sudo yum upgrade opennms

If you are comfortable letting your distribution give you OS updates along with OpenNMS, you can just run:

sudo yum upgrade

If you have the OpenNMS URPMI repositories configured, you can upgrade by running:

sudo urpmi --auto opennms

As with Yum, if you are comfortable letting URPMI give OS updates along with OpenNMS, you can run:

sudo urpmi --auto --auto-select opennms

You can upgrade RPM systems manually by downloading the RPM packages from SourceForge and upgrade them by running:

sudo rpm -Uvh opennms*.rpm

If your Debian or Ubuntu system is configured with the OpenNMS Apt repository, you should just need to run:

sudo apt-get update
sudo apt-get -u install opennms

Since there is no automated installation/upgrade procedure for Windows, you will have to do some preparation before installing the latest version.

Once you've cleaned up the etc and lib directories, the next step is to download the latest standalone-opennms-installer-X.X.X.jar from the OpenNMS SourceForge download page.

Next, run the installer jar, and install over your existing OpenNMS location.

If you backed up the pristine etc directory on your previous installation, you can compare it to the current one to see if there are any configuration changes you wish to integrate into your new install.

Copy your backed up etc directory back into the $OPENNMS_HOME/etc directory.

You should now be able to run your upgraded OpenNMS.

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

# $OPENNMS_HOME/bin/runjava -s

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's java executable>

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:

# /sbin/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

OpenNMS is not terribly heavy on CPU usage, but is extremely I/O-bound, and will also take advantage of as much RAM as you can give it. OpenNMS itself doesn't use a huge amount of RAM per-node, but allowing the OS to cache filesystem interaction makes a very large performance difference.

If you are running on hardware RAID, it is strongly recommended that you have a battery-backed write cache. For example, one user reported that on an HP DL380 G4, the I/O wait of the server dropped from 15% to essentially nothing, using a 128MB battery-backed write cache.

You will get the most out of OpenNMS if you spread your I/O out into multiple spindles and/or separate disks/channels.

sudo /etc/init.d/postgresql stop
sudo mv /var/lib/pgsql/data/pg_xlog /mnt/xlogspindle/pg_xlog
sudo ln -s /mnt/xlogspindle/pg_xlog /var/lib/pgsql/data/pg_xlog
sudo /etc/init.d/postgresql start

sudo mv /var/opennms /mnt/rrdspindle/opennms
sudo rm -f /opt/opennms/share
sudo ln -s /mnt/rrdspindle/opennms /opt/opennms/share

If you are dedicating spindles or drives to OpenNMS, you can mount them with the noatime option on Linux or Solaris for an additional performance boost. This will keep the OS from updating the file access time on individual RRD and database files every time they are used.

On Linux, you do so by editing /etc/fstab and adding noatime to the options section of the filesystem. For example:

LABEL=/                           /                           ext3    defaults         1 1
LABEL=/var/opennms                /var/opennms                ext3    defaults,noatime 1 2
LABEL=/var/lib/pgsql              /var/lib/pgsql              ext3    defaults,noatime 1 2
LABEL=/var/lib/pgsql/data/pg_xlog /var/lib/pgsql/data/pg_xlog ext3    defaults,noatime 1 2

On Solaris, you edit /etc/vfstab and add noatime as an option at the end of the mountpoint information, like so:

/dev/dsk/c1d0s0 /dev/rdsk/c1d0s0 /                            ufs 1 no
/dev/dsk/c1d1s0 /dev/rdsk/c1d1s0 /opt/opennms/share            ufs 2 no noatime
/dev/dsk/c1d2s0 /dev/rdsk/c1d2s0 /usr/local/pgsql/data         ufs 2 no noatime
/dev/dsk/c1d3s0 /dev/rdsk/c1d3s0 /usr/local/pgsql/data/pg_xlog ufs 2 no noatime

Use a mirrored stripe (RAID-10), with enough disks to handle the amount of data you need to collect. A single disk, a pair of mirrored disks (RAID-1), or a RAID-5 is only appropriate for an installation doing a small amount of data collection.

There are a number of other things you can do to tune PostgreSQL. For a good writeup on PostgreSQL performance tuning, see this page at revsys.com.

shared_buffers = 20000
work_mem = 16348
maintenance_work_mem = 65536
vacuum_cost_delay = 50
checkpoint_segments = 20
checkpoint_timeout = 900
wal_buffers = 64
stats_start_collector = on
stats_row_level = on
autovacuum = on

work_mem = 100MB
maintenance_work_mem = 128MB

#max_fsm_pages = 204800		# min max_fsm_relations*16, 6 bytes each
max_fsm_pages = 2048000
#max_fsm_relations = 1000		# min 100, ~70 bytes each
max_fsm_relations = 10000

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

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:

The PostgreSQL server cannot access the iplike.so file. This could be due to the file itself not having appropriate permissions for the user that PostgreSQL runs as and/or one or more of the parent directories of the iplike.so not having appropriate permissions.

This error is seen even when running the installer as root because it is not OpenNMS nor the installer that cannot access the iplike.so file, but the PostgreSQL database. The installer instructs the PostgreSQL database to load the iplike.so and the PostgreSQL database server usually runs as a non-root user, so it is subject to filesystem access control checks like any other normal user. This is commonly seen when people install OpenNMS into a home directory for root or another user and the permissions on that home directory do not allow users other than the owner of the directory access.

The latter part of the error could be something like "<path>/iplike.so: cannot open shared object file: No such file or directory" or "ld.so.1: postgres: fatal: <path>/iplike.so: wrong ELF class: ELFCLASS32".

The PostgreSQL server cannot load the iplike.so file. This is almost always caused by the PostgreSQL server and the iplike.so file being compiled for different processor instruction sets. This is commonly seen when the PostgreSQL server is compiled to use a 64-bit instruction set but the OpenNMS iplike.so shared object is compiled for a 32-bit instruction set, although the opposite is possible, as well. You can use the "file" command on iplike.so and the postmaster binary with PostgreSQL to check their instruction sets.

The easiest solution is to see if there is a packaged version of OpenNMS compiled for the same instruction set (32- or 64-bit) as your PostgreSQL server. The next easiest method for most users is to switch the PostgreSQL server to match the instruction set that the iplike.so file was compiled for. For advanced users, you can compile OpenNMS yourself to fit the processor set that you need. See this post to the discuss list for some pointers.

This error means the database was not created properly. Since the installer script is supposed to create the database, one might assume it is a problem with OpenNMS, but instead it is an issue with the SELinux portions of Red Hat 4 (and CentOS 4). Basically, the postgres init_db command is not able to write to /dev/null, and it fails without a useful error message.

To get around this, run the following commands:

Note that step 2 will delete any changes you made to the postgresql configuration files and you'll need to redo them.

An exact example of this error is: "java.io.FileNotFoundException: /opt/opennms/etc/users.xml (Permission denied)".

If the above error happens when using admin functions through the web interface, such as managing users, notifications, and adding nodes, then the Tomcat web server is running as a non-root user but you haven't changed the permissions on the configuration files so the Tomcat user can access them. Go back and follow the instructions earlier in the install guide on setting up Tomcat to run as a non-root user.

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 entries on the wiki, the bug database and, of course, Google, before posting to a mailing list.

OpenNMS maintains a number of active mailing lists on SourceForge:

The OpenNMS mailing lists are also archived at gmane.org.

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.