Installation:Debian

From OpenNMS
Jump to: navigation, search


This tutorial covers installation of OpenNMS on Debian, and Debian-derived distributions like Ubuntu.

This page was tested with:

 * OpenNMS 1.12.1 on Ubuntu 12.04.3 LTS 64-bit

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 have JavaScript activated in your browser to have a more convenient wiki page for your linux distribution.

Release in OpenNMS means: stable, testing, unstable, snapshot

Configure APT

Adding a Repository

To set up APT to talk to the OpenNMS repository, you'll need to create a file called "opennms.list" within the "/etc/apt/sources.list.d" directory, with the following contents to install OpenNMS stable release:

# contents of /etc/apt/sources.list.d/opennms.list
deb http://debian.opennms.org stable main
deb-src http://debian.opennms.org stable main

The following commands will create this file for you:

cat << EOF | sudo tee /etc/apt/sources.list.d/opennms.list
# contents of /etc/apt/sources.list.d/opennms.list
deb http://debian.opennms.org stable main
deb-src http://debian.opennms.org stable main
EOF

Replace stable to install other releases of OpenNMS

  • testing installs from branches/release-14.0.1
  • snapshot installs from branches/develop
  • Development feature branches can be installed using branches/BRANCH-NAME which are listed in: http://debian.opennms.org/dists/branches

Adding the OpenNMS PGP Key to APT

Packages within the APT system are cryptographically signed to ensure their integrity. This step ensures the integrity of the file you've downloaded, as well as a reference to guarantee that the file is provided by who it says it was. These features are useful at install-time as well as during future upgrades.

To install the OpenNMS PGP key into your system, type the following at a command prompt:

wget -O - http://debian.opennms.org/OPENNMS-GPG-KEY | sudo apt-key add -

Download and verify OpenNMS package catalogs have been downloaded

Then you should be able to run
sudo apt-get update
to get the latest list of packages in your APT repositories, including those in the OpenNMS repository.

Note.png Try It! Check for OpenNMS Packages

Once you've configured APT for the release of your choice, a query of the APT database should show a number of OpenNMS packages as available install options when you run "apt-cache search opennms", for example:

sudo apt-get update
apt-cache search opennms

You should see a list of OpenNMS-related packages:

[user@host tmp] apt-cache search opennms
mib2events - Create OpenNMS configuration from MIB files
opennms-plugin-collector-juniper-tca - Enterprise-grade Open-source Network Management Platform (Juniper TCA Collection Support)
opennms-plugin-protocol-radius - Enterprise-grade Open-source Network Management Platform (RADIUS Protocol Support)
opennms-contrib - Enterprise-grade Open-source Network Management Platform (Contrib)
libopennmsdeps-java - Enterprise-grade Open-source Network Management Platform (Required Libraries)
(...more will display...)

To confirm the version of OpenNMS that will be installed, query the OpenNMS package itself for details. This version should match the expected desired version (stable, unstable, etc.). In the example below, the current stable version of OpenNMS (as of October 2, 2013), ver. 1.12.1-1, is shown in the current package cache.

[user@host tmp] apt-cache show opennms
Package: opennms
Priority: optional
Section: contrib/net
Installed-Size: 32
Maintainer: Jeff Gehlbach <jeffg@opennms.org>
Architecture: all
Version: 1.12.1-1
...

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

The first thing you'll want to do is install the PostgreSQL database itself. On any Debian-based distribution, all you should have to do is install the "postgresql" package, and it will pull in anything it needs.

 sudo apt-get update
 sudo apt-get install postgresql

Determining Your PostgreSQL Version

The version of PostgreSQL that gets installed depends upon what version distribution you're running. You can see the version of PostgreSQL installed with the "pg_lsclusters" command. For the purposes of this tutorial, we'll set an environment variable on the shell to make things easier:

 PGVERSION=`pg_lsclusters -h | head -n 1 | cut -d' ' -f1`

Verification

Example output with PostgreSQL 9.1 installed:

echo $PGVERSION
9.1

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 the operating system's "postgres" or "opennms" users by default, so we have to change the configuration to allow that.

To allow connections as the postgres user to authenticate without a password, you first must change options in the pg_hba.conf file. On Debian-derived systems, this will be located at /etc/postgresql/$PGVERSION/main/pg_hba.conf, where "$PGVERSION" is the environment variable we set earlier containing the version of your PostgreSQL database.

