Installation:Yum

From OpenNMS

Installing on RedHat-Based Distributions

These instructions cover installation for most Yum-Based distributions (Fedora Core, RedHat Enterprise Linux, and CentOS).

NOTE: OpenNMS stable is not yet available in this repository, as the 1.2.x RPM packages were not really designed for Yum delivery and dependency management. For now, only testing, unstable and snapshot repositories have the OpenNMS packages.

Also, if you want to use Yum on RHEL4 instead of uptodate, see the Yum on RHEL4 page.

Install the Yum Repository RPM

Preparation: Yum Fastest Mirror Plugin

Before you start, you may want to install the yum-fastestmirror RPM if your distro supports it. This can often speed up downloads of large packages. See the CentOS Wiki for more details.

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

Releases

There are 4 types of releases available through yum:

stable 

the latest officially released stable version of OpenNMS (currently disabled)

unstable 

the latest officially released development version of OpenNMS (note: this is the one that you should install until 1.6 is released)

testing 

a nightly build of the code that will be part of the next stable version of OpenNMS

snapshot 

a nightly build of the very latest development version of OpenNMS

Install Repository RPMs

First, install the appropriate yum repository RPMs from the OpenNMS yum repository. Choose the release you want to use (stable, unstable, or nightly snapshot), and then install the distribution-specific RPM appropriate for your platform.

For example, on a Fedora Core 7 system, to install the latest snapshot release, you would use:

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

Another example, on a CentOS5 system, to install the latest unstable release, you would use:

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

For the time being the "unstable" repository contains the latest 1.5.x release which is actually reasonably stable (we are prepping for a 1.6 stable release). If you try to use the stable repository you will find that there is no "opennms" package to install. Once the 1.6 version is out it will become the stable version making this note wrong.

Once you've done so, yum should show opennms as available when you do a "yum list opennms":

 [user@localhost]$ sudo yum list opennms
 ...
 Available Packages
 opennms.noarch                           1.3.7-0.7377           opennms-snapshot

Note: if you are using older yum-based distributions (like CentOS 3, for example), you may need to append the yum configuration to yum.conf. Older versions of yum don't recognize /etc/yum.repos.d/ as a valid location for yum configuration. You can do this with cat, like so:

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

(Optional) Pre-Install PostgreSQL

While yum will do it automatically, installing PostgreSQL first ensures that the native IPLIKE code is used, instead of the pure stored-procedure version.

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

Depending on your distribution, you then run either "sudo /sbin/service postgresql start" or "sudo /sbin/service postgresql initdb" to make sure the database is initialized.

You can then follow the instructions below for making sure pg_hba.conf and postgresql.conf are configured properly, and (re)start the server.

Determine What to Install

As of version 1.3.7, OpenNMS is packaged as 5 RPMs:

opennms-core

The core OpenNMS code, responsible for network discovery, polling, data collection, notification, and more.

opennms-docs

Documentation.

opennms-webapp-jetty

The OpenNMS web UI, designed to be started by the opennms-core engine.

opennms-webapp-standalone

The OpenNMS web UI, designed to be deployed to Tomcat or another suitable servlet container.

opennms

A convenience package which installs everything you need for a functional OpenNMS installation on a single system.

It is recommended that you install the opennms package unless you need to do something special with splitting OpenNMS across multiple servers.

Install OpenNMS

