From OpenNMS
Jump to: navigation, search

Warning.png Official Install Guide

With OpenNMS Horizon we have now a version controlled official install guide which can be found here: This wiki is going to be deprecated.

This tutorial covers installation for Linux distributions that make use of the YUM packaging system, including Fedora® , Red Hat Enterprise Linux® and CentOS.

Select Your Release and Distribution

In order to tailor this tutorial to your distribution, please specify the release you decided upon previously, as well as your distribution version:

Hint: Please make sure you've Java Script activated to have a more convenient wiki page for your linux distribution. Release in OpenNMS means, for example, "stable" or "snapshot".

Installing the Repository RPM

The first step is to install the "opennms-repo" RPM appropriate for your distribution. This contains the information YUM needs to get OpenNMS package information for installing.

To do so, find the appropriate release RPM from

Then all you should need to do is install that repo package (as root):

 rpm -Uvh

Note.png Try It! Check for OpenNMS Packages

Once you've installed the distribution-specific RPM package of your choice, a query of the YUM database should show OpenNMS as an available install option when you run yum search opennms:

 [user@opennms -]$ rpm -Uvh \
 Preparing...                ####################################### [100%]
 1:opennms-repo-RELEASE-DISTRIBUTION ####################################### [100%]
 [user@opennms ~]$ yum search opennms
 Loaded plugins: fastestmirror
 ====================== Matched: opennms =================================
 mib2opennms.i386: Generate OpenNMS Events from MIB Traps
 mib2opennms.x86_64: Generate OpenNMS Events from MIB Traps
 opennms.noarch: Enterprise-grade Network Management Platform
 opennms-core.noarch: The core OpenNMS backend.

Preparing the Database for OpenNMS

Before installing OpenNMS itself, you will want to install PostgreSQL, and do a few things to make sure PostgreSQL is working properly.

Installing PostgreSQL

First, you'll want to install PostgreSQL. It is included in all of the major YUM-based distributions. To install, just run the "yum install" command (as root):

 yum install postgresql postgresql-server

Note: The CentOS repository contains an older PostgreSQL v8.4. Newer versions of PostgreSQL are generally very safe and add a lot of great features and performance enhancements. To install a newer version, such as v9.3, follow the instructions on the PostgreSQL RedHat family installation page.


Onec PostgreSQL is installed, the first thing you'll need to do is making sure PostgreSQL starts up properly. On most distributions, you can just run (as root):

 /sbin/service postgresql start

Some distributions will require you to first initialize the database. If you see an error when running that command, try initdb first, and then start again:

 /sbin/service postgresql initdb
 /sbin/service postgresql start

Then, to ensure that PostgreSQL will start after a reboot, use the "chkconfig" command to enable start on bootup:

 /sbin/chkconfig postgresql on

NOTE: Redhat/CentOS 7 and variants use a different method of starting services. The procedure to initialize and start the database are (installs may differ here):

 /usr/pgsql-9.4/bin/postgresql94-setup initdb
 /bin/systemctl start postgresql-9.4.service
 /bin/systemctl enable postgresql-9.4.service

Allowing User Access to the Database

By default, PostgreSQL only allows you to connect if you are logged in to the local account name that matches the PostgreSQL user. Since OpenNMS runs as root, it cannot connect as a "postgres" or "opennms" user by default, so we have to change the configuration to allow that.

To do so, you will need to edit your database's pg_hba.conf file. On many default installations it can be found in the directory /var/lib/pgsql/data/, however you may need to consult your distribution's PostgreSQL documentation for the location of this file if this is not the case.

By default pg_hba.conf should have entries similar to the following at the bottom of the file:

local   all         all                               ident sameuser
host    all         all          ident sameuser
host    all         all         ::1/128               ident sameuser

You will need to change these entries to resemble the following:

local   all         all                               trust
host    all         all          trust
host    all         all         ::1/128               trust

Once you have finished making changes, restart the database (as root):

 /sbin/service postgresql restart

Additionally, while it's beyond the scope of this beginning tutorial, you may want to check the PostgreSQL section of the Performance Tuning page to get the most out of your database installation.

Warning.png Security Implications

The above changes to the default PostgreSQL configuration will make it easy to install OpenNMS on your server, but it also allows for anyone with a local user account to have full access to said DB. As this guide is a quick start, the assumption is that the server is limited to users of the OpenNMS system. If this is not the case, you should consult the PostgreSQL documentation for setting a more restrictive environment.

Installing the JDK

While we provide a JDK in our YUM repository as a fallback, it is very much recommended that you install the latest stable Java 7 JDK from Oracle for the best performance.

Warning.png Java 8 is required beginning with OpenNMS 16

