Installation:Debian

From OpenNMS
Revision as of 06:35, 18 March 2012 by Indigo (Talk | contribs)

Jump to: navigation, search


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

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:

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:

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

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 -

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

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 OpenNMS as an available install option when you run "apt-cache search opennms":

 sudo apt-get update
 apt-cache search opennms

You should see a list of OpenNMS-related packages:

 [user@host tmp] apt-cache search opennms
 opennms-doc - Enterprise-grade Open-source Network Mana... (Documentation)
 opennms-common - Enterprise-grade Open-source Network Ma... (Common Files)
 libopennms-java - Enterprise-grade Open-source Netw... (OpenNMS Libraries)
 opennms-webapp-jetty - Enterprise-grade Open-source Netw... (Jetty Web UI)
 opennms - Enterprise-grade Open-source Network Managemen... (Full Install)
 opennms-server - Enterprise-grade Open-source Network Manageme... (Daemon)

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`

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

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.

Edit your "/etc/postgresql/$PGVERSION/main/pg_hba.conf" file now, as root. It should have entries similar to the following 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 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):

 sudo /usr/sbin/service postgresql restart

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

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

It is recommended that you install the the latest Sun/Oracle JDK.

To do so, on Debian, you will need to enable the "non-free" repository. In most cases, you should be able to edit "/etc/apt/sources.list" and add "non-free" to any of the distribution's entries, next to main.

For example, if your sources.list contains this:

 deb http://http.us.debian.org/debian/ squeeze main
 deb-src http://http.us.debian.org/debian/ squeeze main
 
 deb http://security.debian.org/ squeeze/updates main
 deb-src http://security.debian.org/ squeeze/updates main
 
 # squeeze-updates, previously known as 'volatile'
 deb http://http.us.debian.org/debian/ squeeze-updates main
 deb-src http://http.us.debian.org/debian/ squeeze-updates main

...you would change it to look like this:

 deb http://http.us.debian.org/debian/ squeeze main non-free
 deb-src http://http.us.debian.org/debian/ squeeze main non-free
 
 deb http://security.debian.org/ squeeze/updates main non-free
 deb-src http://security.debian.org/ squeeze/updates main non-free
 
 # squeeze-updates, previously known as 'volatile'
 deb http://http.us.debian.org/debian/ squeeze-updates main non-free
 deb-src http://http.us.debian.org/debian/ squeeze-updates main non-free

Then, you should be able to install the "sun-java6-jdk" package with APT (as root):

 sudo apt-get update
 sudo apt-get install sun-java6-jdk

During the installation process, you will need to accept the Java licensing terms (DLJ). Not accepting this agreement will cause the installation process to fail, as OpenNMS needs a Java Environment to run.

Hint

In the latest Debian and Ubuntu releases the Oracle Java package isn't available anymore. There are two ways to install vanilla Java from Oracle in Debian/Ubuntu.

The first one is using a privately maintained repository you can install with

 sudo add-apt-repository ppa:ferramroberto/java

and install Oracle Java from there. The other one is the manual way. Download and install the binaries from Oracle. The steps to setup are here or here

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

You may see an error about IPLIKE. This is normal, it 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 "apt-get install opennms" command (as root):

 sudo apt-get -y 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:
   ... opennms-server opennms-webapp-jetty
 The following NEW packages will be installed:
   ... opennms opennms-server opennms-webapp-jetty
 0 upgraded, 13 newly installed, 0 to remove and 51 not upgraded.
 Need to get 146 MB of archives.
 After this operation, 251 MB of additional disk space will be used.
 ...
 Get:13 debian.opennms.org stable/main opennms all 1.8.17-1 [6,874 B]
 Fetched 146 MB in 2s (55.7 MB/s)     
 Preconfiguring packages ...
 Selecting previously deselected package iplike-pgsql84.
 Unpacking iplike-pgsql84 (from .../iplike-pgsql84_2.0.2-1_amd64.deb) ...
 Selecting previously deselected package opennms-db.
 Unpacking opennms-db (from .../opennms-db_1.8.17-1_all.deb) ...
 Selecting previously deselected package opennms-common.
 Unpacking opennms-common (from .../opennms-common_1.8.17-1_all.deb) ...
 ...

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. If you installed the recommended Sun/Oracle JDK, all you should need to do is point it at /usr/lib/jvm/java-6-sun:

 sudo $OPENNMS_HOME/bin/runjava -S /usr/lib/jvm/java-6-sun/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):

 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 jicmp:
  - trying to load /usr/lib64/libjicmp.so: OK
- searching for jicmp6:
  - trying to load /usr/lib64/libjicmp6.so: 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!


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

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

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 /usr/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.