Just run "yum install" for the package(s) you want:

 [user@localhost]$ sudo yum install opennms
 ...
 Setting up repositories
 opennms-snapshot-rhel5    100% |=========================| 1.1 kB    00:00     
 opennms-unstable-common   100% |=========================| 1.1 kB    00:00     
 opennms-stable-common     100% |=========================| 1.1 kB    00:00     
 opennms-unstable-rhel5    100% |=========================| 1.1 kB    00:00     
 ...
 Resolving Dependencies
 --> Populating transaction set with selected packages. Please wait.
 ---> Downloading header for opennms to pack into transaction set.
 opennms-1.3.7-0.7377.noar 100% |=========================| 5.4 kB    00:00     
 ---> Package opennms.noarch 0:1.3.7-0.7377 set to be updated
 --> Running transaction check
 --> Processing Dependency: opennms-core = 1.3.7-0.7377 for package: opennms
 ..
 Dependencies Resolved
 
 =============================================================================
  Package                 Arch       Version          Repository        Size 
 =============================================================================
 Installing:
  opennms                 noarch     1.3.7-0.7377     opennms-snapshot-common  5.9 k
 Installing for dependencies:
  jicmp                   i386       1.0-1            opennms-stable-rhel5   31 k
  opennms-core            noarch     1.3.7-0.7377     opennms-snapshot-common   48 M
  opennms-webapp-jetty    noarch     1.3.7-0.7377     opennms-snapshot-common   27 M
  postgresql              i386       8.1.9-1.el5      updates           2.8 M
  postgresql-server       i386       8.1.9-1.el5      updates           4.0 M
 
 Transaction Summary
 =============================================================================
 Install      6 Package(s)         
 Update       0 Package(s)         
 Remove       0 Package(s)         
 
 Total download size: 82 M
 Is this ok [y/N]: y
 Downloading Packages:
 (1/6): opennms-core-1.3.7 100% |=========================|  48 MB    03:57     
 ...
 Running Transaction
   Installing: postgresql                   ######################### [1/6] 
   Installing: postgresql-server            ######################### [2/6] 
   Installing: jicmp                        ######################### [3/6] 
   Installing: opennms-core                 ######################### [4/6] 
   Installing: opennms-webapp-jetty         ######################### [5/6] 
   Installing: opennms                      ######################### [6/6] 
 - moving *.sql.rpmnew files (if any)... done
 - checking for old update files... done
 
  *** Installation complete.  You must still run the installer and
  *** make a few other changes before you start OpenNMS.  See the
  *** install guide and release notes for details.
 
 Installed: opennms.noarch 0:1.3.7-0.7377
 Dependency Installed: jicmp.i386 0:1.0-1 opennms-core.noarch 0:1.3.7-0.7377 opennms-webapp-jetty.noarch 0:1.3.7-0.7377 postgresql.i386 0:8.1.9-1.el5 postgresql-server.i386 0:8.1.9-1.el5
 Complete!

Disable the OpenNMS Repository (If Necessary)

Some RPM-based distributions do an automatic yum update from cron, so you may want to disable the OpenNMS repositories until you're prepared to upgrade, since there are generally a few steps that need to be performed on an upgrade. To do so, edit the /etc/yum.repos.d/opennms*.repo files, and add:

 enabled=0

...inside each [opennms-*] bracketed section.

Configure OpenNMS

First, for the purposes of convenience, we are going to set the $OPENNMS_HOME environment variable before running any commands.

 export OPENNMS_HOME=/opt/opennms

(If you are not using a bourne-compatible shell, you may need to use different syntax.)

Configure Your Database

OpenNMS needs to be able to connect to PostgreSQL as the "postgres" user (by default) over a TCP/IP connection.

RedHat-based systems

/etc/init.d/postgresql start

/sbin/service postgresql start

pg_hba.conf and postgresql.conf are in /var/lib/pgsql/data

Debian-based systems

/etc/init.d/postgresql-X.X start

pg_hba.conf and postgresql.conf are in /etc/postgresql/X.X/main

Mac OS X (Fink)

/sw/bin/pgsql.sh start

Edit pg_hba.conf to Allow postgres to Authenticate

To allow the "postgres" user to connect, you will need to edit your database's pg_hba.conf file, which is usually created on installation or the first startup of PostgreSQL, depending on your distribution: By default, it will have something like this at the bottom:

 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 "ident sameuser" to "trust":

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

Edit postgresql.conf to Allow TCP/IP Connections

You may also need to change the postgresql.conf to allow TCP/IP connections, if it cannot do so already. On older PostgreSQL versions, this is enabled with the flag:

 tcpip_socket = true

On newer PostgreSQL versions, this is enabled with:

 # you can use "*" to listen on all addresses
 listen_addresses = 'localhost'

Restart the Database

Once you've made these changes, you need to restart your database.

Create the opennms Database

If not done, use "sudo -u postgres createdb -U postgres -E UNICODE opennms" to create the database in postgres.