Starting with release 16, OpenNMS requires Java 8. Previous releases are not supported on Java 8. Please use Java 7 for OpenNMS 15.x and below.

To do so, go to the Oracle Java 8 SE JDK download page or the Oracle Java 7 SE JDK download page, accept the license if you agree, choose the platform and architecture that's appropriate to your distribution (Linux x86 or Linux x64), and then download the jdk-*-rpm.bin file.

Once it has finished downloading, execute it from the command-line (it is a shell archive), and then install the resulting JDK rpm.

Note.png Try It! Install the JDK

After downloading the appropriate JDK file from Oracle, run the shell archive and install the RPM that gets unpacked.

[root@test ~]# rpm -ivh jdk-7u45-linux-i586.rpm
Preparing...                ########################################### [100%]
   1:jdk                    ########################################### [100%]
Unpacking JAR files...
[root@test ~]#

Installing OpenNMS

With all the prerequisites taken care of, you can now install OpenNMS. The OpenNMS software is not a single package, but a combination of many components. The YUM packaging system will download and install all of these components and their dependencies, if they are not already installed on your system.

There are many packages available in the OpenNMS YUM repository, but the easiest way to get started is to install the "opennms" package. This will pull in everything you need to have a working OpenNMS, including the OpenNMS core, web UI, and a set of common plugins.

Note.png Try It! Install OpenNMS

Install OpenNMS, using the "yum install" command (as root):

 yum -y install opennms

You should see something like this:

Resolving Dependencies
--> Running transaction check
---> Package opennms.noarch 0:{{StableVersion}}-1 will be installed
---> Package jicmp.x86_64 0:1.2.1-1 will be installed
---> Package jicmp6.x86_64 0:1.0.1-1 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

 Package          Arch   Version             Repository               Size
 opennms          noarch {{StableVersion}}-1            opennms-stable-common   2.2 k
Installing for dependencies:
 jicmp            x86_64 1.2.1-1             opennms-stable-rhel6     44 k
 jicmp6           x86_64 1.0.1-1             opennms-stable-rhel6     27 k
 opennms-core     noarch {{StableVersion}}-1            opennms-stable-common   230 M
Transaction Summary
Install       9 Package(s)

Total download size: 378 M
Installed size: 693 M
Downloading Packages:
(8/9): opennms-core-{{StableVersion}}-1.noarch.rpm             | 230 MB     07:23     
(9/9): opennms-webapp-jetty-{{StableVersion}}-1.noarch.rpm     |  75 MB     02:16     
Total                                      528 kB/s | 378 MB     12:13     
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : jicmp6-1.0.1-1.x86_64                                   1/9 
  Installing : jicmp-1.2.1-1.x86_64                                    2/9 
  Installing : opennms-{{StableVersion}}-1.noarch                                 9/9 

  opennms.noarch 0:{{StableVersion}}-1

Dependency Installed:
  jicmp.x86_64 0:1.2.1-1                                                   
  jicmp6.x86_64 0:1.0.1-1                                                  
  opennms-core.noarch 0:{{StableVersion}}-1
  opennms-webapp-jetty.noarch 0:{{StableVersion}}-1


Post-Install Configuration

Disable YUM Updates

Some distributions that use YUM/RPM as a package management system will attempt an automatic update at regular intervals. A system administrator could potentially run a manual update and inadvertently upgrade OpenNMS resulting in a misconfiguration or complete failure.

To avoid these scenarios, you may want to disable the OpenNMS repositories after a successful installation by editing the "/etc/yum.repos.d/opennms*" file and adding enabled=0 inside each [opennms-*] section. This can just as easily be changed back when it's time to upgrade.

Configure Java

Next, you need to tell OpenNMS which Java you want it to use, using the "$OPENNMS_HOME/bin/runjava" command. If you installed the recommended Sun/Oracle JDK, all you should need to do is point it at /usr/java/latest:

 $OPENNMS_HOME/bin/runjava -S /usr/java/latest/bin/java

Create/Update the OpenNMS Database

Whenever you install OpenNMS or upgrade it, you should run the "$OPENNMS_HOME/bin/install" command, to create the OpenNMS database, or update it to the latest version. The install command takes many options, but in most cases all you should need is:

  • -d - to update the database
  • -i - to insert any default data that belongs in the database
  • -s - to create or update the stored procedures OpenNMS uses for certain kinds of data access

Note.png Try It! Create the Database

Now it's time to create and configure the OpenNMS database. To do so, run the following command (as root):

 $OPENNMS_HOME/bin/install -dis

You should get output something like this:

OpenNMS Installer

Configures PostgreSQL tables, users, and other miscellaneous settings.

- searching for jicmp:
  - trying to load /usr/lib64/ OK
- searching for jicmp6:
  - trying to load /usr/lib64/ OK
