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.

Startup

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

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 127.0.0.1/32 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 127.0.0.1/32 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.

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.

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.

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:

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

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/install_iplike.sh -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 (127.0.0.1), 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:

This example would add permitted access from the C-class network at: 12.34.56.00 through 12.34.56.255, 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

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