Insert the IPLIKE Stored Procedure in the Database

If this is your first time installing OpenNMS or iplike, you should make sure that iplike is configured in your database. First you need to install the iplike package from OpenNMS yum repositories with

 yum install iplike

If the OpenNMS database is already configure, you good to go. If not, you have to manually issue

 install_iplike.sh

Tell OpenNMS Where to Find Java

OpenNMS needs to know where to find Java to be able to start up. To tell it how to do so, you run $OPENNMS_HOME/bin/runjava like so:

 $OPENNMS_HOME/bin/runjava -s

This will search $JAVA_HOME and other common locations for your JDK. If you wish to use a specific JDK, you can run it with the -S flag instead:

 $OPENNMS_HOME/bin/runjava -S /usr/java/jdk1.5.0_12/bin/java

Add the JAVA_HOME in /etc/default/opennms

 JAVA_HOME=/usr

Initialize OpenNMS and the Database

Next, you need to run the OpenNMS installer, which will initialize the OpenNMS database, and do some other basic setup. Upon upgrade, you should run this command again to make sure your database schema and other things required at startup are up-to-date.

In most cases, you can just run:

 $OPENNMS_HOME/bin/install -dis

Sometimes you may need to tell OpenNMS where to find libjicmp.so; in that case, you can use the -l option (OpenNMS 1.3.5 and higher):

 # i386 example
 $OPENNMS_HOME/bin/install -dis -l /usr/lib/jni:/usr/lib
 # x86_64 example
 $OPENNMS_HOME/bin/install -dis -l /usr/lib64/jni:/usr/lib64

Configure Tomcat (OpenNMS 1.2.x or Older Only)

If you are using an older release of OpenNMS, you will need to edit the tomcat configuration to start as root, and potentially to look for the right JVM.

Debian + Tomcat4

Edit /etc/default/tomcat4 make sure that JAVA_HOME points to your Sun JVM, and that tomcat is started as root.

 TOMCAT4_USER=root
 JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun

Also, by default, tomcat4 comes configured to look for a "tomcat-docs" webapp, even if it is not installed. If you do not install the tomcat4-webapps package, you will need to edit /etc/tomcat4/server.xml and comment out the Context path="/tomcat-docs" section:

 <!--
 <Context path="/tomcat-docs" docBase="tomcat-docs" debug="0">
   <Resources className="org.apache.naming.resources.FileDirContext" allowLinking="true" />
 </Context>
 -->

Discover Your Network

Finding Hosts

First, OpenNMS needs to know which devices (or, "nodes") you want it to discover. To discover nodes, OpenNMS does a ping sweep based on the $OPENNMS_HOME/etc/discovery-configuration.xml file, and for any IP address that responds, it will start monitoring. In the most common case, all you need to do is change the include-range to match your IP address range.

<discovery-configuration threads="1" packets-per-second="1"
    initial-sleep-time="30000" restart-sleep-time="86400000"
    retries="1" timeout="2000">

    <include-range>
        <begin>192.168.0.1</begin>
        <end>192.168.0.254</end>
    </include-range>

</discovery-configuration>

For more detailed information on discovery configuration, see Discovery.

Start OpenNMS

You should have a basic OpenNMS installation ready now, so start it up:

 sudo /etc/init.d/opennms start

As of OpenNMS 1.3.7, by default, the web UI will come up using the embedded Jetty servlet container, on port 8980. Open your browser and point it at:

 http://yourhost:8980/opennms/

the user name and password are both "admin" to start.

Get Notifications When Problems Occur

To get started, we need to configure the main admin user to have a valid e-mail address.

1. log in as admin
2. go to Admin in the menu bar
3. set the Notification Status radio button to On and click the Update button
4. go to Configure Users, Groups and Roles and then Configure Users
5. click the icon under "Modify" for the admin user
6. set the Email address, and click the Finish button

This should get OpenNMS configured to send the default notifications to the administrator e-mail address.

Notifications are extremely flexible and can be configured to do much more complex escalations, scheduled outages, and user-management. Detailed instructions are available in the Notification Configuration How-To.

==