- Running migration for changelog: URL [...]
INFO 2/1/12 12:48 PM:liquibase: Successfully acquired change log lock
INFO 2/1/12 12:48 PM:liquibase: Creating database history table
INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog
INFO 2/1/12 12:48 PM:liquibase: Reading from databasechangelog
INFO 2/1/12 12:48 PM:liquibase: ChangeSet ran successfully in 54ms
INFO 2/1/12 12:49 PM:liquibase: Successfully released change log lock
- inserting PL/pgSQL iplike function... OK

Installer completed successfully!

(Optional) Configure IPLIKE

OpenNMS uses a PostgreSQL stored procedure called "IPLIKE" which provides an API for easily performing complicated IP address queries. By default, OpenNMS installs a version of IPLIKE that is compatible with all versions of PostgreSQL, but there is a platform-specific version of IPLIKE with much better performance. While it is optional, it is recommended that you install the "iplike" package from YUM for performance reasons.

Note.png Try It! Install IPLIKE

To do so, install the "iplike" package with yum, like so (as root):

 yum -y install iplike

You should see it finish with something like this:

Installed size: 30 k
Downloading Packages:
iplike-2.0.2-1rhel6.x86_64.rpm                  |  16 kB     00:00     
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : iplike-2.0.2-1.el6.x86_64                           1/1 
- installing iplike into the opennms db (if it exists)... OK

  iplike.x86_64 0:2.0.2-1.el6                                          


If you don't see "OK" next to the "installing iplike into the opennms db" line, for example if you changed the default PostgreSQL authentication options for security reasons, then you may have to run the script manually. For details on the options available to you when running manually, run:

 /usr/sbin/ -h

Configure Your Firewall

Depending on your installation, some distributions will disable connecting to unknown IP ports by default.

Assuming that the iptables service is enabled, in order to permit connections from IP address other than the localhost (, it is necessary to add a rule to the configuration file to allow OpenNMS.

Add a Firewall Exception for OpenNMS

In the case of RHEL and CentOS, this file is: /etc/sysconfig/iptables. If you edit this file, you should see 1 or more lines starting with "-A INPUT" and containing a destination port ("--dport"). You will want to make a copy of one of these lines, and changed the destination port to 8980, like so:

 -A INPUT -p icmp -j ACCEPT
 -A INPUT -i lo -j ACCEPT
 -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
 -A INPUT -m state --state NEW -m tcp -p tcp --dport 8980 -j ACCEPT
 -A INPUT -j REJECT --reject-with icmp-host-prohibited

Note that some versions of CentOS and RHEL, instead of "INPUT" you will see something like "RH-Firewall-1-INPUT". These are equivalent. For the technical details, see the man page for iptables.

Restricting Connections to a Specific Subnet

It is common, however to restrict such connections only from a trusted range of IP addresses, and the addition to iptables of an optional -s address/mask is probably a better practice:

 -A INPUT -p icmp -j ACCEPT
 -A INPUT -i lo -j ACCEPT
 -A INPUT -m state --state NEW -m tcp -p tcp --dport 22 -j ACCEPT
 -A INPUT -m state --state NEW -m tcp -p tcp -s --dport 8980 -j ACCEPT
 -A INPUT -j REJECT --reject-with icmp-host-prohibited

This example would add permitted access from the C-class network at: through, being specified using CIDR notation.

Restart the Firewall

Once you have made your edits, you can restart the firewall by running the service command (as root):

 /sbin/service iptables restart

Before logging out, try connecting to your server again to confirm connectivity.

Start OpenNMS and Connect to the Web UI

You can now start OpenNMS using the "service" command (as root):

 /sbin/service opennms start

Note.png Try It! Connect to the Web UI

Try starting OpenNMS, and connecting to the web UI.

 /sbin/service opennms start

You should be able to go to http://YOUR-OPENNMS-IP:8980/opennms/ in your browser and see the web UI. The default username and password are both "admin" so enter them in when you see the login prompt.

Change the Administrator Password

As mentioned above, the default username is "admin" and the default password is "admin" as well. It is recommended that you change the administrator user's password, for security reasons. To do so, log in to the web UI and then click on the username (admin) in the upper-right corner, and then click "Change Password." Enter the old and new passwords in the prompt, and click "OK."

Note.png Try It! Change the Default Password

To change the default password, browse to http://YOUR-OPENNMS-IP:8980/opennms/ and log in as administrator:

Log In as Admin

...then click the admin username in the upper-right corner:

Edit Admin User

...and finally, click "Change Password," then fill out the form.

Next-arrow.png Next Step: Scan Your First Device

Now that OpenNMS is installed, it's time to scan your first device! Let's move on to the Capability Scanning tutorial.