Edit your "/etc/postgresql/$PGVERSION/main/pg_hba.conf" file now, as root. It should have entries similar to the following at the bottom.

sudo vi /etc/postgresql/$PGVERSION/main/pg_hba.conf

The following example is from PostgreSQL 9.1:

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     peer
# IPv4 local connections:
host    all             all             127.0.0.1/32            md5
# IPv6 local connections:
host    all             all             ::1/128                 md5
# Allow replication connections from localhost, by a user with the
# replication privilege.
#local   replication     postgres                                peer
#host    replication     postgres        127.0.0.1/32            md5
#host    replication     postgres        ::1/128                 md5

You will need to change these entries to replace the default authentication methods with the method "trust". The final result should be like the following.

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# OpenNMS change: configure local, IPv4 and IPv6 connections made from localhost to not require authentication

# "local" is for Unix domain socket connections only
local   all             all                                     trust # the default method is peer
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust # the default method is md5
# IPv6 local connections:
host    all             all             ::1/128                 trust # the default method is md5
# Allow replication connections from localhost, by a user with the
# replication privilege.
#local   replication     postgres                                peer
#host    replication     postgres        127.0.0.1/32            md5
#host    replication     postgres        ::1/128                 md5

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

sudo service postgresql restart

On older releases of Debian, you may need to instead run "sudo service postgresql-$PGVERSION restart"

On older releases of Ubuntu such as Ubuntu 10.04 with PostgreSQL 8.4, you may need to instead run "sudo service postgresql-$PGVERSION 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 Java

Warning.png Oracle JDK

Use of the Oracle JDK is still very much recommended, though the Debian packages do pull in the OpenJDK. If you experience issues, try using the Oracle JDK as a first step.

As of April 2013, it is recommended to use Java 7 if possible (see http://marc.info/?l=opennms-discuss&m=136551915425666&w=2).

Warning.png Java 8 not yet supported

While future versions of OpenNMS will support Java 8, the current stable 1.12 series of releases is not supported on Java 8. Please use Java 7.

Install the Java package with apt-get as root.

On Debian 6 stable (squeeze), Java 7 is not available so the Java 6 package "openjdk-6-jre" is used instead. On Ubuntu 11.10 or later, Java 7 is available in the standard Ubuntu repositories. Earlier versions of Ubuntu only have Java 6 available and so need to use the package "openjdk-6-jre".

# update the package list
sudo apt-get update

# Use Java 6 on Debian or older Ubuntu releases
sudo apt-get install openjdk-6-jre

# use Java 7 on Ubuntu 11.10 or later releases
sudo apt-get install openjdk-7-jre

Verification of the Java version

java -version

This is sample output using Java 7 on Ubuntu 12.04.3.

java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)

Verification of a local mail transfer agent

OpenNMS sends out e-mail by default through a local mail transfer agent listening on port 25. Confirm that a MTA (e.g. exim or postfix) is installed. One way to check for this is to telnet to port 25 on the server and ensure a SMTP banner is displayed.

If a MTA is not present, install it with the following command:

sudo apt-get install default-mta

For Debian, the default MTA is exim. Accept the default debconf configuration responses when configuring exim.

For Ubuntu, the default MTA is postfix. When asked what mail configuration to use, select the default option, "Internet Site" and the default hostname of the server on the next configuration page.

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

You can do so by running (as root):

sudo apt-get install opennms

The installer typically has two prompts: "The OpenNMS installer must now be run manually" and a warning that "IPLIKE installation failed". Please select "<Ok>" for both questions to continue.

The IPLIKE warning is normal, as this package will attempt to install itself into the OpenNMS database, but on a new install the database has not been configured yet. We will re-attempt the install later.

Note.png Try It! Install OpenNMS

Install OpenNMS, using the "sudo apt-get install opennms" command (as root).

sudo apt-get install opennms

You should see something like this:

Reading package lists... Done
Building dependency tree
Reading state information... Done
The following extra packages will be installed:
  heirloom-mailx iplike-pgsql91 jicmp jicmp6 libdbd-pg-perl libdbi-perl libgetopt-mixed-perl libnet-daemon-perl libnet-snmp-perl libopennms-java
  libopennmsdeps-java libplrpc-perl libxml2-utils opennms-common opennms-db opennms-server opennms-webapp-jetty
Suggested packages:
  exim4 mail-transport-agent libcrypt-des-perl libdigest-hmac-perl libio-socket-inet6-perl opennms-doc jrrd rrdtool postgresql-client-8.4
The following NEW packages will be installed:
  heirloom-mailx iplike-pgsql91 jicmp jicmp6 libdbd-pg-perl libdbi-perl libgetopt-mixed-perl libnet-daemon-perl libnet-snmp-perl libopennms-java
  libopennmsdeps-java libplrpc-perl libxml2-utils opennms opennms-common opennms-db opennms-server opennms-webapp-jetty
0 upgraded, 18 newly installed, 0 to remove and 0 not upgraded.
Need to get 219 MB of archives.
After this operation, 411 MB of additional disk space will be used.
Do you want to continue [Y/n]? y

Post-Install Configuration

Disable APT Updates

Some distributions that use APT 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/apt/sources.list.d/opennms*" file and commenting out each "deb" 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.

To have OpenNMS search for and auto-detect the JRE, run:

sudo $OPENNMS_HOME/bin/runjava -s

Example output:

runjava: Looking for an appropriate JRE...
runjava: Checking for an appropriate JRE in JAVA_HOME...
runjava: skipping... JAVA_HOME not set
runjava: Checking JRE in user's path: "/usr/bin/java"...
runjava: found an appropriate JRE in user's path: "/usr/bin/java"
runjava: value of "/usr/bin/java" stored in configuration file

To configure OpenNMS to use a specific JRE binary, use the "-S" with the path to the desired binary.

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

Create/Update the OpenNMS Database

Whenever you install OpenNMS or upgrade it, you should run the "sudo $OPENNMS_HOME/bin/install -dis" 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 are the three options below:

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

A warning "Failed to load the optional jrrd library." during installation is normal and not a problem, as jrrd use is optional. The installation should finish with the line "Installer completed successfully!".

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

sudo $OPENNMS_HOME/bin/install -dis

You should get output something like this:

==============================================================================
OpenNMS Installer
==============================================================================

Configures PostgreSQL tables, users, and other miscellaneous settings.

- searching for libjicmp.so:
  - trying to load /libjicmp.so: NO
  - trying to load /usr/share/opennms/lib/libjicmp.so: NO
  - trying to load /usr/share/opennms/lib/linux64/libjicmp.so: NO
  - trying to load /usr/java/packages/lib/amd64/libjicmp.so: NO
  - trying to load /usr/lib/jni/libjicmp.so: OK
- searching for libjicmp6.so:
  - trying to load /libjicmp6.so: NO
  - trying to load /usr/share/opennms/lib/libjicmp6.so: NO
  - trying to load /usr/share/opennms/lib/linux64/libjicmp6.so: NO
  - trying to load /usr/java/packages/lib/amd64/libjicmp6.so: NO
  - trying to load /usr/lib/jni/libjicmp6.so: OK
- searching for libjrrd.so:
  - trying to load /libjrrd.so: NO

...

Installer completed successfully!


Warning.png Java Network unreachable

If you try to install OpenNMS on Debian 6.0 Squeeze you may get a PostgreSQL error Network unreachable. In Debian 6.0 Squeeze Java applications are not allowed to connect to 127.0.0.1. It is only possible to connect to ::1 by default. The bug is described in http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=560044.

It seems that adding "-Djava.net.preferIPv4Stack=true" to the list of arguments in file $OPENNMS_HOME/bin/install solves the problem.

(Optional but recommended) Install IPLIKE database stored procedure

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 configure the iplike package from APT for performance reasons.

The appropriate IPLIKE package (eg, iplike-pgsql84, iplike-pgsql90, etc.) for your database should already have installed when you installed the main "opennms" package. All you should need to do is re-run the "install_iplike" shell script (as root):

sudo /usr/sbin/install_iplike.sh

This is the expected output if the installation was successful:

CREATE FUNCTION

Verify connectivity to the OpenNMS database

At this point, you can check the network listener and authentication changes, as well as whether or not your DB creation worked properly by trying to connect to the OpenNMS database as the postgres database user from localhost.

psql -U postgres --host=localhost opennms

If you are presented with a prompt that looks like opennms=#, you can type \q and quit the PostgreSQL shell as the database connection was successful. If this was not successful, you will need to review your PostgreSQL configuration before continuing.

Start OpenNMS and Connect to the Web UI

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

Note.png Try It! Connect to the Web UI

Try starting OpenNMS, and connecting to the web UI.

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